@highpoint/frontend-testing

Highpoint React Frontend Testing Package

This package installs all of the necessary dependencies for Storybook.js and Cypress and includes presets and configuration for documenting and unit testing react components.

What You Get

• Storybook.js component documentation and development tool with preconfigured webpack config & additional settings (automatically detects and includes stories defined in *.stories.(ts|js|tsx|jsx) files anywhere in your project)

  • yarn hpt-storybook - Run the local storybook webserver
  • yarn hpt-storybook-build - Build a static version of the storybook

• Cypress testing preconfigured with unit testing support, snapshot testing, cypress-axe a11y testing, and automatic report generation (automatically detects and includes tests defined in *.test.(ts|js|tsx|jsx) files)

  • yarn hpt-cypress-open - Preconfigured cypress open
  • yarn hpt-cypress-run - Preconfigured cypress run w/ report generation

Essentially you get everything you need to develop, unit test, and document a frontend react app with all dependencies and configuration under the hood. :sunglasses:

Installation

1. Install the package

   yarn add --dev @highpoint/frontend-testing
   

   
   

2. Add the following scripts to package.json. These can be used to run/build Storybook and Cypress.

   {
     "storybook": "hpt-storybook",
     "storybook:build": "hpt-storybook-build",
     "test": "hpt-cypress-open",
     "test:run": "hpt-cypress-run"
   }
   

   
   

3. Add the Cypress types to your project's tsconfig.json includes array

   {
     "includes": [..., "node_modules/@gjoneshpt/cypress-plugin-snapshots/types", "node_modules/cypress/types"]
   }
   

   
   

4. Add a .storybook folder to the root folder of the consuming project.

   • In that folder, add a main.ts file. Paste in this code:

     const main = require('@highpoint/frontend-testing/.storybook/main');
     require('@babel/polyfill');
     const webpack = require('../webpack.config');
     
     module.exports = {
       ...main, 
       webpackFinal: async (config, { configType }) => {
     
       // Add consuming project's webpack resolve modules config
       if(typeof(webpack) === 'function') {
         const baseWebpackConfig = webpack({}, configType.toLowerCase());
         
         if(baseWebpackConfig.resolve.modules)
         config.resolve.modules = baseWebpackConfig.resolve.modules;
       }
     
       // Return the altered config
       return config;
     }};
     

   • Also in the .storybook folder, add a preview.ts file. Paste in this code:

     import { preview } from '@highpoint/frontend-testing';
     export const Decorator = preview.Decorator;
     export const decorators = preview.decorators;
     export const parameters = preview.parameters;
     

   • Also in .storybook, add a preview-head.html file. Paste in this code:

     <link href="https://fonts.googleapis.com/css?family=IBM+Plex+Sans:100,200,300,400,500,600,700&display=swap" rel="stylesheet">
     <style>
       html, body, #root {
         height: 100%;
       }
     
       
     .sbdocs-preview {
       background-color: #f5f6fa !important;
     }
     
       @media print {
         #root, #docs-root {
           display: none !important;
         }
       }
     </style>
     

   • Also in .storybook, add a manager.ts file. Paste in this code:

     import { addons } from '@storybook/addons';
     import { theme } from '@highpoint/frontend-testing';
     
     addons.setConfig({
       theme: theme
     });
     

5. Thats it, you're ready to run Storybook and Cypress! Run yarn storybook to run the local storybook server and yarn test to open the cypress test runner.

---

Storybook and Cypress Unit Testing

Storybook and Cypress play well together!

When you write storybook story for a component, you are essentially writing a test specification for it. Each component should have multiple stories with different variations of props passed to it. Exporting a story from a *.stories.(tsx|jsx) file adds it to the storybook. (See storybook docs for more details)

Say we have some component called HelloWorld. Our stories file could look like this:

// HelloWorld.stories.tsx

import React from 'react';
import { HelloWorld } from '.';

export default {
  title: 'HelloWorld',
  component: HelloWorld,
  parameters: {
    componentSubtitle: 'This is the HelloWorld component.',
  }
};

const Template = (args) => <HelloWorld {...args} />;

export const Standard = Template.bind({});
Standard.args = {
  myProp: 1
}

export const Different = Template.bind({});
Different.args = {
  myProp: 2
}

Storybook automatically detects the exported stories and adds them to the storybook, but we can also import these stories into our test files and test directly against them. This means that when we write our stories, we are not only defining our component documention but also our test cases! So our test file can look like this:

// HelloWorld.test.tsx

import React from 'react';
// This mount function is the same as the mount function in 'cypress-react-unit-test' except it also renders a decorator with the @highpoint/ui-elements theme provider.
import { mount } from '@highpoint/frontend-testing';
import { Standard, Different } from './HelloWorld.stories';

describe('HelloWorld', () => {
  
  it('Standard', () => {
    // Note we have to pass the story args to the component
    mount(<Standard {...Standard.args} />);
    cy.document().toMatchImageSnapshot();
  });

  
  it('Different', () => {
    mount(<Different {...Different.args} />);
    cy.document().toMatchImageSnapshot();
  });

});

Component stories and tests should both be placed inline with the component definitions. So for our HelloWorld component, the file structure should look like this:

project  
│
└───components
    └───HelloWorld
        │   index.tsx
        │   HelloWorld.stories.tsx
        │   HelloWorld.test.tsx

---

Configuration

Storybook

You can modify any configuration in main.ts and preview.ts by overriding any field on the storybookDefaults object:

// Note, to use jsx syntax, rename the preview file to preview.tsx
/* preview.tsx */

import { preview } from '@highpoint/frontend-testing';
export const Decorator = preview.Decorator;
export const decorators = preview.decorators.concat([Story => <NotificationMananger><Story /></NotificationManager>]);
export const parameters = preview.parameters;

or

/* main.ts */

const main = require('@highpoint/frontend-testing/.storybook/main');
require('@babel/polyfill');
const webpack = require('../webpack.config');

module.exports = {
  ...main, 
  // Use different stories glob
  stories: ['../src/**/*.stories.@(ts|tsx|js|jsx|mdx)']
  webpackFinal: ...
};

Cypress

Configuration options to come...