MCP Examples

These examples show how to use Assrt from your coding agent. Just type the prompt in Claude Code, Cursor, or any MCP-compatible editor and the agent will call the right tool automatically.

Test your localhost

The most common workflow: you are developing locally and want to verify a feature works before committing.

Use assrt to test http://localhost:3000. Verify the homepage loads,
the navigation links work, and the signup form submits successfully.

The agent calls assrt_test with a generated plan. You get back pass/fail results, assertions with evidence, and screenshots from each step.

Generate a test plan first

If you are not sure what to test, let Assrt analyze the page and suggest scenarios.

Use assrt_plan to analyze https://myapp.com and generate test cases.

The agent launches a headless browser, takes screenshots at different scroll positions, reads the accessibility tree, and returns a set of test cases in #Case N: format. You can review them, edit, then run:

Now run those test cases with assrt_test against https://myapp.com

Diagnose a failure

When a test fails, ask the agent to diagnose it instead of debugging manually.

Use assrt_diagnose on http://localhost:3000.
The test "Click Add to Cart, verify cart count updates" failed with
"Timed out waiting for text 'Cart (1)'". What went wrong?

The agent calls assrt_diagnose and returns root cause analysis, whether it is an app bug or a flawed test, and a corrected scenario you can run immediately.

Test after making changes

A powerful pattern: ask your agent to test the feature it just built.

I just added a dark mode toggle to the settings page.
Use assrt to test http://localhost:3000/settings — verify the toggle
is visible, clicking it changes the theme, and the preference persists
after page reload.

Run specific scenarios

You can pass detailed test plans inline using the #Case format.

Run assrt_test on http://localhost:3000 with this plan:

#Case 1: Login with valid credentials
1. Navigate to /login
2. Type "user@example.com" into the email field
3. Type "password123" into the password field
4. Click the Sign In button
5. Verify the dashboard page loads with a welcome message

#Case 2: Login with invalid credentials
1. Navigate to /login
2. Type "wrong@example.com" into the email field
3. Type "wrongpass" into the password field
4. Click the Sign In button
5. Verify an error message appears

Use in CI with the CLI

For CI pipelines, use the CLI directly instead of the MCP server. Create a test plan file and run it on every push.

name: QA Tests
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci && npm run dev &
      - run: npx playwright install chromium
      - run: |
          npx -y -p @m13v/assrt assrt run \
            --url http://localhost:3000 \
            --plan-file tests/smoke.txt \
            --json > results.json
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-results
          path: results.json

Tips for writing good prompts

1. Be specific about URLs. Always include the full URL including port number for localhost apps.
2. Describe expected outcomes.Say "verify the dashboard loads with the user's name" not just "verify it works."
3. Include test data. If a form needs specific values, include them in the prompt (email, password, etc.).
4. Keep scenarios short. 3 to 5 actions per test case. Focused tests that pass are better than complex ones that fail.
5. Use diagnose for failures. Instead of re-running a failed test, ask assrt_diagnose to tell you why it failed.