actionbook-web-test

What this skill does

## When to Use This Skill

Activate when the user:

- Asks to "test", "verify", "check", or "validate" a website workflow
- Wants to run smoke tests or health checks on a web application
- Needs to verify a user flow works end-to-end (login, checkout, search, etc.)
- Asks to "run regression tests" or "does this still work?"
- Wants to confirm a deployment didn't break functionality
- Needs to monitor a website's functionality on a schedule
- Builds browser-based test suites without writing Playwright/Cypress code

## What actionbook-web-test Provides

actionbook-web-test transforms web tests from coded test scripts into **declarative YAML workflows** executed by AI agents via Actionbook CLI.

| Benefit | How |
|---------|-----|
| **AI-native recovery** | When a selector fails, the agent snapshots the live page and finds the equivalent element |
| **Actionbook-managed selectors** | Pre-verified selectors with health scores — no manual maintenance |
| **Cross-project reusability** | YAML workflows work anywhere Actionbook CLI is installed |
| **No test framework required** | No Playwright/Cypress/Jest setup — just `actionbook browser` commands |
| **Human-readable tests** | YAML workflows are readable by non-developers |
| **Visual test reports** | json-ui powered HTML reports with metrics, step details, and failure screenshots |

## Test Workflow Format

Tests are defined as YAML files in a `tests/` directory. Each file describes one test workflow.

```yaml
name: example-test
description: What this test verifies
url: https://example.com
tags: [smoke, critical]
timeout: 30000  # ms, default 30000

# Pre-fetch verified selectors from Actionbook
actions:
  - "example.com:/:default"

# Environment variables (support {{env.VAR}} templates)
env:
  USERNAME: "test-user"
  PASSWORD: "{{env.TEST_PASSWORD}}"

# Browser setup options
setup:
  headless: true
  auto_dismiss_dialogs: true
  no_animations: true

# Ordered test steps
steps:
  - name: Open page
    action: open
    url: "https://example.com"

  - name: Verify loaded
    assert:
      - type: element-exists
        selector: "#main-content"
```

Full schema reference: [workflow-format.md](references/workflow-format.md)

## Step Types

Each step has a `name` and either an `action` (browser command) or `assert` (verification checks).

### Actions → CLI Command Mapping

| Action | CLI Command | Required Fields |
|--------|-------------|-----------------|
| `open` | `actionbook browser open <url>` | `url` |
| `click` | `actionbook browser click "<selector>"` | `selector` |
| `fill` | `actionbook browser fill "<selector>" "value"` | `selector`, `value` |
| `type` | `actionbook browser type "<selector>" "value"` | `selector`, `value` |
| `select` | `actionbook browser select "<selector>" "value"` | `selector`, `value` |
| `hover` | `actionbook browser hover "<selector>"` | `selector` |
| `press` | `actionbook browser press <key>` | `key` |
| `wait` | `actionbook browser wait "<selector>"` | `selector` |
| `wait-fn` | `actionbook browser wait-fn "<expression>"` | `expression` |
| `wait-idle` | `actionbook browser wait-idle` | — | ⚠ Not supported in extension mode |
| `wait-nav` | `actionbook browser wait-nav` | — |
| `snapshot` | `actionbook browser snapshot` | — |
| `screenshot` | `actionbook browser screenshot` | — |
| `text` | `actionbook browser text [selector]` | `selector` (optional) |
| `eval` | `actionbook browser eval "expression"` | `expression` |
| `upload` | `actionbook browser upload "<selector>" "<file-path>"` | `selector`, `file_path` |
| `scroll` | `actionbook browser scroll <direction>` | `direction` (up/down/top/bottom/to) |
| `emulate` | `actionbook browser emulate <device>` | `device` |
| `info` | `actionbook browser info "<selector>"` | `selector` |
| `console` | `actionbook browser console --level error` | — |
| `close` | `actionbook browser close` | — |

### Step Options

