skiritai 0.0.3

AI-driven browser test automation framework

Skiritai

AI-Powered Test Automation Agent

Named after the Skiritai — Sparta's elite reconnaissance troops who scouted the path ahead of the main army.

English | 中文

---

What is Skiritai?

Skiritai is an AI-driven browser test automation framework that scouts automation paths before executing them.

Like the ancient Skiritai who reconnoitered the terrain before the Spartan army advanced, Skiritai's agent first explores the target application — navigating pages, discovering UI elements, and figuring out the correct sequence of actions — then generates replayable scripts that can execute the same path at 30x speed without any AI inference.

Explore Mode (Scout the path)
  AI Agent → analyze page → decide actions → generate scripts
         ↓
Replay Mode (Execute the proven path)
  Script → direct execution → no AI needed → 30x faster

Key Features

Feature	Description
Explore → Replay Loop	AI explores and generates scripts on first run; replays them instantly on subsequent runs
30x Performance	Replay mode skips AI inference entirely — 74s → 2.5s
Python-native Cases	Define test cases as Python classes with decorators
Auto-Solidification	Successful explorations are automatically saved as replayable scripts
Multi-level Fallback	fill → click_force → eval_js for resilient element interaction
Flexible LLM	Supports OpenAI, Anthropic, Qwen, and any compatible API
Optional Web UI	FastAPI backend with REST + WebSocket for external frontends
CLI	skiritai run/serve/list/browser commands

How It Works

from skiritai import BaseCase, step_mode

class SearchTest(BaseCase):
    async def setup(self):
        await self.launch_browser()

    async def teardown(self):
        await self.close_browser()

    async def open_site(self, ai):
        await ai.action("Navigate to https://example.com")

    @step_mode("explore")  # Force AI exploration for this step
    async def search(self, ai):
        await ai.action("Search for 'automation testing'")

    async def verify(self, ai):
        await ai.action("Verify search results are displayed")

First run — AI explores each step, generates scripts:

[Step] open_site   (explore)  → 20s  → scripts/open_site.py   ✓
[Step] search      (explore)  → 30s  → scripts/search.py      ✓
[Step] verify      (explore)  → 24s  → scripts/verify.py      ✓
Total: 74s

Second run — scripts replay directly, no AI:

[Step] open_site   (replay)   → 0.8s → direct execution       ✓
[Step] search      (replay)   → 0.8s → direct execution       ✓
[Step] verify      (replay)   → 0.8s → direct execution       ✓
Total: 2.5s

Quick Start

1. Install

pip install skiritai
playwright install chromium

2. Configure

# .env
OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o

3. Run

# Run an example case
skiritai run examples/minimal

# List available cases
skiritai list examples/

Or programmatically:

import asyncio
from pathlib import Path
from skiritai import run_case

report = asyncio.run(run_case(Path("examples/minimal")))
print(report)

4. (Optional) Start Web Server

pip install skiritai[web]
skiritai serve --host 0.0.0.0 --port 8000

Project Structure

skiritai/
├── core/                      # Core engine (always installed)
│   ├── agent_loop.py          # LangGraph ReAct Agent
│   ├── ai_context.py          # Explore/Replay execution context
│   ├── base_case.py           # Test case base class
│   ├── runner.py              # Case discovery and execution
│   ├── tools.py               # Playwright tool set (14 tools)
│   ├── browser.py             # Browser lifecycle management
│   └── ...
├── llm/                       # LLM provider abstraction
│   ├── openai_provider.py
│   └── anthropic_provider.py
├── events/                    # Event bus
├── web/                       # [optional] FastAPI server (pip install skiritai[web])
│   ├── app.py                 # Application factory
│   ├── routers/               # REST + WebSocket endpoints
│   └── ws_manager.py          # Event → WebSocket bridge
└── cli.py                     # CLI entry point

examples/                      # Sample test cases
├── minimal/                   # Pure Playwright, no AI needed
├── baidu_search/              # AI-driven with replay scripts
└── playwright_docs/           # Exploration example

tests/                         # Framework tests
├── unit/
├── functional/
├── acceptance/
└── e2e/

CLI Commands

skiritai run <case_dir>               # Run a test case
skiritai serve [--host] [--port]       # Start web server
skiritai list [cases_root]            # List available cases
skiritai browser status [case_dir]    # Check persistent browser session
skiritai browser cleanup [case_dir]   # Kill orphan browser process

Tool Set

14 Playwright tools available to the AI agent:

Tool	Description
navigate	Navigate to URL
click	Click element
click_force	Force click (for hidden elements)
fill	Fill input field
type_text	Type character by character
focus	Focus on element
get_text	Get element text content
get_page_info	Get page title, URL, and text summary
wait_for	Wait for element to appear
scroll	Scroll page
eval_js	Execute JavaScript
select_option	Select dropdown option
hover	Hover over element
screenshot	Capture page screenshot

Execution Modes

Control how each step executes via ai.action() or the @step_mode decorator:

Mode	Behavior	Use Case
auto (default)	Replay if script exists, otherwise explore	Most steps
explore	Always use AI, overwrite existing script	New features, re-exploration
replay	Always replay, error if no script	CI/CD regression

# Via decorator
@step_mode("explore")
async def my_step(self, ai):
    await ai.action("...")

# Via parameter (overrides decorator)
await ai.action("...", mode="replay")

---

Author

Joe Shen

---

License

Contributing

Contributions, issues, and feature requests are welcome!