CircleCI browser testing

Run Monito browser tests from CircleCI with an API key and your deployed URL. Untested config example, URL handoff between jobs and secret limits.

CI/CD · Checked 2026-11-13

Add a job after your deploy job and wait for Monito's browser verdict. The Monito CLI path works today; our team has not run this config in CircleCI.

How it works

  1. Your deploy job finishes and writes the deployed URL to a file in the CircleCI workspace.
  2. A Node job attaches the workspace, authenticates with MONITO_TOKEN, and runs the project's saved tests against that URL with --base-url.
  3. The CLI waits and exits nonzero for failed or errored tests, failing the job. Inspect the browser evidence in Monito's run report.

Set it up

Pro or Team to create the API key used as MONITO_TOKEN. Browser runs use your credits. Plan details

  1. Create a Monito API key on Pro or Team. Store it as MONITO_TOKEN in a CircleCI context or a project environment variable, and set MONITO_PROJECT_ID to your project ID. Name the context on the monito job in the workflow. A project environment variable is available without that key.
  2. Have the deploy job write the deployed URL to a file, for example mkdir -p workspace and echo "$URL" > workspace/deploy-url.txt, then persist that file with persist_to_workspace. Keep the token out of the file.
  3. Add the config below. The monito job requires the deploy job, attaches the workspace, and runs the saved tests with --base-url.
  4. If a failed job should block merges, require the status CircleCI reports to your Git provider. A normal job reports ci/circleci: and the job name on GitHub and Bitbucket. When the CircleCI Checks app is installed, GitHub reports the workflow, and requiring the job status key can leave the pull request waiting. This setup does not post a Monito comment on the pull request.
.circleci/config.yml · yaml
version: 2.1
jobs:
  deploy:
    docker:
      - image: cimg/node:24.22.3
    steps:
      - run:
          name: Record the deployed URL
          command: |
            mkdir -p workspace
            echo "$URL" > workspace/deploy-url.txt
      - persist_to_workspace:
          root: workspace
          paths:
            - deploy-url.txt
  monito:
    docker:
      - image: cimg/node:24.22.3
    steps:
      - attach_workspace:
          at: /tmp/workspace
      - run:
          name: Run saved browser tests
          command: |
            DEPLOY_URL="$(cat /tmp/workspace/deploy-url.txt)"
            test -n "$DEPLOY_URL" || { echo "DEPLOY_URL is empty"; exit 1; }
            npx -y @monitodev/cli@4 project run "$MONITO_PROJECT_ID" --wait --base-url "$DEPLOY_URL"
workflows:
  browser-tests:
    jobs:
      - deploy
      - monito:
          requires: [deploy]

Example our team has not run in CircleCI. The deploy job stands in for your deployment and only writes the URL into the workspace. Replace the echo with the URL your deploy command prints. Add a context key on the monito job when MONITO_TOKEN is stored in a context. The guard fails the job if the URL is empty so the CLI cannot silently test the project's default environment. The image is pinned to cimg/node:24.22.3. On 2026-11-13 that tag, cimg/node:24.22, and cimg/node:24 shared one Docker Hub digest.

Using GitLab CI instead?

Using GitLab CI instead? The same CLI command runs after a review deploy when the URL arrives through a dotenv artifact. Our team has not run that YAML in GitLab.

CircleCI sources

The CircleCI behavior on this page was checked against the following documentation on 2026-11-13. cimg/node:24.22.3 was the newest Node 24 tag on Docker Hub that day, and cimg/node:24 pointed at the same digest. The benchmark reports below do not validate the CircleCI configuration.

Example result

Example result: field names from the CLI, values illustrative

Selected fields from project run --wait --json. Each runs entry has its own id, status and sessionId. Add --json to read the full result. Open /session/<sessionId> on Monito, or follow the run report from the dashboard or GitHub summary to inspect browser evidence.

Illustrative result · JSON
{
  "runs": [
    {
      "id": "run_example",
      "scenarioId": "scenario_example",
      "status": "failed",
      "sessionId": "session_example"
    }
  ]
}

Limits to account for

Builds from forked pull requests do not receive environment variables set in the CircleCI application unless Pass secrets to builds from forked pull requests is on. CircleCI also hides deployment keys, user keys, passphraseless SSH keys, and AWS permissions from those builds. On an OAuth organization, turning the setting on shares those secrets with anyone who forks the project and opens a pull request, so MONITO_TOKEN would be readable by the fork's config. CircleCI's help center says the fork also receives contexts when Build forked pull requests is on, and a context limited to All members does not block that. The pass-secrets setting is not supported when the organization slug starts with circleci/.

If a context is restricted to a security group, the user who triggered the pipeline must belong to one of those groups, or the workflow fails with Unauthorized. Organization administrators are excepted. Security group restrictions are available for GitHub organizations. Bitbucket organizations cannot restrict a context this way.

Jobs do not share files unless an earlier job persists them with persist_to_workspace and a later job attaches them with attach_workspace. The later job has to require the earlier one. An environment variable exported in one job is not available in the next. CircleCI moves data between jobs with artifacts, caches, and workspaces, and a workspace carries files.

Secrets masking hides project and context environment variables in the job output when echo or print is used. Code running in the job can still read the value. Values shorter than 4 characters, and the values true and false, are not masked. Masking does not cover test results, artifacts, or an SSH debug session, and a shell trace can print the value.

A base-URL override preserves scenario paths and saved-login origin restrictions. It does not authorize credentials on a new preview origin.

Comparable benchmark runs

Our team published these runs in the reliability benchmark. They show comparable browser journeys, not executions of the configuration or illustrative result above. Run your own scenario before relying on this integration.

Benchmark method and limits

Questions

Does Monito have a CircleCI orb?

No. Monito does not publish a CircleCI orb for browser tests. This page runs the Monito CLI with npx.

Which plan do I need?

Pro or Team. Creating the API key used as MONITO_TOKEN requires Pro ($79/mo) or Team ($199/mo). Browser runs use credits.

Can it test preview deployments?

Yes. Pass the deployed URL with --base-url. The override preserves scenario paths and saved-login origin restrictions. It does not authorize credentials on a new preview origin.

Read the full guide

All integrations