Uses AI + iOS or Android emulators / web browsers to create automated test suites using simple instructions

Before running web tests with IntelliTester, you need to install Playwright browsers:

npx playwright install chromium
# Or for all browsers:
npx playwright install

IntelliTester can generate comprehensive documentation for AI assistants (Claude, GPT, etc.) to help them write effective tests.

Use the guide command to create an intellitester_guide.md file in your project:

intellitester guide
# Or use the alias:
intellitester init-guide

This generates a detailed reference document that AI assistants can read to understand:

• All action types and their syntax
• Target selector options (testId, text, css, xpath, role, description)
• Variable interpolation and built-in generators
• Best practices for test organization
• Common testing patterns (login flows, form submissions, email verification)
• Configuration options for tests, workflows, and pipelines

The guide is particularly useful when:

• Using AI assistants to generate test files
• Onboarding team members who use AI coding tools
• Maintaining consistent test patterns across a team

IntelliTester provides JSON schemas for YAML configuration files to enable autocomplete and validation in VS Code and other editors.

Add this to your .vscode/settings.json (or workspace settings):

{
  "yaml.schemas": {
    "./node_modules/intellitester/schemas/intellitester.config.schema.json": "intellitester.config.yaml",
    "./node_modules/intellitester/schemas/test.schema.json": "*.test.yaml",
    "./node_modules/intellitester/schemas/workflow.schema.json": "*.workflow.yaml",
    "./node_modules/intellitester/schemas/pipeline.schema.json": "*.pipeline.yaml"
  }
}

This enables:

• Auto-completion for all configuration properties
• Inline documentation and examples
• Real-time validation and error checking
• Type checking for action steps and configurations

If you're working on IntelliTester itself or want to use local schemas, use these paths instead:

{
  "yaml.schemas": {
    "./schemas/intellitester.config.schema.json": "intellitester.config.yaml",
    "./schemas/test.schema.json": "*.test.yaml",
    "./schemas/workflow.schema.json": "*.workflow.yaml",
    "./schemas/pipeline.schema.json": "*.pipeline.yaml"
  }
}

IntelliTester provides powerful debugging capabilities to help troubleshoot failing tests.

Run tests with the --debug flag to pause execution on failure and open the Playwright Inspector:

# Run with debug mode - pauses on failure
intellitester run tests/login.test.yaml --headed --debug

Add breakpoints directly in your test files using the debug action type. This pauses execution and opens the Playwright Inspector at that specific step:

# Add breakpoints in your test
steps:
  - type: navigate
    value: /signup
  - type: debug  # Pauses here, opens Playwright Inspector
  - type: input
    target: { testId: email }
    value: test@example.com

When execution pauses, you can:

• Inspect the current page state
• Step through actions manually
• Examine selectors and elements
• Continue execution when ready

Use errorIf to fail a step immediately when a condition is met, without waiting for timeouts:

steps:
  - type: tap
    target: { testId: login-btn }
    errorIf: not-found  # Fail immediately if element not found

  - type: assert
    target: { testId: welcome-msg }
    errorIf: not-visible  # Fail if element exists but not visible

  - type: input
    target: { testId: email }
    value: test@example.com
    errorIf: disabled  # Fail if input is disabled

Available conditions:

Note: testId now matches data-testid, id, and class attributes in that order.

IntelliTester automatically tracks resources created during tests and cleans them up after execution. This ensures tests don't leave behind database rows, files, users, or other artifacts.

IntelliTester includes cleanup providers for common backends:

• Appwrite - Delete rows, files, teams, users, memberships
• PostgreSQL - Delete rows and users
• MySQL - Delete rows and users
• SQLite - Delete rows and users

Configure cleanup in your test YAML files or global config:

# Using Appwrite (backwards compatible)
appwrite:
  endpoint: https://cloud.appwrite.io/v1
  projectId: ${APPWRITE_PROJECT_ID}
  apiKey: ${APPWRITE_API_KEY}
  cleanup: true
  cleanupOnFailure: true

# Or using the new cleanup config
cleanup:
  provider: appwrite
  parallel: false      # Sequential cleanup by default
  retries: 3           # Retry failed deletions

  # Provider-specific configuration
  appwrite:
    endpoint: ${APPWRITE_ENDPOINT}
    projectId: ${APPWRITE_PROJECT_ID}
    apiKey: ${APPWRITE_API_KEY}

  # Map resource types to cleanup methods
  types:
    row: appwrite.deleteRow
    team: appwrite.deleteTeam
    stripe_customer: stripe.deleteCustomer

  # Explicit handler files to load
  handlers:
    - ./src/cleanup/stripe.ts

  # Auto-discover handlers (enabled by default)
  discover:
    enabled: true
    paths:
      - ./tests/cleanup
    pattern: "**/*.ts"

