Testing
Jest for unit testingβ
Supporting server-only testsβ
We support server and client testing based on the following naming convention:
- A test named
myTest.test.ts
will be executed in a JSDOM environment (~ like a browser). Use as a default for React components and generic utility code. - A test named
myTest.test.server.ts
, or any test located within aserver
folder, will be executed only in the Node server environment. Use to test your Graphql resolvers for instance.
React Testing libraryβ
We have preinstalled React Testing Library and React Testing Hooks.
Tests for Vulcan Next (for contributors only)β
We have a unit tests for some key features and scripts of VN, through the tests/vn
folder.
This folder is ignored when running yarn run test:unit
, to avoid bloating your own tests.
MDX parsing, magic imports with ~β
jest-transformer-mdx allow importing .mdx also in Jest
.env supportβ
Load .env
config automatically in Jest,
see Jest globalSetup.
Unified testing patternsβ
We strive to unify testing patterns between Cypress and Jest where it makes sense.
First, add React Testing queries into Cypress, so you can fetch elements with similar patterns. Check React Testing docs for example of the reverse approach (data-cy in React Testing).
Unified test coverageβ
We followed awesome recommandations from Bahmutov to unify Cypress and Jest coverage. This is crucial to have a clearer vision of what is correctly tested in your application, whatever the test method is. For instance, e2e tests provides a huge coverage for React components, while unit tests are more efficient for helpers, hooks and functions.
yarn run coverage
will run tests and compute the unified report in coverage
.
yarn run reports:combined
will compute the combined report without running tests.
Cypress for e2e testingβ
Run Next in test modeβ
Run yarn start:test
or yarn dev:test
to run your Next server in Test mode. This will in particular load .env.test
environment config and set NODE_ENV
to "test".
TypeScript and vanilla JS (+ESLint)β
Custom commands, with TypeScriptβ
You can write JavaScript tests and still enjoy auto-completion of custom commands, thanks to TS triple slash directives.
Reuse app Webpack configβ
You may want your Cypress code to be as powerful as your app code. For this, we are enhancing the Cypress webpack config with the same features as in the app.
Example from Cypress with TS + Webpack
Code coverageβ
See Cypress Code Coverage example for TS, Cypress Next example, Cypress TS example...
Note: doc of NYC for TS has to be followed carefully (computing sourceMaps for TS code, installing all sibling packages...). The difficult part is instrumentation.
Code coverage is totally disabled client-side when simply running tests, using "CYPRESS_coverage" variable (thanks @bahmutov).
No screenshot/videos as a defaultβ
For some reason, Cypress:run will automatically store videos of test run. We disabled this behavior in the config as it may bloat CI/CD.
Import from your codeβ
We use Cypress Webpack Preprocessor, to enhance Cypress build with similar options as the actual app.
We use ts-loader
, with transpileOnly
option to fasten build. We expect your e2e tests typing to be correct at run time.
Pure SSR testingβ
The cy.visitAsHtml()
command allow to check the pure HTML render of a page. It will disable JS in the the page automatically.
Note: at the time of writing (2020/06) there is an open issue when needing this command in multiple tests
Loads .env.development the same way next doesβ
We use a plugin that will in turn rely on Next.js dotenv loading capabilities.
Used for instance to load the default admin user credentials in tests.
As a default, it will use development values from .env.development
.
Intercept emailsβ
Vulcan Next embeds the setup described in the following official tutorial on how to test mail workflows in Cypress.
Cypress will automatically run a test mail server on http://localhost:7777
and can intercept mails via the "getMail" task.
See e2e tests for the authentication workflow to get some usage examples.
Storybookβ
Webpack 5 and TypeScript configβ
You can write your Storybook config as normal TypeScript files and even import your local code.
NOTE: installing ts-node
may break Storybook, see this Stack Overflow ticket
Same import as in Nextβ
We reuse our Webpack config extension function, so you can enjoy magic imports and isomorphic imports in Storybook too.
Styling with Styled JSX and CSS Modulesβ
Note: CSS modules are currently not appearing correctly in Storybook, see vulcan-next/issues/20
Public folderβ
Storybook is aware of the public
folder, so it will display images accordingly.
I18nβ
We reuse the same i18n config as in the app, so your stories will be internationalized automatically.
Webpack bundle analyzer for storybookβ
There is nothing worse than a slow Storybook build, you can debug your Webpack bundle using yarn run analyze-bundle:storybook
Mock packagesβ
See .storybook/mocks/packages
and .storybook/main.js
, we use Webpack alias to load them. Thus, you can use components that rely on next/config
for instance.
We use Storybook Addon Next Router for mocking the router.
Chromatic configurationβ
We don't usually recommend third party services, but Chromatic is really an excellent addition to any developer workflow.
Set the CHROMATIC_PROJECT_TOKEN
environment variable in .env.development.local
and then run yarn run chromatic
.