web-squire

web-squire

Composable agentic UI testing, dashboard validation, and browser automation suite for Claude Code.

Built on the four-layer composable architecture from Bowser: Skill → Subagent → Command → Just.

Quick Start

Get from zero to running tests in 5 minutes.

1. Install the plugin

Inside Claude Code:

/plugin marketplace add https://github.com/cn-dataworks/web-squire-plugin
/plugin install web-squire

See INSTALL.md for alternative install methods and full details.

2. Install Playwright CLI

npm install -g @playwright/cli@latest
playwright-cli --help   # verify it works

3. Create a story file

In your project, create ai_user_stories/web/smoke-test.yaml:

stories:
  - name: "Homepage loads correctly"
    url: "https://myapp.example.com"
    workflow: |
      Navigate to https://myapp.example.com
      Verify the page loads without errors
      Verify a navigation bar is visible at the top
      Verify the main content area contains a heading

4. Run the tests

/web-squire:ui-review

5. What to expect

The command discovers your story files, spawns one QA agent per story, and each agent:

• Opens a browser session
• Executes your workflow steps sequentially
• Screenshots every step to screenshots/qa/
• Reports a pass/fail summary table

✅ SUCCESS

**Story:** Homepage loads correctly
**Steps:** 4/4 passed
**Screenshots:** ./screenshots/qa/homepage-loads-correctly_a1b2c3d4/

| # | Step | Status | Screenshot |
| --- | --- | --- | --- |
| 1 | Navigate to homepage | PASS | 00_navigate.png |
| 2 | Verify page loads | PASS | 01_page-loads.png |
| 3 | Verify nav bar | PASS | 02_nav-bar.png |
| 4 | Verify heading | PASS | 03_heading.png |

RESULT: PASS | Steps: 4/4

Which Command Do I Use?

I want to...	Command	Story directory
Test UI workflows (login, forms, navigation)	/web-squire:ui-review	ai_user_stories/web/
Validate dashboards visually (Power BI, Tableau)	/web-squire:test-dashboards	ai_user_stories/dashboard/
Scrape data or monitor pages	/web-squire:run-browser-automation	ai_user_stories/browser_automation/
Run a single saved workflow	/web-squire:automate <file>	Any path

Which Skill Do I Need?

Situation	Use	Why
Standard web testing (default)	playwright-cli	Headless, fast, supports parallel sessions
Site requires SSO/cookies/extensions	chrome-mcp	Uses your real Chrome session with existing auth
Not sure	playwright-cli	Works for 90% of cases

Note: When using commands (Layer 3), you don't pick skills directly — the agents choose automatically. Skill selection matters when you invoke skills directly at Layer 1.

Story File Format

Stories use a stories array with name, url, and workflow keys. The workflow field is natural language — be specific about what to verify.

QA story (for /web-squire:ui-review)

stories:
  - name: "User can login"
    url: "https://myapp.example.com/login"
    workflow: |
      Navigate to https://myapp.example.com/login
      Verify the login page loads with username and password fields
      Enter username "testuser" and password "testpass"
      Click the Login button
      Verify the dashboard page loads
      Verify the user's name appears in the top-right corner

  - name: "Dashboard shows recent activity"
    url: "https://myapp.example.com/dashboard"
    workflow: |
      Navigate to https://myapp.example.com/dashboard
      Verify the dashboard loads with an activity feed
      Verify at least 3 activity items are visible

Dashboard story (for /web-squire:test-dashboards)

Dashboard tests use vision mode automatically — the agent screenshots each step and visually reads chart values, KPIs, and filter states from the image.

stories:
  - name: "Revenue dashboard shows correct Q4 data"
    url: "https://app.powerbi.com/reports/abc123/ReportSection"
    workflow: |
      Navigate to the revenue dashboard
      Verify the dashboard loads with at least 3 chart tiles
      Click the Q4 filter button
      Verify the revenue chart updates to show Q4 data
      Verify the KPI card shows revenue above $2M
      Hover over the trend line chart and verify the tooltip shows monthly values

Data gathering story (for /web-squire:run-browser-automation)