Create custom handlers for resources not covered by built-in providers:

// intellitester.cleanup.ts (auto-discovered at project root)
import { defineCleanupHandlers } from 'intellitester/cleanup';
import Stripe from 'stripe';

export default defineCleanupHandlers({
  stripe_customer: async (resource) => {
    const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
    await stripe.customers.del(resource.id);
  },

  stripe_subscription: async (resource) => {
    const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
    await stripe.subscriptions.cancel(resource.id);
  },
});

Handlers are loaded in this order (later definitions override earlier ones):

1. Built-in provider methods (e.g., appwrite.deleteRow)
2. intellitester.cleanup.ts at project root
3. Files in discovery paths (default: tests/cleanup/**/*.ts)
4. Explicit handler files from config

In your app's server-side code, track resources for cleanup:

import { track } from 'intellitester/integration';

// Track a database row
await track({
  type: 'row',
  id: row.$id,
  databaseId: 'main',
  tableId: 'users',
});

// Track a team
await track({
  type: 'team',
  id: team.$id,
});

// Track a custom resource (requires custom handler)
await track({
  type: 'stripe_customer',
  id: customer.id,
});

The track() function is production-safe - it's a no-op if the required environment variables aren't set. IntelliTester sets these automatically during test execution.

IntelliTester can persist tracked resources to disk in addition to (or instead of) the in-memory tracking server. This helps recover from interrupted runs and enables cleanup even if the tracking server is unavailable.

By default, the executor sets:

• INTELLITESTER_TRACK_FILE to a JSONL file in .intellitester/track/TEST_SESSION_<id>.jsonl
• .intellitester/track/ACTIVE_TESTS.json for heartbeats and stale session pruning

You can override the session ID or tracking directory:

intellitester run --session-id my-session --track-dir .intellitester/track

If INTELLITESTER_TRACK_URL is set, track() will send HTTP requests and also append to the track file (when available). If only the file is set, track() writes locally.

IntelliTester supports three levels of test organization:

A single test with a sequence of steps. The most basic building block.

name: Login Test
platform: web
variables:
  EMAIL: test@example.com
steps:
  - type: navigate
    value: /login
  - type: input
    target: { testId: email }
    value: ${EMAIL}
  - type: input
    target: { testId: password }
    value: secret123
  - type: tap
    target: { text: Sign In }
  - type: assert
    target: { text: Welcome }

Multiple tests run in sequence with a shared browser session. Tests share cookies, local storage, and authentication state.

name: User Onboarding
platform: web
config:
  web:
    baseUrl: http://localhost:3000
continueOnFailure: false
tests:
  - file: ./signup.test.yaml
    id: signup
  - file: ./verify-email.test.yaml
    id: verify
    variables:
      EMAIL: ${signup.EMAIL}
  - file: ./complete-profile.test.yaml

Multiple workflows with shared browser session, dependencies, and variables. Pipelines orchestrate complex test suites with control over execution order and failure handling.

name: Full E2E Suite
platform: web
on_failure: skip  # skip | fail | ignore
cleanup_on_failure: true
config:
  web:
    baseUrl: http://localhost:3000
  webServer:
    command: npm run dev
    url: http://localhost:3000
    reuseExistingServer: true
    timeout: 30000
workflows:
  - file: ./auth.workflow.yaml
    id: auth
    on_failure: fail  # Stop pipeline if auth fails

  - file: ./dashboard.workflow.yaml
    id: dashboard
    depends_on: [auth]
    variables:
      USER_TOKEN: ${auth.TOKEN}

  - file: ./settings.workflow.yaml
    depends_on: [auth]
    on_failure: ignore  # Continue even if settings tests fail

  - file: ./cleanup.workflow.yaml
    depends_on: [dashboard, settings]

Workflow Properties:

Failure Handling (on_failure):

• skip - Skip dependent workflows, continue independent ones (default)
• fail - Stop the entire pipeline immediately
• ignore - Continue as if the workflow succeeded

Web Server (config.webServer):

Start a dev server automatically before running tests:

config:
  webServer:
    command: npm run dev        # Command to start server
    url: http://localhost:3000  # Wait for this URL
    reuseExistingServer: true   # Use existing if running
    timeout: 30000              # Startup timeout (ms)

Shared Browser Session:

All workflows in a pipeline share the same browser context, preserving:

• Cookies and session storage
• Authentication state
• Local storage data