Running Betterer
You can run Betterer with the Betterer CLI. If you used npx @betterer/cli init to add Betterer to your project, @betterer/cli will already be added as a dependency, and there will be a betterer script in your package.json file.
Start mode
If you just want to run your tests once (like before commiting your code), you can use betterer start or just betterer:
- Yarn
- npm
Run yarn betterer start or just yarn betterer to run Betterer once.
Run npm run betterer start or just npm run betterer to run Betterer once.
Betterer will run your tests, compare the new results against the expected results, and report the updated status. If any test result is better, the .betterer.results file will be updated with the new result ✅! If it gets worse, your test will fail and Betterer will throw an error ❌!
If it is your first time running a Betterer test it will create a .betterer.results file!
Including and excluding files
If you want to test specific files, you can pass a file path or glob directly to the start command.
If you include files with a generic glob and want to exclude a specific file, you can use the --exclude option, which can take multiple values. Each exclude pattern should be a regular expression.
Examples
- Yarn
- npm
Run yarn betterer "src/**/*.js" to run Betterer on all JavaScript files within src.
Run yarn betterer "src/**/*.js" "src/**/*.css" to run Betterer on all JavaScript and CSS files within src.
Run yarn betterer "src/**/*.js" "src/**/*.css" --exclude excluded.js to run Betterer on all JavaScript and CSS files within src, but not any files called excluded.js.
Run npm run betterer "src/**/*.js" to run Betterer on all JavaScript files within src.
Run npm run betterer "src/**/*.js" "src/**/*.css" to run Betterer on all JavaScript and CSS files within src.
Run npm run betterer "src/**/*.js" "src/**/*.css" --exclude excluded.js to run Betterer on all JavaScript and CSS files within src, but not any files called excluded.js.
Betterer will only run File Tests when targeting specific files.
Start options
You can pass the following options to start:
| Option | Description | Default |
|---|---|---|
--cache | When present, Betterer will only run on changed files. | false |
--cachePath [value] | Path to Betterer cache file relative to CWD | ./.betterer.cache |
-c, --config [value] | Path to test definition file relative to CWD. Takes multiple values | ./.betterer.ts |
--exclude [value] | RegExp filter for files to exclude. Takes multiple values | [] |
-f, --filter [value] | Select tests to run by RegExp. Takes multiple values | [] |
-R, --reporter [value] | npm package name or file path to a Betterer reporter. Takes multiple values | ['@betterer/reporter'] |
-r, --results [value] | Path to test results file relative to CWD | ./.betterer.results |
-s, --silent | Disable all default reporters. Custom reporters still work normally. | false |
--strict | Hide the "how to update" message and set --update to false. | false |
-t, --tsconfig [value] | Path to TypeScript config file relative to CWD | null |
-u, --update | Update the results file, even if things get worse | false |
--workers | number of workers to use. Set to false to run tests serially. | Number of CPUs - 2 |
Read more about Start mode
CI mode
When you run your tests on your CI server (like as part of a build review process), you should use betterer ci:
- Yarn
- npm
Run yarn betterer ci to run Betterer in CI mode.
Run npm run betterer ci to run Betterer in CI mode.
Betterer will run your tests, compare the new results against the expected results, and report the updated status. If there is any difference between the new results and the expected results, then the committed results file doesn't reflect the real state of the codebase, and Betterer will throw an error ❌.
CI options
You can pass the following options to ci:
| Option | Description | Default |
|---|---|---|
--cache | When present, Betterer will only run on changed files. | false |
--cachePath [value] | Path to Betterer cache file relative to CWD | ./.betterer.cache |
-c, --config [value] | Path to test definition file relative to CWD. Takes multiple values | ./.betterer.ts |
--exclude [value] | RegExp filter for files to exclude. Takes multiple values | [] |
-f, --filter [value] | Select tests to run by RegExp. Takes multiple values | [] |
-R, --reporter [value] | npm package name or file path to a Betterer reporter. Takes multiple values | ['@betterer/reporter'] |
-r, --results [value] | Path to test results file relative to CWD | ./.betterer.results |
-s, --silent | Disable all default reporters. Custom reporters still work normally. | false |
-t, --tsconfig [value] | Path to TypeScript config file relative to CWD | null |
--workers | number of workers to use. Set to false to run tests serially. | Number of CPUs - 2 |
Read more about CI mode
Pre-commit mode
If you just want to run your tests in a pre-commit hook, you can use betterer precommit:
- Yarn
- npm
Run yarn betterer precommit to run Betterer in Pre-commit mode.
Run npm run betterer precommit to run Betterer in Pre-commit mode.
Betterer will run your tests, and if there is a change in the results file then Betterer will add it to the commit.
Pre-commit options
You can pass the following options to precommit:
| Option | Description | Default |
|---|---|---|
--cache | When present, Betterer will only run on changed files. | false |
--cachePath [value] | Path to Betterer cache file relative to CWD | ./.betterer.cache |
-c, --config [value] | Path to test definition file relative to CWD. Takes multiple values | ./.betterer.ts |
--exclude [value] | RegExp filter for files to exclude. Takes multiple values | [] |
-f, --filter [value] | Select tests to run by RegExp. Takes multiple values | [] |
-R, --reporter [value] | npm package name or file path to a Betterer reporter. Takes multiple values | ['@betterer/reporter'] |
-r, --results [value] | Path to test results file relative to CWD | ./.betterer.results |
-s, --silent | Disable all default reporters. Custom reporters still work normally. | false |
-t, --tsconfig [value] | Path to TypeScript config file relative to CWD | null |
--workers | number of workers to use. Set to false to run tests serially. | Number of CPUs - 2 |
Read more about Pre-commit mode
Watch mode
If you just want to run your tests each time your files change (like when working to fix a whole bunch of issues), you can use betterer watch:
- Yarn
- npm
Run yarn betterer watch to run Betterer in watch mode.
Run npm run betterer watch to run Betterer in watch mode.
Watch mode controls
- Press
qto quit - Press
fto modify filters - Press
ito modify ignores
Betterer will start watch mode, and wait for any files to change. When a file is saved, it will run any tests that apply to that file, compare the new results against the saved results, and report the updated status. When you quit watch mode (by pressing q), the .betterer.results file will be updated with the new results ✅!
When running in watch mode, Betterer will currently only run File Tests. This might change in the future, so please raise an issue with your use case!
Watch options
You can pass the following options to watch:
| Option | Description | Default |
|---|---|---|
--cache | When present, Betterer will only run on changed files. | false |
--cachePath [value] | Path to Betterer cache file relative to CWD | ./.betterer.cache |
-c, --config [path] | Path to test definition file relative to CWD. Takes multiple values | ./.betterer.ts |
-f, --filter [regexp] | Select tests to run by RegExp. Takes multiple values | [] |
-i, --ignore [glob] | Ignore files by Glob when running in watch mode. Takes multiple values | [] |
-R, --reporter [value] | npm package name or file path to a Betterer reporter. Takes multiple values | ['@betterer/reporter'] |
-r, --results [path] | Path to test results file relative to CWD | ./.betterer.results |
-s, --silent | Disable all default reporters. Custom reporters still work normally. | false |
-t, --tsconfig [path] | Path to TypeScript config file relative to CWD | null |
--workers | number of workers to use. Set to false to run tests serially. | Number of CPUs - 2 |
Ignoring files
If you want to ignore changes in certain files when running in Watch mode, you can use the --ignore option, which can take multiple values. Each ignore pattern should be a glob.
- Yarn
- npm
Run yarn betterer watch --ignore **/*.js to run Betterer with an ignore.
Run yarn betterer watch --ignore "**/*.js" --ignore "**/*.css" to run Betterer with multiple ignores.
Run npm run betterer watch --ignore **/*.js to run Betterer with an ignore.
Run npm run betterer watch --ignore "**/*.js" --ignore "**/*.css" to run Betterer with multiple ignores.
When running in Watch mode, ignores can be updated on the fly by first pressing i, and then modifying the current ignore.
Debug mode
If something isn't working correctly, it can be useful for debugging purposes to get a debug log. You can pass the following options to any of the run commands:
| Option | Description | Default |
|---|---|---|
-d, --debug | Enable debug mode. Also enables the silent option to hide reporters output. | false |
-l, --debug-log [path] | Path to the debug log file. | ./.betterer.log |