```yaml
- name: Accept cookies if present
  action: click
  selector: "[data-testid='cookie-accept']"
  on_fail: continue     # skip | abort (default) | continue
  retry: 1              # override retry count
  timeout: 5000         # step-level timeout override
  condition: element-exists "[data-testid='cookie-banner']"
```

## Assertion Types

Steps can include `assert` blocks to verify expected outcomes. Common types listed below; see [assertion-types.md](references/assertion-types.md) for the complete reference.

| Type | Description | CLI Mapping |
|------|-------------|-------------|
| `text-contains` | Element text contains string | `browser text "<selector>"` + string check |
| `text-equals` | Element text exactly matches | `browser text "<selector>"` + exact match |
| `text-matches` | Text matches regex pattern | `browser text "<selector>"` + regex |
| `url-contains` | Current URL contains string | `browser eval "location.href"` |
| `url-equals` | Current URL exactly matches | `browser eval "location.href"` |
| `element-exists` | Element present in DOM | `browser wait "<selector>" --timeout 5000` |
| `element-not-exists` | Element NOT present | `browser eval "!document.querySelector(...)"` |
| `element-visible` | Element is visible | `browser eval` visibility check |
| `element-hidden` | Element hidden or absent | Inverse of `element-visible` |
| `element-count` | Element count matches condition | `browser eval "querySelectorAll(...).length"` |
| `attribute-equals` | Element attribute matches | `browser eval "getAttribute(...)"` |
| `attribute-contains` | Attribute contains substring | `browser eval "getAttribute(...)"` |
| `page-title-contains` | Page title contains string | `browser eval "document.title"` |
| `eval-truthy` | JS expression evaluates truthy | `browser eval "<expression>"` |
| `console-no-errors` | No JS errors in console | `browser console --level error` |
| `network-no-failures` | No HTTP 4xx/5xx errors | Network monitoring via CDP |
| `screenshot-match` | Visual regression comparison | `browser screenshot` + pixel diff |
| `performance-under` | Performance metric under threshold | `browser eval` performance timing |

### Assertion Examples

```yaml
# Text assertions
- name: Verify welcome message
  assert:
    - type: text-contains
      selector: "[data-testid='welcome']"
      value: "Welcome back"

# URL assertions
- name: Verify redirect
  assert:
    - type: url-contains
      value: "/dashboard"

# Element count with operator
- name: Verify search results
  assert:
    - type: element-count
      selector: ".search-result"
      operator: ">="
      value: 5

# JS evaluation
- name: Verify cart state
  assert:
    - type: eval-truthy
      expression: "JSON.parse(localStorage.getItem('cart')).items.length > 0"
```

## Execution Flow

### Step 0: Pre-flight Checks

Before running any test, verify the environment is ready:

```bash
# 1. Check browser connection
actionbook browser status
# If no browser → open one with setup flags

# 2. Verify target site is reachable (fast check, no rendering)
actionbook browser fetch <url> --format text --timeout 10000 --lite
# If fails → report site unreachable, skip all tests for this domain

# 3. Start console error monitoring
actionbook browser console --level error --duration 0 &
# Capture JS errors throughout the test session
```

Pre-flight failures should be reported clearly — distinguish "test failed" from "environment broken".

### Step 1: Discover

Parse YAML workflow files from the `tests/` directory. Filter by `--filter` flag (matches tags or name).

```bash
# Run all tests
/actionbook-web-test run tests/

# Run smoke tests only
/actionbook-web-test run tests/smoke/

# Filter by tag
/actionbook-web-test run tests/ --filter critical
```

### Step 2: Setup

For each workflow:
1. Pre-fetch selectors: `actionbook search` + `actionbook get "<action-id>"` for each entry in `actions`
2. Resolve template variables (`{{env.VAR}}`, `{{timestamp}}`, etc.)
3. Restore auth state if `setup.profile` is specified (cookies/storage from previous session)