What is Chromogen?

Few developers take pleasure in writing unit tests. Time spent assembling boilerplate code and creating countless assertions constitutes time away from doing what we really love – building the application itself. Yet most developers understand the importance of testing. Comprehensive test coverage (mostly) guarantees that your application is functioning as expected, and will continue to do so as your codebase matures. With proper testing in place, your team can iterate quickly, spending less time on bug fixes and more energy on new features. Your inner perfectionist can find rest easy knowing that any changes introduced by colleagues are vetted by the judicious tests in your application’s test suites.

Chromogen is a recently launched open-source tool that aims to spare developers the monotony of writing state-based unit tests. To do so, Chromogen generates meaningful, comprehensive Jest tests as you interact with your running application. Because the tool is interaction-driven, the generated tests reflect the way an end-user will experience your app. This allows the tests to skirt the over-emphasis on implementation details that commonly plagues well-meaning test-writers.

What tests does Chromogen generate?

Chromogen is tailored to React apps that employ the hottest new state management library: Recoil.js. Released in May 2020 by Facebook, Recoil is simple, performant, easy to learn, and requires little boilerplate. At the crux of the Recoil API are two concepts used to manage global state: atom and selector functions. An atom constitutes a piece of state, while a selector is a pure function that accepts atoms (or other selectors) as input and returns derived data. Components can easily subscribe to an atom or selector using Recoil’s provided hooks.

Though steadily evolving, the Recoil ecosystem offers scant tooling for testing its implementation. Powerful and easy to use, Chromogen presents a much-needed contribution to the Recoil developer's toolkit by generating an assortment of test suites that ensure your Recoil atoms and selectors render, update, and set state properly.

How can I use Chromogen?

I. npm install chromogen

Getting started with Chromogen is simple: after installing the npm package, nest Chromogen's wrapper component within <RecoilRoot />, and update your Recoil imports (full instructions here). A basic button GUI will render in the bottom-left of your application’s view. To start generating tests, simply interact with stateful pieces of your application. For repetitive changes to the same state, you can toggle recording on and off by clicking the red button. When you’re finished, click the green button to download a complete Jest test file. You can then drag and drop the file into your application’s test directory. Before running your test command, update the import statement at the top of the file with the correct relative path to your Recoil store.

II. (optional) Download the Chrome extension!

If you prefer to use Chromogen without rendering the button component to your application UI, the Chromogen team has developed a Chrome DevTools extension that offers the same functionality. It is currently under publishing review by Chrome and is anticipating approval within the next few weeks. Once approved, you’ll be able to download it for free from the Chrome Web Store. Once installed, Chromogen can intelligently detect when the accompanying panel has been opened, removing the GUI from your application view.

Under the hood: how does it work?

Chromogen provides shadow methods that mimic Recoil's native atom and selector functions – with a bit of tracking logic interjected. These methods allow the package to record atom and selector calls. On each call, Chromogen's wrapper component employs Recoil's useRecoilTransactionObserver API to capture state updates and map them to recorded atom and selector invocations. Ultimately, this recorded data is passed into Chromogen's test-composing algorithm to generate your test file.

Chromogen is available now to npm install in your existing Recoil app, or check out our repo for a pre-configured demo application. The Chromogen team welcomes contributions and feedback via GitHub.