Run tests locally

Run your tests locally against your development environment

Running Tests Locally

There are two ways to run Octomind tests locally against your development environment:

1. Using the Octomind CLI (recommended)
2. Using Debugtopus (legacy method)

Running tests locally is ideal for setting breakpoints, stepping through code, and debugging issues identified by Octomind tests.

Using the Octomind CLI

The Octomind CLI provides a simple way to run tests locally with the debug command. This is the recommended approach for local test execution.

1. Install the Octomind CLI

If you haven’t already installed the CLI, you can do so with:

npm i -g @octomind/octomind

Or use it directly with npx:

npx @octomind/octomind

2. Initialize the CLI

If you haven’t already initialized the CLI with your API key:

octomind init

3. Run Tests Locally

Use the debug command to run tests against your local development environment:

octomind debug --url http://localhost:3000

This will use a local browser controlled by Playwright to run the test cases. It will still use the configured setup including the proxy settings for the environment.

Options

• --url <url> (required): URL of your locally running application
• --id <uuid>: ID of a specific test case you want to run
• --environmentId <uuid>: ID of the environment to use
• --testTargetId <uuid>: ID of the test target (optional if configured via init)
• --headless: Run without the UI of Playwright and the browser
• --persist: Write Playwright config and files to current directory for later use

Example

To run a specific test case against your local development server:

octomind debug --url http://localhost:3000 --id 12345678-1234-1234-1234-123456789012

Using Debugtopus (Legacy Method)

Debugtopus is our open source tool that was previously used for local test execution. While the CLI method is now recommended, Debugtopus is still available for users who prefer it.

1. Get shell script

Click on run locally to get a shell script snippet which you can use to install and start Debugtopus.

Run locally button in advanced debugging tools in test result detail, 05/2025

Click on copy to clipboard.

Debugtopus shell script, 05/2025

2. Start test locally

Open a terminal window and paste the shell script from your clipboard.

Pasting debugtopus shell script to terminal, 02/2024

Now change the url with the url of your locally running application. In the example screenshot below, the placeholder was replaced with localhost:3000. You might also have to include the route to the starting point. For example, if your test case assumes to run from the sign-in page you have to add the route to the sign-in page e.g. localhost:3000/signin.

Change the url placeholder with your locally running application, 02/2024

3. First time users - install Debugtopus package

If either Playwright or Chromium are not available on your computer, the shell script command will install the Debugtopus package and its dependencies on your computer. You have to confirm by entering y.

Install Debugtopus, 02/2024

The biggest portion of this package is Playwright. If you want to see the full package list, please check out the Debugtopus Github repository.

If you do not have Chromium installed, debugtopus will run npx playwright install chromium for you and the first run will take some time to complete.

4. Run test locally in the Playwright UI

Click the run button which is displayed on the right side of the test case to run your test.

Run test button in Playwright UI, 02/2024

Now the Playwright UI is shown.

Playwright UI screenshot, 02/2024

Watch this this video for more insight on how to run Octomind tests: