Package Exports

jest-preview
jest-preview/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (jest-preview) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Jest Preview Logo

Jest Preview

Debug your Jest tests. Effortlessly. 🛠🖼

Jest Preview Demo

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 complex 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();
  });
});

Examples

Use with Vite: Example with Vite
Use with Create React App: 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. Create `cssTransform.js` and `fileTransform.js`

// 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');

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

For Create React App users, please use processFileCRA instead of processFile. See more at examples/create-react-app/README.md

3. Configure jest's transform to intercept CSS and files

// jest.config.js
transform: {
    "^.+\\.css$": "<rootDir>/config/jest/cssTransform.js",
    "^(?!.*\\.(js|jsx|mjs|cjs|ts|tsx|css|json)$)": "<rootDir>/config/jest/fileTransform.js",
  },

4. 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

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

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',
    'node_modules/@your-design-system/css/dist/index.min.css',
    'node_modules/bootstrap/dist/css/bootstrap.min.css',
  ],
});

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');
  });
});