Setup and context
Antigravity's Browser Sub-Agent is far more than a test automation tool — it's a Gemini 3.1 Pro-powered browser automation engine that can "see," reason, and interact with your application the same way a human tester would.
This is what fundamentally sets it apart from traditional Playwright or Selenium setups. Script-based tests require you to hard-code "what to click," while the Browser Sub-Agent uses multimodal visual reasoning to evaluate whether "the button looks correct" or "the layout has broken" — making dynamic, context-aware decisions in real time.
In this guide, you'll learn how to:
- Understand the Browser Sub-Agent's architecture and how it processes visual input
- Build E2E test specs using natural language and structured YAML
- Set up visual regression testing with baseline comparisons
- Integrate automated tests into GitHub Actions CI/CD
- Optimize performance and control Gemini API costs
- Troubleshoot common failures with concrete fixes
Who this is for: Developers comfortable with Antigravity's core workflow who have working knowledge of testing concepts and CI/CD pipelines.
Prerequisites & Environment Setup
Requirements
- Antigravity v1.18.0 or later (Browser Sub-Agent reached GA in v1.18)
- Node.js 20.x or higher
- A project repository (Next.js, React, Vue, or any web app)
- GitHub Actions access (for CI/CD integration)
Check Your Antigravity Version
# Verify version from terminal
antigravity --version
# Expected output: Antigravity 1.20.3 (stable)Project Configuration
To activate the Browser Sub-Agent, create an AGENTS.md file (or GEMINI.md) at your project root. As of v1.20.3, AGENTS.md is the preferred configuration format.
<!-- AGENTS.md -->
# Project Agent Configuration
## Browser Sub-Agent
- base_url: http://localhost:3000
- headless: true
- viewport: { width: 1280, height: 720 }
- screenshot_on_failure: true
- max_actions_per_session: 50
## Test Artifacts
- Save screenshots to: .agent-artifacts/screenshots/
- Save diffs to: .agent-artifacts/diffs/
- Report format: markdown
## Permissions
- Allow: navigate, click, fill, screenshot, scroll
- Require confirmation: file_download, form_submit_external.gitignore Updates
# .gitignore
.agent-artifacts/screenshots/
.agent-artifacts/diffs/
.agent-artifacts/cache/Architecture: How Browser Sub-Agent Works
The Three-Layer Model
Antigravity's Browser Sub-Agent operates across three distinct layers, each powered by different capabilities:
┌─────────────────────────────────────────┐
│ Layer 1: Directive │
│ Developer describes goals in plain │
│ natural language │
│ "Verify the login flow works" │
├─────────────────────────────────────────┤
│ Layer 2: Perception │
│ Gemini Vision analyzes screenshots, │
│ recognizes UI elements and layouts │
├─────────────────────────────────────────┤
│ Layer 3: Action │
│ Executes clicks, inputs, navigation │
│ via Chromium WebDriver │
└─────────────────────────────────────────┘
Where script-based tests depend on DOM selectors (CSS classes, IDs), the Browser Sub-Agent relies on visual and semantic understanding. A renamed class won't break your tests — the agent finds elements by what they look like and what they do.
Integration with Agent Manager
The Browser Sub-Agent runs under Agent Manager supervision, executing asynchronously in the background. This means you can keep coding while a parallel agent runs your test suite — no blocking, no waiting.
Step-by-Step Implementation
Step 1: Writing Your First E2E Test Spec
Start simple. Create an e2e/ directory and write a natural language test spec:
<!-- e2e/auth-flow.agent.md -->
# Authentication Flow E2E Test
## Objective
Verify that user registration, login, and logout flows work correctly end-to-end.
## Test Cases
### TC-001: New User Registration
1. Navigate to http://localhost:3000/register
2. Enter email "test+{timestamp}@example.com"
3. Enter password "SecurePass123!"
4. Click the "Sign Up" button
5. Verify redirect to the dashboard page
6. Verify the username appears in the header
### TC-002: Login
1. Navigate to http://localhost:3000/login
2. Log in with the credentials above
3. Verify a "Welcome back" message appears
### TC-003: Logout
1. Click the user avatar in the header
2. Select "Sign Out"
3. Verify redirect to the login page
## Pass Criteria
- No error messages appear at any step
- Redirects complete within 3 seconds
- Screenshots show no layout breakageStep 2: Triggering the Agent
In Antigravity's Agent chat (Editor View sidebar):
@browser Run all tests in e2e/auth-flow.agent.md.
Start the dev server first if it's not running.
Save screenshots to .agent-artifacts/screenshots/.
The agent will automatically:
- Start the dev server via
npm run dev - Execute each test case in sequence
- Capture screenshots at each step
- Generate a test results report as an Artifact
Step 3: Structured YAML for Complex Flows
For multi-step checkout or onboarding flows, structured YAML gives you more precision:
# e2e/checkout-flow.agent.yaml
name: "Checkout Flow E2E"
base_url: "http://localhost:3000"
timeout_seconds: 60
retry_on_failure: 2
setup:
- action: navigate
url: "/login"
- action: fill
selector_hint: "Email address input"
value: "buyer@example.com"
- action: fill
selector_hint: "Password input"
value: "TestPass123!"
- action: click
selector_hint: "Login button"
- action: wait_for
condition: "URL contains /dashboard"
tests:
- name: "Add item to cart"
steps:
- action: navigate
url: "/products/premium-widget"
- action: screenshot
name: "product-page"
- action: click
selector_hint: "Add to Cart primary button"
- action: assert
condition: "Cart icon badge shows the number 1"
screenshot: "cart-badge-check"
- name: "Complete checkout"
steps:
- action: navigate
url: "/cart"
- action: click
selector_hint: "Proceed to Checkout button"
- action: fill
selector_hint: "Credit card number field"
value: "4242 4242 4242 4242"
- action: fill
selector_hint: "Expiration date"
value: "12/28"
- action: fill
selector_hint: "CVV"
value: "123"
- action: click
selector_hint: "Place Order button"
- action: assert
condition: "Order confirmation message is visible"
screenshot: "order-complete"
teardown:
- action: navigate
url: "/account/orders"
- action: screenshot
name: "order-history"Building Visual Regression Tests
Visual regression testing is where the Browser Sub-Agent truly shines. By combining Gemini's vision capabilities with pixel-level comparison, you get both semantic and structural diff detection.
Step 1: Capture Baseline Screenshots
<!-- e2e/visual-baseline.agent.md -->
# Visual Baseline Capture
## Purpose
Capture baseline screenshots for key pages to establish a visual ground truth.
## Pages to Capture
- / (Home) — desktop and mobile
- /pricing (Pricing page)
- /dashboard (Post-login)
- /settings (User settings)
## Output Directory
.agent-artifacts/baseline/
## Notes
- Mask dynamic content (timestamps, random values)
- Capture full-page screenshots for scrollable pagesAgent prompt:
@browser Run e2e/visual-baseline.agent.md.
Save baselines to .agent-artifacts/baseline/.
Use {page-name}-{viewport}.png naming format.
Step 2: Running a Regression Check
After making code changes:
@browser Run visual regression check.
Compare current state against .agent-artifacts/baseline/.
Flag any page with more than 2% visual diff.
Save diff images to .agent-artifacts/diffs/.
The agent uses Gemini Vision to re-screenshot each page, then runs both pixel-level and semantic comparison against the baseline.
Step 3: Automated Report Generation
<!-- e2e/generate-report.agent.md -->
# Visual Regression Report Generator
## Input
- Baseline: .agent-artifacts/baseline/
- Current: .agent-artifacts/current/
- Diffs: .agent-artifacts/diffs/
## Output
Generate a report at .agent-artifacts/visual-regression-report.md including:
- List of changed pages
- Per-page change percentage
- Links to diff images
- Pass/Fail verdict (threshold: 2%)
- Change analysis (layout shift? Intentional update? CSS regression?)CI/CD Integration with GitHub Actions
Full Workflow Configuration
# .github/workflows/e2e-tests.yml
name: E2E Tests with Antigravity Browser Agent
on:
pull_request:
branches: [main, develop]
push:
branches: [main]
jobs:
e2e-test:
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: "20"
cache: "npm"
- name: Install dependencies
run: npm ci
- name: Build application
run: npm run build
- name: Start application
run: npm run start &
env:
PORT: 3000
NODE_ENV: test
- name: Wait for server to be ready
run: npx wait-on http://localhost:3000 --timeout 30000
- name: Install Antigravity CLI
run: npm install -g @google/antigravity-cli
- name: Run E2E tests via Browser Agent
run: |
antigravity agent run \
--task "Run all tests in e2e/auth-flow.agent.md. Generate a detailed error report if any test fails." \
--output .agent-artifacts/ci-report.md \
--timeout 1200 \
--headless true
env:
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
ANTIGRAVITY_TOKEN: ${{ secrets.ANTIGRAVITY_TOKEN }}
- name: Run Visual Regression Tests
run: |
antigravity agent run \
--task "Run visual regression check. List any pages with more than 2% visual diff." \
--output .agent-artifacts/visual-report.md \
--timeout 600 \
--headless true
env:
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
ANTIGRAVITY_TOKEN: ${{ secrets.ANTIGRAVITY_TOKEN }}
- name: Upload test artifacts
uses: actions/upload-artifact@v4
if: always()
with:
name: e2e-artifacts-${{ github.sha }}
path: .agent-artifacts/
retention-days: 14
- name: Comment PR with results
if: github.event_name == 'pull_request'
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
const report = fs.readFileSync('.agent-artifacts/ci-report.md', 'utf8');
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: `## 🤖 E2E Test Results\n\n${report}`
});Required Secrets
Add these in your repo under Settings → Secrets and variables → Actions:
GEMINI_API_KEY=your-gemini-api-key
ANTIGRAVITY_TOKEN=your-antigravity-token
Advanced Pattern: Parallel Multi-Agent Testing
Applying techniques from Advanced Multi-Agent Orchestration, you can run multiple browser agents in parallel to dramatically cut test execution time:
<!-- e2e/parallel-test-orchestration.agent.md -->
# Parallel E2E Test Orchestration
## Parallel Execution Plan
Use Agent Manager to run the following simultaneously:
### Agent A: Auth Flow
- Execute: e2e/auth-flow.agent.md
- Port: 3000
### Agent B: E-Commerce Flow
- Execute: e2e/checkout-flow.agent.yaml
- Port: 3001 (separate instance)
### Agent C: Visual Regression
- Execute: e2e/visual-baseline.agent.md
- Port: 3002 (separate instance)
## Sync Point
After all agents complete, generate consolidated-report.md.
If any agent fails, include all agent results in the report.Manager prompt:
@manager Run e2e/parallel-test-orchestration.agent.md.
Launch 3 agents in parallel and generate a consolidated report once all complete.
For a deep dive into Manager Surface orchestration, see Manager Surface Guide.
Troubleshooting
Error 1: Browser Sub-Agent: Navigation timeout
Cause: App startup is slow, or the network is unstable. Fix: Extend timeout values in AGENTS.md:
## Browser Sub-Agent
- page_load_timeout: 30000 # Extended from default 10000
- action_timeout: 15000
- retry_on_timeout: 3Error 2: Gemini Vision: Element not found
Cause: Low contrast UI, loading spinners, or ambiguous element descriptions. Fix: Use more specific semantic hints with stability checks:
# Vague (fails)
- action: click
selector_hint: "button"
# Specific (works)
- action: click
selector_hint: "Blue primary 'Add to Cart' button below the product image"
wait_for_stable: true # Wait for animations to completeError 3: Rate limit exceeded / Quota errors
Browser Sub-Agent is Gemini API-intensive. Long test suites can hit quota limits.
## Browser Sub-Agent
- screenshot_frequency: "on_failure_only"
- max_vision_calls_per_session: 100
- compress_screenshots: trueError 4: Headless mode: CSS rendering discrepancies
Cause: Fonts and CSS animations may behave differently in headless Chromium. Fix:
## Browser Sub-Agent
- headless: false # Use headed mode to debug visually
- disable_animations: true
- font_rendering: "force-color-profile"Performance Optimization
Managing Gemini Vision API Costs
The primary cost driver for Browser Sub-Agent is the number of Gemini Vision API calls. Here's a practical breakdown:
| Strategy | Impact | Configuration |
|---|---|---|
| Screenshot compression | 40–60% cost reduction | compress_screenshots: true |
| Failure-only screenshots | 70% fewer calls | screenshot_frequency: on_failure_only |
| Reduced viewport | Smaller image size | viewport: {width: 1024, height: 768} |
| DOM snapshot caching | Avoids re-scanning unchanged pages | cache_dom_snapshot: true |
Parallelization Time Savings
Sequential (5 tests × 2 min each) = 10 minutes
Parallel (5 tests ÷ 3 agents) = ~3 min 20 sec (67% faster)
Local Cache Configuration
## AGENTS.md
## Browser Sub-Agent
- dom_cache_ttl: 300 # Cache DOM snapshots for 5 minutes
- asset_cache: true # Cache static assets
- reuse_browser_context: true # Reuse browser context across sessionsConclusion
Antigravity's Browser Sub-Agent doesn't just automate testing — it changes how you think about test coverage. Instead of maintaining brittle selector-based scripts, you describe what your app should do and look like, and let Gemini handle the rest.
Three concrete steps to get started today:
- Create AGENTS.md in your project root to enable Browser Sub-Agent
- Write one auth flow spec (auth-flow.agent.md) and run it with
@browser - Add the GitHub Actions workflow so every PR gets auto-tested
For parallel multi-agent test orchestration, see Advanced Multi-Agent Orchestration. For combining Browser Sub-Agent with Playwright MCP, see Playwright MCP + Antigravity Integration.