Results file

All your test results will be saved in a results file. By default, Betterer sets this to be .betterer.results, but you can change that by using the --results option when running Betterer.

The results file is similar to a Jest Snapshot file. It should be commited along with your code and probably shouldn't be updated manually (although you of course can if you're feeling confident!).

The results file will look something like this:

// BETTERER RESULTS V2.
exports[`no hack comments`] = {
  value: `{
    "packages/cli/src/cli.ts:1074837834": [
      [13, 0, 7, "RegExp match", "645651780"]
    ],
    "packages/cli/src/init/update-package-json.ts:2842907794": [
      [34, 4, 7, "RegExp match", "645651780"]
    ]
  }`
};

This is a valid JavaScript file, so you can import it and manipulate it if you need to. Each test will have an object that stores its result value, which can be controlled by a tests serialiser and printer options.

When your tests run, Betterer will check to see the result against the expected result in the results file. If the new result is better, the results file will be updated, and that result will be the expected baseline going forward.

BettererFileTest results

The above example comes from a BettererFileTest, which has some note-worthy details. A BettererFileTest result has the following format:

exports[testName]: {
 value: `{
    "relativeFilePath:fileHash": [
      [issueLine, issueColumn, length, issueMessage, issueHash]
      // ... more issues
    ],
    // ... more files
 }`
}

caution

fileHash and issueHash are used to track issues as the lines of code in a file change, or as the file moves around in the codebase. This means they change quite often! Check out the workflow guide for suggested ways to handle this with source control.

Merge

If you are working in a codebase where there is a lot of changes, you may encounter merge conflicts in the results file. It is possible to resolve these manually, but it is much easier to let Betterer handle merging for you!

The merge command does a fairly naive merge of the results file.

Yarn

Run yarn betterer merge to automatically merge the Betterer results file.

npm

Run npm run betterer merge to automatically merge the Betterer results file.

Merge options

You can pass the following options to merge:

Option	Description	Default
-r, --results [value]	Path to test results file relative to CWD	./.betterer.results

Automerge

If you don't ever want to have to think about merging the results file, you can enable automatic merging. Run betterer init with the --automerge. Betterer will update your git configuration to always run betterer merge whenever there is a conflict in the results file.

caution

Automerge is still experimental. Please try it out and create issues on Github if anything is weird. If something is broken, you can just delete the Betterer merge config from the .gitattributes file.