qa-agent 0.2.2__tar.gz → 0.3.0__tar.gz

{qa_agent-0.2.2/qa_agent.egg-info → qa_agent-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qa-agent
-Version: 0.2.2
+Version: 0.3.0
 Summary: Agentic exploratory QA testing for web applications
 Author: Bill Richards
 License: MIT License
@@ -90,7 +90,8 @@ Need targeted tests? Pass plain-English instructions and an LLM generates custom
 
 ---
 
-## Table of Contents
+<details>
+<summary><strong>Table of Contents</strong></summary>
 
 - [Features](#features)
 - [Installation](#installation)
@@ -130,10 +131,9 @@ Need targeted tests? Pass plain-English instructions and an LLM generates custom
 
 ```bash
 pip install qa-agent            # standard testing (Playwright only)
-playwright install chromium     # required — downloads browser binaries
 ```
 
-Optional extras:
+Chromium is installed automatically on first run. Optional extras:
 
 ```bash
 pip install "qa-agent[pdf]"    # PDF reports (adds WeasyPrint)
@@ -148,7 +148,7 @@ export ANTHROPIC_API_KEY=sk-ant-...   # Anthropic (default)
 export OPENAI_API_KEY=sk-...          # OpenAI
 ```
 
-> `playwright install chromium` must run once after every fresh install. See [Troubleshooting](#troubleshooting) if anything goes wrong.
+> Chromium is installed automatically on the first run. If you need to reinstall it manually, run `playwright install chromium`.
 
 ---
 
@@ -194,6 +194,25 @@ print(f"Pages tested:   {len(session.pages_tested)}")
 print(f"Total findings: {session.total_findings}")
 ```
 
+Set `workers` to test pages in parallel, and use `BatchRunner` to run several
+independent sessions concurrently with a bounded pool:
+
+```python
+from qa_agent import BatchRunner, TestConfig
+
+configs = [
+    TestConfig(urls=["https://example.com"], workers=4),
+    TestConfig(urls=["https://other.test"]),
+]
+
+with BatchRunner(pool_size=4) as runner:
+    for result in runner.run_all(configs):
+        if isinstance(result, Exception):
+            print(f"session failed: {result}")
+        else:
+            print(f"{result.session_id}: {result.total_findings} findings")
+```
+
 → [Full Python API Reference](https://github.com/billrichards/qa-agent/blob/main/docs/api-reference.md) — all classes, methods, and configuration options.
 
 ---
@@ -308,6 +327,50 @@ qa-agent --mode focused https://example.com   # default — test only given URLs
 qa-agent --mode explore https://example.com    # crawl and test discovered pages
 ```
 
+### Concurrency
+
+Test multiple pages in parallel with cooperating workers. Each worker drives its
+own browser, so memory and CPU scale with the worker count (capped at 16).
+
+```bash
+qa-agent --workers 4 --mode explore https://example.com   # 4 pages at a time
+```
+
+Run several independent sessions concurrently from a JSON spec file. Each entry
+needs `urls` plus optional per-run overrides (`mode`, `max_depth`, `max_pages`,
+`instructions`, `workers`); all other settings come from the command-line flags.
+
+```bash
+qa-agent --batch-file runs.json --pool-size 4
+```
+
+```json
+[
+  {"urls": ["https://example.com"], "mode": "explore", "workers": 4},
+  {"urls": ["https://other.test/login"], "instructions": "Check the checkout flow"}
+]
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--workers N` | `1` | Concurrent page-workers per run (max 16) |
+| `--batch-file FILE` | — | JSON file of multiple runs to execute concurrently |
+| `--pool-size N` | `4` | Max concurrent runs for `--batch-file` (max 8) |
+| `--rate-limit N` | `3.0` | Max page navigations/sec to any single host (0 = unlimited) |
+
+> Total live browsers ≈ `pool-size × workers`, so size both with that
+> multiplicative cost in mind. The web API accepts the same `workers` value in
+> the `POST /api/run` body, and the pool size is set server-side via the
+> `QA_AGENT_JOB_POOL_SIZE` environment variable.
+
+By default, navigations to any single host are throttled to 3 requests/second
+across all workers and batch jobs, to avoid overwhelming dev/staging servers
+with "too many connections" when running with many concurrent browsers. Raise
+or disable this with `--rate-limit` (e.g. `--rate-limit 10` or `--rate-limit 0`
+for unlimited). The limit applies only to page navigations (`page.goto()`), not
+in-page interactions like clicks or form fills. The web server uses the same
+3 req/s default, overridable via the `QA_AGENT_RATE_LIMIT` environment variable.
+
 ### Exploration (explore mode)
 
 | Flag | Default | Description |
@@ -448,7 +511,6 @@ Six built-in suites cover keyboard navigation, mouse interaction, form handling,
     ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}   # or OPENAI_API_KEY
   run: |
     pip install qa-agent
-    playwright install chromium
     qa-agent --output json --output-dir ./qa-results https://staging.example.com
 
 - name: Upload Results
@@ -479,11 +541,13 @@ Exits with code `1` when critical or high severity issues are found, failing the
 
 ### Playwright browser not found
 
+Chromium is installed automatically on first run. If reinstalling is needed:
+
 ```bash
 playwright install chromium
 ```
 
-Must run once after every fresh install. Easy to forget in CI.
+If automatic installation fails, run the above command manually.
 
 ### Web UI not working
 

{qa_agent-0.2.2 → qa_agent-0.3.0}/README.md

@@ -23,7 +23,8 @@ Need targeted tests? Pass plain-English instructions and an LLM generates custom
 
 ---
 
-## Table of Contents
+<details>
+<summary><strong>Table of Contents</strong></summary>
 
 - [Features](#features)
 - [Installation](#installation)
@@ -63,10 +64,9 @@ Need targeted tests? Pass plain-English instructions and an LLM generates custom
 
 ```bash
 pip install qa-agent            # standard testing (Playwright only)
-playwright install chromium     # required — downloads browser binaries
 ```
 
-Optional extras:
+Chromium is installed automatically on first run. Optional extras:
 
 ```bash
 pip install "qa-agent[pdf]"    # PDF reports (adds WeasyPrint)
@@ -81,7 +81,7 @@ export ANTHROPIC_API_KEY=sk-ant-...   # Anthropic (default)
 export OPENAI_API_KEY=sk-...          # OpenAI
 ```
 
-> `playwright install chromium` must run once after every fresh install. See [Troubleshooting](#troubleshooting) if anything goes wrong.
+> Chromium is installed automatically on the first run. If you need to reinstall it manually, run `playwright install chromium`.
 
 ---
 
@@ -127,6 +127,25 @@ print(f"Pages tested:   {len(session.pages_tested)}")
 print(f"Total findings: {session.total_findings}")
 ```
 
+Set `workers` to test pages in parallel, and use `BatchRunner` to run several
+independent sessions concurrently with a bounded pool:
+
+```python
+from qa_agent import BatchRunner, TestConfig
+
+configs = [
+    TestConfig(urls=["https://example.com"], workers=4),
+    TestConfig(urls=["https://other.test"]),
+]
+
+with BatchRunner(pool_size=4) as runner:
+    for result in runner.run_all(configs):
+        if isinstance(result, Exception):
+            print(f"session failed: {result}")
+        else:
+            print(f"{result.session_id}: {result.total_findings} findings")
+```
+
 → [Full Python API Reference](https://github.com/billrichards/qa-agent/blob/main/docs/api-reference.md) — all classes, methods, and configuration options.
 
 ---
@@ -241,6 +260,50 @@ qa-agent --mode focused https://example.com   # default — test only given URLs
 qa-agent --mode explore https://example.com    # crawl and test discovered pages
 ```
 
+### Concurrency
+
+Test multiple pages in parallel with cooperating workers. Each worker drives its
+own browser, so memory and CPU scale with the worker count (capped at 16).
+
+```bash
+qa-agent --workers 4 --mode explore https://example.com   # 4 pages at a time
+```
+
+Run several independent sessions concurrently from a JSON spec file. Each entry
+needs `urls` plus optional per-run overrides (`mode`, `max_depth`, `max_pages`,
+`instructions`, `workers`); all other settings come from the command-line flags.
+
+```bash
+qa-agent --batch-file runs.json --pool-size 4
+```
+
+```json
+[
+  {"urls": ["https://example.com"], "mode": "explore", "workers": 4},
+  {"urls": ["https://other.test/login"], "instructions": "Check the checkout flow"}
+]
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--workers N` | `1` | Concurrent page-workers per run (max 16) |
+| `--batch-file FILE` | — | JSON file of multiple runs to execute concurrently |
+| `--pool-size N` | `4` | Max concurrent runs for `--batch-file` (max 8) |
+| `--rate-limit N` | `3.0` | Max page navigations/sec to any single host (0 = unlimited) |
+
+> Total live browsers ≈ `pool-size × workers`, so size both with that
+> multiplicative cost in mind. The web API accepts the same `workers` value in
+> the `POST /api/run` body, and the pool size is set server-side via the
+> `QA_AGENT_JOB_POOL_SIZE` environment variable.
+
+By default, navigations to any single host are throttled to 3 requests/second
+across all workers and batch jobs, to avoid overwhelming dev/staging servers
+with "too many connections" when running with many concurrent browsers. Raise
+or disable this with `--rate-limit` (e.g. `--rate-limit 10` or `--rate-limit 0`
+for unlimited). The limit applies only to page navigations (`page.goto()`), not
+in-page interactions like clicks or form fills. The web server uses the same
+3 req/s default, overridable via the `QA_AGENT_RATE_LIMIT` environment variable.
+
 ### Exploration (explore mode)
 
 | Flag | Default | Description |
@@ -381,7 +444,6 @@ Six built-in suites cover keyboard navigation, mouse interaction, form handling,
     ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}   # or OPENAI_API_KEY
   run: |
     pip install qa-agent
-    playwright install chromium
     qa-agent --output json --output-dir ./qa-results https://staging.example.com
 
 - name: Upload Results
@@ -412,11 +474,13 @@ Exits with code `1` when critical or high severity issues are found, failing the
 
 ### Playwright browser not found
 
+Chromium is installed automatically on first run. If reinstalling is needed:
+
 ```bash
 playwright install chromium
 ```
 
-Must run once after every fresh install. Easy to forget in CI.
+If automatic installation fails, run the above command manually.
 
 ### Web UI not working
 

{qa_agent-0.2.2 → qa_agent-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qa-agent"
-version = "0.2.2"
+version = "0.3.0"
 description = "Agentic exploratory QA testing for web applications"
 readme = "README.md"
 license = {file = "LICENSE"}

qa_agent-0.3.0/qa_agent/__init__.py

@@ -0,0 +1,45 @@
+"""
+QA Agent - Automated Exploratory Testing Tool
+
+A Python/Playwright-based QA agent that performs exploratory testing on web applications,
+testing various input methods and detecting UX issues.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("qa-agent")
+except PackageNotFoundError:
+    # Package not installed (e.g. running from source without install)
+    __version__ = "0.3.0"
+
+from .agent import QAAgent  # noqa: E402
+from .batch import BatchJob, BatchRunner  # noqa: E402
+from .config import (  # noqa: E402
+    AuthConfig,
+    OutputFormat,
+    RecordingConfig,
+    ScreenshotConfig,
+    TestConfig,
+    TestMode,
+)
+from .llm_client import LLMProvider  # noqa: E402
+from .models import Finding, PageAnalysis, Severity, TestSession  # noqa: E402
+
+__all__ = [
+    "QAAgent",
+    "BatchRunner",
+    "BatchJob",
+    "TestConfig",
+    "AuthConfig",
+    "ScreenshotConfig",
+    "RecordingConfig",
+    "TestMode",
+    "OutputFormat",
+    "LLMProvider",
+    "TestSession",
+    "PageAnalysis",
+    "Finding",
+    "Severity",
+    "__version__",
+]