Domain Tools

Domain tools handle test creation, execution, exploration, security auditing, GitHub integration, and healing. Some work locally without cloud, while others require cloud authentication.

Testing & Exploration

test

Start a test session. Launches a browser, navigates to the URL (if provided), captures a page snapshot and screenshot, and returns a structured prompt for your AI assistant to execute test scenarios using the browser tools.

Parameter	Type	Required	Description
description	string	Yes	What to test, in natural language
url	string	No	App URL to test against
project	string	No	Project name (auto-saved to .fasttest.json)
device	string	No	Device to emulate (e.g., iPhone 15, Pixel 7)

{
  "description": "Test the checkout flow with a guest user",
  "url": "https://shop.example.com",
  "project": "E-Commerce"
}

Your AI assistant receives the page snapshot and follows the returned prompt to drive browser interactions — clicking, filling, asserting — using browser tools. No cloud LLM is involved.

explore

Explore a web application autonomously. Navigates to the URL, captures a snapshot and screenshot, and returns a structured prompt for your AI assistant to breadth-first survey the app — discovering pages, forms, CRUD flows, and error states.

Parameter	Type	Required	Description
url	string	Yes	Starting URL
max_pages	number	No	Max pages to explore (default: 20)
focus	enum	No	forms, navigation, errors, or all (default: all)
device	string	No	Device to emulate

{
  "url": "https://myapp.example.com",
  "focus": "forms"
}

vibe_shield

One-command safety net for regression testing. Say “vibe shield my app” and FastTest Agent explores the app, generates test cases, saves them as a suite, and runs a baseline.

Parameter	Type	Required	Description
url	string	Yes	App URL to protect
project	string	No	Project name (auto-saved to .fasttest.json)
suite_name	string	No	Suite name (default: Vibe Shield: <domain>)
device	string	No	Device to emulate

First run: Returns a prompt to explore the app and build a test suite. Subsequent runs: Returns a prompt to run the existing suite and check for regressions.

{
  "url": "https://myapp.example.com",
  "project": "MyApp"
}

Tip

Vibe Shield is the fastest way to go from zero to a full regression suite. Run it once to build, then re-run whenever you make changes to catch regressions.

security_audit

Unified security testing with three modes: static code analysis (SAST/SCA), dynamic browser adversarial testing (DAST), or both. Say “secure my app” to trigger a full audit.

Parameter	Type	Required	Description
mode	enum	No	static, dynamic, or full (default: full)
directory	string	No	Directory to scan for static analysis (default: cwd)
url	string	Conditional	URL for dynamic testing (required for dynamic and full modes)
focus	enum	No	Dynamic focus: forms, navigation, auth, or all (default: all)
duration	enum	No	quick or thorough (default: thorough)
project	string	No	Project name for saving report
device	string	No	Device to emulate for dynamic testing
severity_threshold	enum	No	Minimum severity for static results: critical, high, medium, or low (default: low)
run_mode	enum	No	auto re-runs existing suite, interactive forces fresh testing

{
  "mode": "full",
  "directory": "/path/to/project",
  "url": "https://myapp.example.com",
  "focus": "forms",
  "duration": "quick"
}

Static mode (SAST + SCA) — scans source code with opengrep and dependencies with Trivy. Finds vulnerabilities, secrets, misconfigurations, and known CVEs. Binaries are auto-downloaded on first use.

Dynamic mode (DAST) — browser adversarial testing:

• XSS payloads, SQL injection strings, boundary values
• Extremely long inputs, special characters, Unicode
• Auth bypass attempts (direct URL access, session manipulation)
• Console error monitoring and network failure detection

Full mode — runs both, then cross-references: findings confirmed by both static and dynamic analysis are flagged as “confirmed exploitable”.

---

Suite Management

save_suite

Save test cases as a reusable test suite in the cloud. If a suite with the same name already exists in the project, it will be updated automatically (test cases matched by name — existing updated, new added, unmentioned kept).

Parameter	Type	Required	Description
suite_name	string	Yes	Name for the test suite
description	string	No	What this suite tests
intent	string	No	WHY these tests exist (powers Provenance page)
test_type	enum	No	functional (default) or security
project	string	No	Project name (auto-resolved or created)
session	string	No	Default browser session for all test cases
setup	array/object	No	Login steps (single role: array, multi-role: map)
test_cases	array	Yes	Array of test cases (see below)
chaos_findings	array	No	Security findings to save as a report
chaos_url	string	No	URL tested during security audit session

Each test case has:

Field	Type	Required	Description
name	string	Yes	Test case name
description	string	No	What this test verifies
priority	enum	No	critical, high, medium, or low
steps	array	Yes	Test steps (see actions below)
assertions	array	Yes	Assertions to verify
tags	string[]	No	Tags for categorization
status	enum	No	passed or failed — records the result from your interactive session

Step actions: navigate, click, fill, fill_form, hover, select, wait_for, scroll, press_key, upload_file, evaluate, go_back, go_forward, drag, resize, assert

