How It Works

Overview

FastTest Agent has two main parts:

The MCP server runs locally on your machine, inside your AI coding assistant. It controls a real browser (Chromium, Firefox, or WebKit) and exposes 25 tools. It never calls an LLM — your AI assistant (Claude Code, Codex, etc.) drives all browser interactions using its own reasoning.
The cloud stores your projects, test suites, test cases, execution history, and healing patterns. It also powers AI test generation and AI selector suggestions — the only places the cloud calls an LLM.

Your Machine                              Cloud
+-------------------------------+   +----------------------------+
|  AI Coding Assistant          |   |                            |
|  (Claude Code, Cursor, etc.)  |   |  FastTest Agent Cloud      |
|          |                    |   |  - Test generation (AI)    |
|          v                    |   |  - Project & suite storage |
|  FastTest Agent MCP Server    |   |  - Execution history       |
|  - 25 tools                   |   |  - Healing pattern DB      |
|  - Local Playwright browser   |-->|  - GitHub integration      |
|  - Self-healing cascade       |<--|  - Regression detection    |
|  - Session persistence        |   |  - CI/CD integration       |
|  - Device emulation           |   +----------------------------+
+-------------------------------+            |
                                             v
                                   +----------------------------+
                                   |  Dashboard                 |
                                   |  - Live test monitoring    |
                                   |  - Project management      |
                                   |  - Healing patterns        |
                                   |  - Security audit reports   |
                                   |  - Shared steps            |
                                   +----------------------------+

Key Architectural Principle

The MCP server is a tool provider — it never calls an LLM. Domain tools like test, explore, security_audit, and heal return page snapshots and structured prompts that your AI assistant follows with its own reasoning. This means:

No cloud LLM latency in the test execution path
Any MCP-compatible AI assistant can drive FastTest Agent (Claude Code, Codex, Cursor, VS Code, Windsurf, etc.)
Tests run locally on your machine — no data leaves unless you opt into cloud features

Test Creation Flow

You describe what to test

“Test the checkout flow on staging.myapp.com” — in plain English, inside your AI assistant.
FastTest Agent opens a browser

The test tool launches a local Playwright browser, navigates to your app, and returns a page snapshot to your AI assistant.
Your AI assistant drives the test

Using the page snapshot, your AI assistant reasons about the app and executes test steps — clicking buttons, filling forms, checking assertions — all using the browser tools.
Save as a reusable suite

Once your AI assistant finishes testing, it saves the test cases to the cloud with the save_suite tool — including steps, assertions, and {{VAR_NAME}} placeholders for sensitive values.

Test Execution Flow

You say “run the tests”

Your AI assistant triggers the run tool with the suite name or ID.
Tests execute locally

The MCP server fetches test cases from the cloud, then runs each one step by step in a local Playwright browser — navigating pages, clicking buttons, filling forms, and checking assertions.
Broken selectors are healed automatically

If a step fails because a CSS selector no longer matches, the self-healing cascade tries 5 strategies to find a working replacement. If successful, the test continues and the fix is stored org-wide.
Results are reported with regression detection

You see pass/fail results in your assistant. The cloud compares with the previous run and highlights regressions (tests that broke), fixes (tests that started passing), and new tests.

What Runs Where

Component	Where	What it does
MCP Server	Your machine	Runs browser, executes test steps, heals selectors
Browser (Playwright)	Your machine	Chromium, Firefox, or WebKit — tests run in a real browser
Cloud API	Hosted	Stores projects, test cases, results, healing patterns
Dashboard	Web app	View results, manage projects, review healing history
CI Runner (`fasttest-ci`)	Your CI pipeline	Runs test suites headlessly in GitHub Actions or any CI