BugmoleDocs bugmole.com →

Getting started

There are two ways in. Most people start in the dashboard, which needs nothing installed. Add the CLI when you want to test localhost, run in CI, or keep results on your own machines.

In the dashboard: nothing to install

  1. Sign up at app.bugmole.com. You get a workspace and a first project.
  2. On Overview, paste your app's address into Paste your app's address and choose Explore this URL. Bugmole opens the app in a real browser and clicks through it like a first-time visitor. The box says roughly when it will be done.
  3. Every page and form it finds becomes a test. Open Tests, pick one, and choose Run tests to run it on Chrome, Firefox, Safari, Edge and emulated phones at once.
  4. Watch the result live, or come back later: Runs keeps every run with its result, what started it, and which tests are flaky. Issues lists what needs attention.

Exploration runs in Bugmole Cloud, so your app must be reachable from the internet. See Discover and debug for what it does and doesn't do, including apps that start with a sign-in page.

With the CLI

Requirements

Install

Run it without installing:

npx bugmole init

Or install it once, globally:

npm install -g bugmole

Either way you get the bugmole command and its shortcut, bm. (bugmole is a small package that installs @bugmole/cli; npx @bugmole/cli init and npm install -g @bugmole/cli do the same thing.)

Installing also downloads the browsers Bugmole tests in: Chromium, Firefox and WebKit (Safari), plus ffmpeg for run videos. Browsers you already have are skipped. Edge needs admin rights, so add it yourself once per machine if you want it:

npx playwright install msedge

Connect your project

From the folder of the app you want to test:

bugmole init

It asks only for the project's name and whether to keep results on this computer or in Bugmole (and, when you belong to several workspaces, which one). Everything else takes a default: add -y to take them all without questions, or --advanced to be asked about every setting. Running it again in a project you're already in links to that project. To use a project you already made in the dashboard (its id may differ from the folder's name), pick it from the list init shows, or choose it under Connect this folder to on the page that opens when you pair a new machine.

On a machine with no API key yet, this prints a short pairing code and opens the dashboard, where you sign in and pick the project. The machine's API key is then written once to .bugmole.env as BUGMOLE_API_KEY, and init adds .bugmole.env to .gitignore so it stays out of git. Pairing another machine to the same project reuses the project's environment rather than adding another.

bugmole init first works out which app it's in. Bugmole tests web apps and mobile apps (Android and iOS); if the folder has neither, such as a data pipeline or a model, it says it's out of scope. A project is identified by the repository's git remote plus the app's folder in it, so a teammate who runs bugmole init in their own clone joins the same project instead of creating another. In a repository with several apps, each app is its own project: run bugmole init from the app's folder, or pass --app-path apps/web. The credentials in a git remote are never sent to Bugmole.

Explore, plan and run

bugmole init writes .bugmole/config.yaml, which works as it is. You don't need an AI model key: steps that use AI run on Bugmole AI with your machine's API key, or on your own model if you add one (see Configuration).

Explore the project (its routes, pages and flows). If the source has no route files, such as an Express or plain Node app, pass --base-url and Bugmole crawls the running app instead:

bugmole --mode explore --base-url http://localhost:3000

Exploration records the journeys it finds in spec/journeys.graph.json. Plan one of them for a role a person has confirmed (see Roles; bugmole roles lists them):

bugmole --mode plan --journey-id <journey> --actor <role>

On the web, planning also writes a runnable flow for the journey at spec/flows/journeys/<plan>.yaml. It never overwrites that file, so you can edit it. A journey that's still a draft can be planned too: running its plan is how it's proven.

Run the plan:

bugmole --mode run --plan-id <plan>

Run it on several browsers and devices at once:

bugmole --mode run --plan-id <plan> --browsers chromium,firefox,webkit,msedge --devices "iPhone 15,Pixel 7"

A missing proof or an unsafe action is reported as blocked, never silently marked as passing.

Explore an app that needs sign-in

On Bugmole Cloud, save a sign-in flow and its secrets under Settings → Sign-in for runs; cloud exploration and cloud runs sign in with them first. See Sign-in for runs. From your machine or CI, give discovery the sign-in flow and it explores what's behind it:

bugmole --mode discover --base-url https://staging.your-app.com --out spec/flows/discovered --sign-in spec/flows/sign-in.yaml

Discovery copies the sign-in flow into the output folder as 00-sign-in.yaml, so it runs first, and prints the command to run them all in one signed-in session:

bugmole --mode suite --flows spec/flows/discovered --base-url https://staging.your-app.com --share-session

Keep the password out of the flow: type it with {{secret.APP_PASSWORD}} and set BUGMOLE_FLOW_SECRET_APP_PASSWORD in the environment.

Run dashboard tests on your own machine

To run tests you start from the dashboard on this machine (for localhost, a VPN, or free unlimited runs), keep a worker running:

bugmole serve

It prints a dashboard link. Open the whole link, including everything after #: that part lets the dashboard read results kept on this machine, and it never reaches Bugmole's servers. Then choose Change under the run button and pick My resources. See Bugmole Cloud or your own machines.

Next