alexis-regnaud / jest-preview

Debug your Jest tests. Effortlessly.🛠🖼

Jest Preview

Debug your Jest tests. Effortlessly. 🛠🖼

Try Jest Preview Online. No downloads needed!

Why jest-preview

When writing tests using Jest, we usually debug by reading the HTML code. Sometimes the HTML is too complicated and it's hard to imagine how the UI looks in our head. jest-preview initiates a server and serve your HTML in a browser, then you can see your actual UI visually. This way, it helps you debug jest tests faster.

jest-preview is initially design to work with jest and react-testing-library. However it's framework-agnostic and you can use it with any testing libraries.

Features

• 👀 Preview your actual app's HTML in a browser in milliseconds.
• 🔄 Auto reload browser when execute preview.debug().
• 💅 Support CSS:
  • ✅ Direct CSS import
  • ✅ Styled-components
  • ✅ External CSS
  • ✅ CSS Modules
  • ✅ Sass
• 🌄 Support viewing images.

How to use jest-preview in 2 lines of code

+import preview from 'jest-preview';

describe('App', () => {
  it('should work as expected', () => {
    render(<App />);
+    preview.debug();
  });
});

Or:

+import { debug } from 'jest-preview';

describe('App', () => {
  it('should work as expected', () => {
    render(<App />);
+    debug();
  });
});

Examples

• Use with Vite: Example with Vite
• Use with Create React App: Example with CRA
• Use with NextJs Rust Compiler: Example with NextJs Rust Compiler
• Use with NextJS Babel: Example with CRA

Installation

1. Install jest-preview

npm install --save-dev jest-preview
# Or
yarn add --dev jest-preview
pnpm install --dev jest-preview

2. Configure jest's transform to transform CSS and files

jest-preview comes with pre-configured transformations to handle CSS and files. This is a recommended way to configure. However, you can configure it yourself using exported transform functions as well. See Advanced configurations for more.

If you use Sass in your project, make sure sass is already installed. Note that Node Sass and LibSass are not supported.

Update jest.config.js:

transform: {
  "^.+\\.(css|scss|sass)$": "jest-preview/transforms/css",
  "^(?!.*\\.(js|jsx|mjs|cjs|ts|tsx|css|json)$)": "jest-preview/transforms/file",
}

For Create React App users, please use jest-preview/transforms/fileCRA instead of jest-preview/transforms/file. See more at examples/create-react-app/README.md

3. If you use CSS Modules, make sure it doesn't get ignored

In most cases, CSS Modules is ignored in Jest environment. For example, Create React App default configuration ignores CSS Modules via transformIgnorePatterns and moduleNameMapper. To make CSS Modules works with Jest Preview, we need to make sure it isn't ignored. Remove options to ignore CSS Modules or mapping using a third party library (such as identity-obj-proxy).

// jest.config.js
transformIgnorePatterns: [
-  '^.+\\.module\\.(css|sass|scss)$',
],
moduleNameMapper: {
-  '^.+\\.module\\.(css|sass|scss)$': 'identity-obj-proxy',
},

4. Clear your jest Cache

Since we are updating our transformation code, make sure you clear your jest cache for new changes to take effect.

./node_modules/.bin/jest --clearCache
# Or usually
npm run test -- --clearCache

5. (Optional) Configure external CSS

Sometimes, there are some CSS files imported outside your current test components (e.g: CSS imported in src/index.js, src/main.tsx). In this case, you can manually add those CSS files to jest-preview by jestPreviewConfigure. Notice that they should be path from root of your project.

  // jest.config.js
  {
    setupFilesAfterEnv: ["./config/jest/setupTests.js"],
  }

// ./config/jest/setupTests.js
import { jestPreviewConfigure } from 'jest-preview';

// Should be path from root of your project
jestPreviewConfigure({
  externalCss: [
    'demo/global.css',
    'demo/global.scss', // Sass
    'node_modules/@your-design-system/css/dist/index.min.css', // css from node_modules
    'node_modules/bootstrap/dist/css/bootstrap.min.css',
  ],
});

6. (Optional) Configure public folder

You don't need to do anything if your public folder is public. However, if it's different, you can configure as following:

// ./config/jest/setupTests.js
import { jestPreviewConfigure } from 'jest-preview';

// Should be path from root of your project
jestPreviewConfigure({
  publicFolder: 'static', // No need to configure if `publicFolder` is `public`
});

Usage

1. Update to package.json

{
  "scripts": {
    "jest-preview": "jest-preview"
  }
}

Optionally, you can use npm-run-all to run jest and jest-preview server in parallel

{
  "scripts": {
    "test:debug": "npm-run-all -p test jest-preview"
  },
  "devDependencies": {
    "npm-run-all": "latest"
  }
}

2. Run the jest-preview server

# You can use PORT to customize port, default to 3336
npm run jest-preview
# Or
yarn jest-preview
pnpm run jest-preview

3. Preview your html from jest. Following code demo how to use it with react-testing-library

import preview from 'jest-preview';

describe('App', () => {
  it('should work as expected', () => {
    render(<App />);

    userEvent.click(screen.getByTestId('increase'));
    userEvent.click(screen.getByTestId('increase'));

    // Open http://localhost:3336 to see the preview
    preview.debug();

    expect(screen.getByTestId('count')).toContainHTML('2');
  });
});

Then visit http://localhost:3336 to see the preview

Advanced configurations

You should use Pre-configured transformation in most cases. However, if you have existing code transformation, you can use following provided ones as follow:

• processCss: Process CSS files
• processFile: Process files
• processFileCRA: Process files for Create React App

For examples:

```javascript
// config/jest/cssTransform.js
'use strict';

const { processCss } = require('jest-preview');

module.exports = {
  process(src, filename) {
    return processCss(src, filename);
  },
};

// config/jest/fileTransform.js
'use strict';

const { processFile } = require('jest-preview');
// Use processFileCRA for Create React App

module.exports = {
  process(src, filename) {
    return processFile(src, filename); // Use processFileCRA for Create React App
  },
};

Upcoming features

• Support more css-in-js libraries.
• Multiple preview.
• You name it.

Run jest-preview locally

Install dependencies

npm install

To see the real demo app

npm run dev

Run jest and jest-preview simultaneously

npm run test

Open chrome at http://localhost:3336 to see the preview

However, it's recommend to run jest and jest-preview separately

npm run server # Run jest-preview server
npm run test:only # Run jest

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Hung Viet Nguyen 💻 📖 💡

Truong Nguyen 💻 📖 💡

Viet Huu Doan 🎨

HarveyNguyen ⚠️

Matt Murphy 📖

Traitanit Huangsri 💻

Thanh Son Nguyen 💻 💡 📖

This project follows the all-contributors specification. Contributions of any kind welcome!

License

MIT