Abacus: Automattic's Experimentation Platform UI
Getting Started
Requirements
npm
Update Your System Host File
In order for our OAuth authorization to work, it needs to be given a redirect URI that has been declared as acceptable. In order to aid with using the site locally, add the following DNS mapping to your system's host file.
127.0.0.1 a8c-abacus-local
Spin up your Development server
npm install
npm run dev
Check your code
# Run all tests and checks
npm run verify
# Code testing
npm run test:all
npm run test:e2e
npm run test:e2e -- --watch
npm run test:e2e -- --updateSnapshot
npm run test:integration
npm run test:integration -- --watch
npm run test:integration -- --updateSnapshot
npm run test:unit
npm run test:unit -- -- --watch
npm run test:unit -- -- --updateSnapshot
DEBUG_PRINT_LIMIT=30000 npm run test:unit # For when react-test-library truncates your debug output
# Code formatting
npm run format:check
npm run format # Fixes formatting
# Code linting
npm run lint
npm run lint:ts:fix # Fixes lint issues
Build for Deployment
npm run build
Testing Tips/Notes
Where to find tests
- Integration:
/__tests__
- E2E:
/e2e
- Unit tests: Rest of the codebase, alongside file it is testing.
E2E Testing tips
Our e2e tests use Jest and Puppeteer in a headless Chrome browser.
Smoke Tests:
We have smoke tests that are inteded to be used in development for quick iterations.
npm run test:e2e:smoke
Debugging
For debugging, you'll likely want to run with a full visual browser. To do that:
- Create a .env file at the project's root if it does not already exist. You can copy the .env.example file as an initial template.
- Add
PUPPETEER_HEADLESS=false
. This will cause the E2E tests to run in a browser that can be visually seen.
See https://developers.google.com/web/tools/puppeteer/debugging for more debugging tips.
Use Production Config/APIs
Since we don't have a mock server it is important to test on the Production config/APIs.
To do so, spin up your dev server like this:
REACT_APP_PRODUCTION_CONFIG_IN_DEVELOPMENT=true npm run dev
See /config.ts
for more info.
Auth Flow
We don't currently have a log-out feature but it can be necessary to log a user out for testing, this is how to do so manually:
Once a user is authenticated and they authorize Abacus to have access, we save the authorization info in local storage under the key experiments_auth_info
. To simulate using Abacus on a new browser or the access token expiring, you can remove this item from local storage using the Chrome devtools > Application tab.
Pre-Commit Hooks
Pre-commit hooks have been put in place via husky
which will run the precommit
NPM script. This script runs lint-staged
but could be used to run different or more commands. The lint-staged
command will run commands on only the staged files of the commit according to the configuration. The lint-staged
configuration is in package.json
.
Storybook
Storybook allows you to render components in isolation.
This is useful when building components. It allows you to create "stories" for the various states that the component can be in.
Storybook can be used for other purposes too. You could run e2e tests on it to ensure components are functioning as expected. It could be used to render a style guide too.
To run Storybook:
npm run storybook
This will open a browser window of the Storybook webapp.
"DebugMode"
We currently have a special debug mode which adds in-development features as well as extra debug information. To activate it hold shift and double click on the footer.
Advanced Tools
Docker (Not Recommended)
You can use the following commands to run the server in a Docker container:
npm run docker-build
: Build a docker image that runs a production Abacus server at port 3000.npm run docker-start
: Run the above docker image, mapping port 3000 from the image to port 8888 on your local machine.
Bundle Analysis (Not Recommended)
Shouldn't be a concern for this App
The Next.js build creates two bundles of files. One for the client and one for the server.
Running the following will build, analyze, and open two browser windows with a report on the client and server bundles.
npm run analyze