Donobu for Coding Agents

Overview

Donobu ships an agent skill with the @donobu/test package. Install it once in your test repo and your coding agent knows the library, the donobu CLI, and the conventions that connect a test to the test case it covers.

The skill is the supported way to use Donobu from a coding agent. The MCP server is not yet updated for these features, so use the skill until it is.

Prerequisites

• @donobu/test installed from the Donobu registry. See Installation & Setup for the .npmrc and the install command.
• DONOBU_API_KEY in your environment or in the project's .env. The same key installs the package, runs tests, and reads your account's test cases. Run npx donobu status to confirm which key and account answer.

Install the skill

Run this in the root of your test repo:

npx donobu skills install

It writes three things:

• .agents/skills/donobu/ for the vendor-neutral Agent Skills convention.
• .claude/skills/donobu/ for Claude Code project skills.
• A marker-delimited managed block in AGENTS.md, for agents that read AGENTS.md but not skill directories.

Each target holds SKILL.md plus reference files the agent reads on demand. Commit them. They are generated files, so edits are overwritten on the next install.

Keep them fresh by wiring the install into the project's prepare script:

{
  "scripts": {
    "prepare": "donobu skills install || exit 0"
  }
}

The || exit 0 guard keeps production installs green when @donobu/test is a devDependency and the binary is absent. To check for drift without writing anything, run npx donobu skills status --check.

What the skill covers

Authoring tests. The agent writes standard Playwright specs and delegates steps to the AI with page.ai, plus page.ai.assert, page.ai.locate, page.ai.extract, and page.ai.within. Steps are written in plain English, and the test self-heals when the app changes.

Debugging failures. npx donobu runs and npx donobu results return run history and per-test results, and npx donobu files get pulls one result's evidence by name (screenshots, the treatment plan, logs). A CI run URL names a run, so the agent triages a CI failure without downloading an artifact bundle.

Driving a live browser. npx donobu session start gives the agent a recorded browser it drives one step at a time with observe, click, type, goto, assert, and logs. npx donobu save <path> emits the recording as a runnable spec.

Managing test cases. npx donobu cases list|show|create|update|delete|link|unlink reads and writes your account's test-case inventory in Donobu Cloud. The case ID doubles as a Playwright tag: a test tagged @<slug> links to the case with that slug, and the case then reports that test's results.

The loop

Automating one test case takes six steps.

1. Install the skill. npx donobu skills install in the test repo, with DONOBU_API_KEY set.

2. Read the case. npx donobu cases show checkout-guest --json returns the title, the description, and any tests already linked.

3. Write the spec. A standard Playwright test, tagged with the case ID:

   import { test } from '@donobu/test';
   
   test(
     'Guest checkout completes end to end',
     { tag: ['@checkout-guest'] },
     async ({ page }) => {
       await page.goto('https://app.example.com');
       await page.ai('Add the first product to the cart and open the cart');
       await page.ai.assert('The cart shows 1 item');
     },
   );
   

4. Run it. npx donobu test -g "Guest checkout".

5. Read the result. npx donobu runs show latest, then npx donobu results show <result-id> when a test failed. Fix and run again.

6. Confirm the link. Donobu derives the link from the tag on its side, and it appears after the next link sync. Once it has, npx donobu cases show checkout-guest lists the test under its linked tests, and npx donobu results list --test "Guest checkout completes end to end" shows how it did. The case page on donobu.com shows the same thing. If the test is not listed yet, wait for the sync rather than adding a manual link: a manual link is never garbage-collected, so it would outlive the tag.

Tests run on your machine, in CI, or in Donobu Studio. donobu.com shows the results.

The MCP server

The Donobu MCP server is not yet updated for the features on this page. It gives an AI IDE three tools over a running copy of Donobu Studio. Until it is brought to parity, install the skill: it covers the same ground and more, and npx donobu session drives a real browser step by step from the command line, with no desktop app and no MCP configuration file. Existing MCP setups keep working.