Now Compatible with React V18

Chromogen is a Jest unit-test generation tool for Recoil selectors and React useState Hooks. It captures state changes during user interaction and auto-generates corresponding test suites. Simply launch your app after following the installation instructions below, interact as a user normally would, and with one click you can download a ready-to-run Jest test file.

Installation

Start by installing the Chromogen package from npm:

npm i chromogen

Scroll down if you are looking to test Hooks.

ChromogenObserver (Recoil)

Before using Chromogen, you'll need to make two changes to your application:

1. Import the <ChromogenObserver /> component as a child of <RecoilRoot />
2. Import atom and selector functions from Chromogen instead of Recoil. Chromogen has engineered atom and selector to track state changes.

Note: These changes do have a small performance cost, so they should be reverted before deploying to production.

React Component

import React from 'react';
import { RecoilRoot } from 'recoil';
import { ChromogenObserver } from 'chromogen';
import MyComponent from './components/MyComponent.jsx';

const App = (props) => (
  <RecoilRoot>
    <ChromogenObserver />
    <MyComponent {...props} />
  </RecoilRoot>
);

export default App;

By default, Chromogen uses atom & selector keys to generate import statements in the test file. If your source code variable names don't match their assigned keys (such as when using UUID), you can optionally pass a store prop containing all your import atoms & selectors.

import * as store from './store';
// ...
<ChromogenObserver store={store} />;

OR

import * as atoms from './store/atoms';
import * as selectors from './store/selectors';
import * as misc from './store/arbitraryRecoilState';
// ...
<ChromogenObserver store={[atoms, selectors, misc]} />;

Imports

import { atom, selector } from 'chromogen';

export myAtom = atom({key: 'myAtom', default: true});
export mySelector = selector({key: 'mySelector', get: ({ get }) => !get(myAtom)});

Usage

1. After installing Chromogen and following the above directions accordingly, launch your application as you normally would.

2. Two buttons will appear in the lower left corner. The play (left) button toggles test recording on and off. It will always start automatically by default. The download (right) button generates and downloads the test file containing all cumulative recorded tests.

3. After completing all the interactions you'd like to test, click the download button and drag-and-drop the resulting file into your application's test folder.

4. Before running any tests, you'll need to update the line <ADD STORE FILEPATH> with the correct filepath to your Recoil store.

HooksChromogenObserver (React Hooks)

Before using Chromogen, you'll need to make two changes to your application:

1. Import the <HooksChromogenObserver /> component and wrap it around the parent most <App />
2. Import useState function from Chromogen instead of React. Chromogen has engineered useState to track state changes.

React Component

To track state changes in your application's useState Hooks, import HooksChromogenObserver in index.js (or the file your application's uppermost parent component is stored) and wrap it around your App. Now Chromogen's useState will become available throughout your app.

import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';
import { HooksChromogenObserver } from 'chromogen';

const root = createRoot(document.getElementById('root'));

root.render(
  <HooksChromogenObserver name="App">
    <App />
  </HooksChromogenObserver>
);

By default, Chromogen requires a second parameter in the useState hooks as id to generate a test suite for the user's application.

Wherever you import useState from React in your file, import useState from Chromogen instead. To have Chromogen track your application's state changes and generate a test suite, import Chromogen's useState:

import React from 'react';
import { useState as hooksUseState } from 'chromogen';

const App: React.FC = () => {
  const [elements, setElements] = hooksUseState<number>(0, "id");
  return (...)
};

Coverage

Chromogen produces unit tests for the useState Hook and synchronous Recoil selectors, including readonly selectors, writeable selectors, and selectorFamilies (coming soon). Currently, it does not generate tests for any other Hooks or asynchronous selectors due to their unique mocking requirements; Chromogen identifies and excludes these cases at runtime without issue.

DevTool

Refer to Chromogen's README for downloading this improved DevTool!

Chromogen is currently in active Beta

Please visit our main repo for more detailed instructions, as well as any bug reports, support issues, or feature requests.