Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/open-source-labs/Chromogen
UI-driven Jest test-generation package for Recoil selectors and Zustand store hooks
https://github.com/open-source-labs/Chromogen
jest react recoil testing-tools zustand
Last synced: 3 months ago
JSON representation
UI-driven Jest test-generation package for Recoil selectors and Zustand store hooks
- Host: GitHub
- URL: https://github.com/open-source-labs/Chromogen
- Owner: open-source-labs
- License: mit
- Created: 2020-08-07T23:57:50.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2023-03-02T22:33:14.000Z (over 1 year ago)
- Last Synced: 2024-07-06T05:40:09.330Z (4 months ago)
- Topics: jest, react, recoil, testing-tools, zustand
- Language: TypeScript
- Homepage:
- Size: 29.4 MB
- Stars: 278
- Watchers: 8
- Forks: 51
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
A UI-driven test-generation package for Zustand Stores and Recoil.js selectors.
[](https://www.npmjs.com/package/chromogen)
[](https://github.com/open-source-labs/Chromogen/blob/master/LICENSE)
[](https://twitter.com/intent/tweet?text=CHROMOGEN%20-%20A%20UI-driven%20Jest%20test%20generator%20for%20Recoil%20apps%0A&url=https://www.npmjs.com/package/Chromogen&hashtags=React,Recoil,Jest,testing)
[](http://makeapullrequest.com)
[](https://www.npmjs.com/package/chromogen)
[](https://github.com/open-source-labs/Chromogen)
## Table of Contents
- [Overview](#overview)
- [Supported Tests](#supported-tests)
- [Installing the Package](#installing-the-package)
- [Installation for Zustand Apps](#installation-for-zustand-apps)
- [Installation for Recoil Apps](#installation-for-recoil-apps)
- [Usage for All Apps](#usage-for-all-apps)
- [Contributor Setup](#contributor-setup)
- [Test Setup](#test-setup)
- [CI/CD with Jenkins](#jenkins)
- [Demo Apps](#demo-apps)
- [Contributing](#contributing)
- [Core Team](#core-team)
- [License](#license)
## Overview
You're an independent developer or part of a lean team. You want reliable unit tests for your new Zustand or React-Recoil app, but you need to move fast and time is a major constraint. More importantly, you want your tests to reflect how your users interact with the application, rather than testing implementation details.
[Enter Chromogen - Now on version 4.0](https://www.npmjs.com/package/chromogen). Chromogen is a Jest unit-test generation tool for Zustand Stores and Recoil selectors. It captures state changes during user interaction and auto-generates corresponding test suites. Simply launch your application 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. Alternatively, you can copy the generated tests straight to your clipboard.
Chromogen is now compatible with React V18!
## Supported Tests
Zustand Tests
Chromogen currently supports two types of testing for Zustand applications:
1. **Initial Store State** on page load.
2. **Store State Changes** whenever an action is invoked on the store.
On initial render, Chromogen captures store state as a whole and keeps track of any subsequent state changes. In order to generate tests, you'll need to make some changes to how your store is created.
To use Chromogen with your Zustand application, please see the [Installation for Zustand Apps](#installation-for-zustand-apps) section below.
Recoil Tests
Chromogen currently supports three main types of tests for Recoil apps:
1. **Initial selector values** on page load
2. **Selector return values** for a given state, using snapshots captured after each state transaction.
3. **Selector _set_ logic** asserting on resulting atom values for a given `newValue` argument and starting state.
These test suites will be captured for _synchronous_ selectors and selectorFamilies only. However, the presence of asyncronous selectors in your app should not cause any issues with the generated tests. Chromogen can identify such selectors at run-time and exclude them from capture.
At this time, we have no plans to introduce testing for async selectors; the mocking requirements are too opaque and fragile to accurately capture at runtime.
By default, Chromogen uses atom and selector keys to populate the import & hook statements in the test file. If your source code does _not_ use matching variable and key names, you will need to pass the imported atoms and selectors to the Chromogen
component as a `store` prop. The installation instructions below contain further details.
## Installing the Package
```
npm install chromogen
```
## Installation for Zustand Apps
Before using Chromogen, you'll need to make two changes to your application:
1. Import the `` component and render it alongside any other components in ``
2. Import `chromogenZustandMiddleware` function from Chromogen. This will be used as middleware when setting up your store.
### Import the ChromogenZustandObserver component
Import `ChromogenZustandObserver`. ChromogenZustandObserver can be rendered alongside any other components in ``.
```jsx
import React from 'react';
import { ChromogenZustandObserver } from 'chromogen';
import TodoList from './TodoList';
const App = () => (
<>
>
);
export default App;
```
Import `chromogenZustandMiddleware`. When you call create, wrap your store function with chromogenZustandMiddleware. **Note**, when using chromogenZustandMiddleware, you'll need to provide some additional arguments into the set function.
1. _Overwrite State_ (boolean) - Without middleware, this defaults to `false`, but you'll need to explicitly provide a value when using Chromogen.
2. _Action Name_ - Used for test generation
3. _Action Parameters_ - If the action requires input parameters, pass these in after the Action Name.
```jsx
import { chromogenZustandMiddleware } from 'chromogen';
import create from 'zustand';
const useStore = create(
chromogenZustandMiddleware((set) => ({
counter: 0,
color: 'black',
prioritizeTask: ['walking', 5],
addCounter: () => set(() => ({ counter: (counter += 1) }), false, 'addCounter'),
changeColor: (newColor) => set(() => ({ color: newColor }), false, 'changeColor', newColor),
setTaskPriority: (task, priority) =>
set(() => ({ prioritizeTask: [task, priority] }), false, 'setTaskPriority', task, priority),
})),
);
export default useStore;
```
## Installation for Recoil Apps
Before running Chromogen, you'll need to make two changes to your application:
1. Import the `` component as a child of ``
1. Import the `atom` and `selector` functions from Chromogen instead of Recoil
Note: These changes do have a small performance cost, so they should be reverted before deploying to production.
### Import the ChromogenObserver component
ChromogenObserver should be included as a direct child of RecoilRoot. It does not need to wrap any other components, and it takes no mandatory props. It utilizes Recoil's TransactionObserver Hook to record snapshots on state change.
```jsx
import React from 'react';
import { RecoilRoot } from 'recoil';
import { ChromogenObserver } from 'chromogen';
import MyComponent from './components/MyComponent.jsx';
const App = (props) => (
);
export default App;
```
If you are using pseudo-random key names, such as with _UUID_, you'll need to pass all of your store exports to the ChromogenObserver component as a `store` prop. This will allow Chromogen to use source code variable names in the output file, instead of relying on keys. When all atoms and selectors are exported from a single file, you can pass the imported module directly:
```jsx
import * as store from './store';
// ...
;
```
If your store utilizes seprate files for various pieces of state, you can pass all of the imports in an array:
```jsx
import * as atoms from './store/atoms';
import * as selectors from './store/selectors';
import * as misc from './store/arbitraryRecoilState';
// ...
;
```
### Import atom & selector functions from Chromogen
Wherever you import `atom` and/or `selector` functions from Recoil (typically in your `store` file), import them from Chromogen instead. The arguments passed in do **not** need to change in any away, and the return value will still be a normal RecoilAtom or RecoilSelector. Chromogen wraps the native Recoil functions to track which pieces of state have been created, as well as when various selectors are called and what values they return.
```js
import { atom, selector } from 'chromogen';
export const fooState = atom({
key: 'fooState',
default: {},
});
export const barState = selector({
key: 'barState',
get: ({ get }) => {
const derivedState = get(fooState);
return derivedState.baz || 'value does not exist';
},
});
```
## Usage for All Apps
After following the installation steps above, launch your application as normal. You should see two buttons in the bottom left corner.
The pause button on the left is the **pause recording** button. Clicking it will pause recording, so that no tests are generated during subsequent state changes. Pausing is useful for setting up a complex initial state with repetitive actions, where you don't want to test every step of the process.
The button in the middle is the **download** button. Clicking it will download a new test file that includes _all_ tests generated since the app was last launched or refreshed.
The button on the right is the **copy-to-clipboard** button. Clicking it will copy your tests, including _all_ tests generated since the app was last launched or refreshed.
Once you've recorded all the interactions you want to test, click the pause button and then the download button to generate the test file or press copy to copy to your clipboard. You can now drag-and-drop the downloaded file into your app's test directory or paste the code in your new file. **Don't forget to add the source path in your test file**
You're now ready to run your tests! After running your normal Jest test command, you should see a test suite for `chromogen.test.js`.
The current tests check whether state has changed after an interaction and checks whether the resulting state change variables have been updated as expected.
## Contributor Setup
In order to make/observe changes to the code, you'll have to run Chromogen locally as opposed to running via NPM.
Due to inconsistencies across different machines, it is recomended to use the following method to run Chromogen locally.
**Run for demos within this directory**
After cloning the repo,
```jsx
npm install
```
from BOTH the /package directory (where the app lives) AND the /demo directory you're developing with.
Then, and ONLY then, run
```jsx
npm run tarballUpdate
```
**Run for local applications outside this directory**
After cloning this repo, add the following script to your app's package.json:
```jsx
"tarballUpdate": "npm --prefix run build && npm pack && npm uninstall chromogen && npm install ./chromogen-5.0.1.tgz && npm start"
```
## Test Setup
### Zustand Test Setup
Before running the test file, you'll need to specify the import path for your store by replacing ``. The default output assumes that all stores are imported from a single path; if that's not possible, you'll need to separately import each set of stores from their appropriate path.
| **BEFORE** | **AFTER** |
| :-------------------------------------------------------------------: | :-------------------------------------------------------------------: |
|  |  |
---
### Recoil Test Setup
Before running the test file, you'll need to specify the import path for your store by replacing ``. The default output assumes that all atoms and selectors are imported from a single path; if that's not possible, you'll need to separately import each set of atoms and/or selectors from their appropriate path.
| **BEFORE** | **AFTER** |
| :-----------------------------------------------------------: | :----------------------------------------------------------: |
|  |  |
You're now ready to run your tests! Upon running your normal Jest test command, you should see three suites for `chromogen.test.js`:
**Initial Render** tests whether each selector returns the correct value at launch. There is one test per selector.
**Selectors** tests the return value of various selectors for a given state. Each test represents the app state after a transaction has occured, generally triggered by some user interaction. For each selector that ran after that transaction, the test asserts on the selector's return value for the given state.
**Setters** tests the state that results from setting a writeable selector with a given value and starting state. There is one test per set call, asserting on each atom's value in the resulting state.
## CI/CD with Jenkins
You will need to have Docker installed to run Jenkins. Ru the following command to create a bridge network for Jenkins:
```jsx
docker network create jenkins
```
Enable Docker commands to be executable with Jenkins nodes:
```jsx
docker run \
--name jenkins-docker \
--rm \
--detach \
--privileged \
--network jenkins \
--network-alias docker \
--env DOCKER_TLS_CERTDIR=/certs \
--volume jenkins-docker-certs:/certs/client \
--volume jenkins-data:/var/jenkins_home \
--publish 2376:2376 \
--publish 3003:3003 --publish 5003:5003 \
docker:dind \
--storage-driver overlay2
```
Build a Docker image from the DOckerfile within Chromogen:
```jsx
docker build -t chromogen-jenkins .
```
Run your Chromogen-Jenkins image in Docker as a container:
```jsx
docker run \
--name jenkins-blueocean \
--detach \
--network jenkins \
--env DOCKER_HOST=tcp://docker:2376 \
--env DOCKER_CERT_PATH=/certs/client \
--env DOCKER_TLS_VERIFY=1 \
--publish 8080:8080 \
--publish 50000:50000 \
--volume jenkins-data:/var/jenkins_home \
--volume jenkins-docker-certs:/certs/client:ro \
--volume "$HOME":/home \
--restart=on-failure \
--env JAVA_OPTS="-Dhudson.plugins.git.GitSCM.ALLOW_LOCAL_CHECKOUT=true" \
myjenkins-blueocean:2.375.3-1
```
Navigate to your localhost:8080 and enter the password (between the two sets of asterisks) that is generated from the following command:
```jsx
docker logs jenkins-blueocean
```
Create your first administrator user.
Stop and start your Docker container using one of the following:
```jsx
docker stop jenkins-blueocean jenkins-docker
docker start jenkins-blueocean jenkins-docker
```
When configuring your pipeline, make sure to set your pipeline definition to 'Pipeline Script from SCM' and enter the path to your local repositiory, specify the brand you are working from, set the Script Path to 'jenkins/Jenkinsfile', and uncheck 'Lightweight Checkout'.
## Demo Apps
### Zustand Demo To-Do App
Chromogen's open-source Zustand demo app provides a Zustand-based frontend with multiple store properties and actions to test. You can access this demo application here, and view the source code in the `demo-zustand-todo` folder of this repository.
### Recoil Demo To-Do App
Chromogen's official Recoil demo app provides a ready-to-run Recoil frontend with a number of different selector implementations to test against. It's available in the `demo-todo` folder of this repository and comes with Chromogen pre-installed; just run `npm install && npm start` to launch.
## Contributing
**We expect all contributors to abide by the standards of behavior outlined in the [Code of Conduct](CODE_OF_CONDUCT.md).**
We welcome community contributions, including new developers who've never [made an open source Pull Request before](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github). If you'd like to start a new PR, we recommend [creating an issue](https://docs.github.com/en/github/managing-your-work-on-github/creating-an-issue) for discussion first. This lets us open a conversation, ensuring work is not duplicated unnecessarily and that the proposed PR is a fix or feature we're actively looking to add.
## Bugs
Please [file an issue](https://docs.github.com/en/github/managing-your-work-on-github/creating-an-issue) for bugs, missing documentation, or unexpected behavior.
## Feature Requests
Please file an issue to suggest new features. Vote on feature requests by adding
a đź‘Ť. This helps us prioritize what to work on.
## Questions
For any questions and concerns related to using the package, feel free to email us via `[email protected]`.
## Chromogen V5.0 updates
**GUI Overhaul**
**Why?**
*Hovering GUI blocked functionality of host app
*Recording/downloading interactivity was cumbersome and inflexible
*Suboptimal for CI/CD implementation Buttons not functional
**What?**
*Discrete Collapsible IDE that allows for real-time observation & manual interactivity of generated tests
**Next steps:**
*Recording button functionality
**Real-time feed rendering**
**Why?**
*Generated tests were only accessible as a monolith of text, preventing isolation of individual components’ tests
**What?**
*IDE updates in real-time as changes of state are recorded
**Next steps:**
*Test categorization.
*Filter groups of tests by:
*Initialization vs ΔState Action
*Description
*and allow user to select which filter to apply to displayed generated tests.
**CI/CD overhaul**
**Why?**
*Travis implementation not functional
**What?**
*Re-implemented CI/CD with Jenkins
**Additional Next Steps**
**Add functionality for Zustand multi-store rendering & Asynchronous state**
**Docker containerization**
**Why?**
*V 4.0 presented inconsistencies when accessed from different local machines.
This hindered team workflow both with development and production-use
**What?**
*Containerization of app ensures homogenous, improved User/Dev experience
## Core Team
Brach Burdick
Francois Denavaut
Maggie Kwan
Lawrence Liang
Michelle Holland
Andy Wang
Connor Rose Delisle
Jim Chen
Amy Yee
Jinseon Shin
Ryan Tumel
Cameron Greer
Nicholas Shay
Marcellies Pettiford
Sung Kim
Lina Lee
Erica Oh
Dani Almaraz
Craig Boswell
Hussein Ahmed
Ian Kila
Yuehao Wong
## LICENSE
Logo crafted with [AdobeExpress](https://www.adobe.com/express/)
README format adapted from [react-testing-library](https://github.com/testing-library/react-testing-library/blob/master/README.md) under [MIT license](https://github.com/testing-library/react-testing-library/blob/master/LICENSE).
All Chromogen source code is [MIT](./LICENSE) licensed.
Lastly, shoutout to [this repo](https://github.com/conorhastings/redux-test-recorder) for the original inspiration.