Getting started

Bombadil runs on your development machine if you’re on macOS or Linux. Use it to validate changes to TypeScript specifications, and to run short tests while working on your system. Configure something like GitHub Actions or a cron job to continously run longer tests on your main branch or in a deployed staging environment. When you’re ready to put your system under extreme conditions, and test your full stack deterministically, run it inside Antithesis.

Installation

The most straightforward way for you to get started is downloading the executable for your platform:

npm install --save-dev @antithesishq/bombadil

{
  "scripts": {
    "test": "bombadil browser test --time-limit=1m https://your-app.example.com"
  }
}

curl -L -o bombadil https://github.com/antithesishq/bombadil/releases/download/v0.6.1/bombadil-aarch64-darwin
chmod +x bombadil

mv ./bombadil ~/.local/bin/bombadil

bombadil --version

curl -L -o bombadil https://github.com/antithesishq/bombadil/releases/download/v0.6.1/bombadil-x86_64-linux
chmod +x bombadil

mv ./bombadil ~/.local/bin/bombadil

bombadil --version

nix run github:antithesishq/bombadil

- uses: antithesishq/bombadil-action@v2
  with:
    driver: browser
    origin: https://your-app.example.com
    specification: ./bombadil/specification.ts
    time-limit: 5m
    exit-on-violation: true
    output-path: bombadil-output

If you want to compile from source, see Contributing.

TypeScript support

When writing specifications in TypeScript, you’ll want the types available. If you installed Bombadil via npm, you already have them — skip ahead to Your first test.

Otherwise, install the package with your package manager of choice:

npm install --save-dev @antithesishq/bombadil

yarn add --dev @antithesishq/bombadil

bun add --development @antithesishq/bombadil

Or use the files provided in the release package.

Your first test

With the CLI installed, let’s run a browser test just to see that things are working:

bombadil browser test https://en.wikipedia.org --output-path my-test

This will run until you shut it down using Ctrl+C. Any property violations will be logged as errors, and with the --output-path option you will get results to inspect afterwards.

Launch the Bombadil Inspect tool to see what happened in the test you just ran:

bombadil browser inspect my-test

This will open a web application in your browser, which has some features to highlight:

• This interface is focused on state transitions, i.e. the state before and after each action.
• On the left is the actions list, which you can use to navigate the state transitions by clicking the actions.
• In the bottom you’ll see the timeline, which you can scrub (click and drag) with your mouse. The timeline also shows the currently selected state transition.
• If there were any violations found in the test, they’ll be shown as exclamation mark icons in the timeline.

No violations? That’s fine, Wikipedia is pretty solid! This confirms that Bombadil runs and produces results.

Reproducing violations

If Bombadil finds a bug in a project you’re working on, you might want to reproduce that test case when working on a bug fix. That is, have Bombadil perform the same sequence of actions to reach the same state.

Use the --reproduce option and point it to the output directory of the original test run:

bombadil browser test --reproduce=my-test http://example.com

Reproductions are not guaranteed to succeed; if they diverge, Bombadil fails with an error. For reproductions to succeed, it’s important to use the same options as in the original test. After a test run, Bombadil prints both the inspect and --reproduce commands you can use.