Every step should include an intent field — a plain-English description of what the step does, used for self-healing context.

Caution

For sensitive values (passwords, API keys, tokens), use {{VAR_NAME}} placeholders instead of literal values. Example: {{TEST_USER_PASSWORD}} instead of the actual password. Variables are resolved from environment variables at execution time. Names must be UPPER_SNAKE_CASE.

Security findings can be attached when saving security test results. Each finding has:

Field	Type	Required	Description
severity	enum	Yes	critical, high, medium, or low
category	string	Yes	e.g., xss, injection, crash, validation, error, auth
description	string	Yes	What was found
reproduction_steps	string[]	Yes	Steps to reproduce
console_errors	string[]	No	Captured console errors

---

Execution

run

Execute a test suite. Fetches test cases from the cloud, runs each one in a local Playwright browser, attempts self-healing on failures, and reports results with regression detection.

Parameter	Type	Required	Description
suite_id	string	No	Suite ID (provide this OR suite_name)
suite_name	string	No	Suite name (resolved automatically)
environment_name	string	No	Environment to run against (e.g., staging, production)
test_case_ids	string[]	No	Specific test case IDs (default: all in suite)
pr_url	string	No	GitHub PR URL for posting results as a comment
device	string	No	Device to emulate

{
  "suite_name": "Login Flow",
  "pr_url": "https://github.com/myorg/myrepo/pull/42"
}

Example output:

Test Run PASSED
Execution ID: exec-789
Total: 5 | Passed: 4 | Failed: 0 | Skipped: 1
Duration: 12.3s

  PASSED Login with valid credentials (2100ms)
  PASSED Add item to cart (3400ms)
  PASSED Guest checkout flow (4200ms)
  PASSED Order confirmation page (1800ms)
  SKIPPED Payment with Apple Pay (800ms)

Self-Healed: 1 selector(s)
  "Add item to cart" step 2
     #add-to-cart -> [data-testid="add-to-cart"]
     Strategy: data_testid (98% confidence)

Regression Diff:
  Regressions: 0 | Fixes: 1 | New: 0

Tip

The run tool handles the full lifecycle: fetching test cases, resolving {{VAR}} placeholders, executing steps, healing broken selectors, reporting results, and computing regression diffs against the previous run.

status

Check execution status or backend health.

Parameter	Type	Required	Description
execution_id	string	No	Execution ID to check (omit for health check)
base_url	string	No	Override URL for health check

With execution_id: returns execution details (status, results, timing). Without execution_id: checks if the FastTest backend is reachable.

cancel

Cancel a running test execution.

Parameter	Type	Required	Description
execution_id	string	Yes	Execution ID to cancel

---

Setup & Configuration

setup

Authenticate with the FastTest Agent cloud via device auth flow. Opens a browser for secure login, then saves the API key locally.

Parameter	Type	Required	Description
base_url	string	No	Cloud API URL (default: https://api.fasttest.ai)

The flow:

1. Requests a device code from the cloud
2. Opens a browser to the verification URL
3. Polls until you complete authentication
4. Saves API key to ~/.fasttest/config.json

---

Project & Suite Listing

list

List projects, suites, or test cases in a single tool.

Parameter	Type	Required	Description
type	enum	Yes	projects, suites, or cases
search	string	No	Filter suites by name (only for type='suites')
suite_id	string	No	Suite ID (only for type='cases')
suite_name	string	No	Suite name (only for type='cases')

Examples:

{ "type": "projects" }

{ "type": "suites", "search": "checkout" }

{ "type": "cases", "suite_name": "Login Flow" }

---

GitHub Integration

github_token

Set the GitHub personal access token for PR integration. The token is encrypted and shared across your organization.

Parameter	Type	Required	Description
token	string	Yes	GitHub PAT with repo scope

Caution

Use a classic token with repo scope, or a fine-grained token with Contents: Read and Pull requests: Read and write permissions. The token is encrypted at rest and scoped to your organization.

---

Healing

heal

Heal a broken selector or view healing history.

Heal mode (provide selector): Runs the 5-strategy healing cascade against the current page. If all local strategies fail, returns a page snapshot for your AI assistant to reason about.

Parameter	Type	Required	Description
selector	string	No	The broken CSS selector to heal
page_url	string	No	URL where the selector broke (defaults to current page)
error_message	string	No	The Playwright error message
show_history	boolean	No	Set to true to view healing patterns and statistics
limit	number	No	Max patterns to return when show_history=true (default: 20)

{ "selector": "#old-submit-btn" }

Success response:

Selector healed!
  Original: #old-submit-btn
  New:      [data-testid="submit-btn"]
  Strategy: data_testid (98% confidence)

Failure response: Returns a page snapshot and prompt for your AI assistant to suggest alternatives based on the current DOM.

History mode (show_history: true):

{ "show_history": true }

Healing Statistics
Total healed: 47
Patterns stored: 12
Avg confidence: 92%

Strategy breakdown:
  data_testid: 23 heals
  aria: 11 heals
  text: 8 heals
  structural: 5 heals