@desplega.ai/qa-use 2.8.7 → 2.9.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@desplega.ai/qa-use",
-    "version": "2.8.7",
+    "version": "2.9.0",
     "packageManager": "bun@^1.3.4",
     "description": "QA automation tool for browser testing with MCP server support",
     "type": "module",
@@ -37,10 +37,12 @@
         "test:unit": "node scripts/test-unit.js",
         "test:integration": "node scripts/test-integration.js",
         "test:coverage": "bun test --coverage --preload ./test-setup.ts",
+        "generate:docs": "tsx scripts/generate-docs.ts",
         "generate:readme": "node scripts/generate-readme-tools.js",
         "generate:types": "tsx scripts/generate-types.ts",
+        "check:docs": "tsx scripts/generate-docs.ts && git diff --exit-code src/cli/generated/docs-content.ts || (echo '❌ Docs content is stale — run bun run generate:docs and commit the result' && exit 1)",
         "release": "bun scripts/release.ts",
-        "prepublishOnly": "bun run build && bun lint && bun typecheck",
+        "prepublishOnly": "bun run generate:docs && bun run check:docs && bun run build && bun lint && bun typecheck",
         "cc:validate": "claude plugin validate ."
     },
     "keywords": [

package/dist/src/cli/commands/docs.d.ts

@@ -0,0 +1,6 @@
+/**
+ * qa-use docs - Access bundled documentation and reference guides
+ */
+import { Command } from 'commander';
+export declare const docsCommand: Command;
+//# sourceMappingURL=docs.d.ts.map

package/dist/src/cli/commands/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/docs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6BpC,eAAO,MAAM,WAAW,SAgDpB,CAAC"}

package/dist/src/cli/commands/docs.js

@@ -0,0 +1,71 @@
+/**
+ * qa-use docs - Access bundled documentation and reference guides
+ */
+import { Command } from 'commander';
+import { MAIN_DOC, REFERENCE_DOCS, TEMPLATES } from '../generated/docs-content.js';
+import { error, info } from '../lib/output.js';
+const TOPIC_KEYS = Object.keys(REFERENCE_DOCS);
+const TEMPLATE_KEYS = Object.keys(TEMPLATES);
+function printList() {
+    console.log(info('Available documentation topics:\n'));
+    console.log('  Reference Guides:');
+    for (const key of TOPIC_KEYS) {
+        console.log(`    ${key.padEnd(22)} ${REFERENCE_DOCS[key].title}`);
+    }
+    console.log('\n  Templates:');
+    console.log(`    ${'templates'.padEnd(22)} List all test templates`);
+    for (const key of TEMPLATE_KEYS) {
+        console.log(`    template:${key.padEnd(14)} ${TEMPLATES[key].title}`);
+    }
+    console.log(`
+Usage:
+  qa-use docs                      Main documentation
+  qa-use docs browser-commands     Browser commands reference
+  qa-use docs templates            List all templates
+  qa-use docs template:auth-flow   Show auth flow template`);
+}
+export const docsCommand = new Command('docs')
+    .description('Show documentation and reference guides')
+    .argument('[topic]', 'Topic to display (use --list to see available topics)')
+    .option('--list', 'List available documentation topics')
+    .action(async (topic, options) => {
+    if (options.list) {
+        printList();
+        return;
+    }
+    // No topic: show main doc
+    if (!topic) {
+        process.stdout.write(`${MAIN_DOC}\n`);
+        return;
+    }
+    // Check reference docs
+    if (topic in REFERENCE_DOCS) {
+        process.stdout.write(`${REFERENCE_DOCS[topic].content}\n`);
+        return;
+    }
+    // "templates" lists available templates
+    if (topic === 'templates') {
+        console.log(info('Available test templates:\n'));
+        for (const key of TEMPLATE_KEYS) {
+            console.log(`  ${key.padEnd(16)} ${TEMPLATES[key].title}`);
+        }
+        console.log('\nUsage: qa-use docs template:<name>');
+        return;
+    }
+    // "template:<name>" shows a specific template
+    if (topic.startsWith('template:')) {
+        const name = topic.slice('template:'.length);
+        if (name in TEMPLATES) {
+            process.stdout.write(`${TEMPLATES[name].content}\n`);
+            return;
+        }
+        console.log(error(`Unknown template: "${name}"`));
+        console.log(`Available: ${TEMPLATE_KEYS.join(', ')}`);
+        process.exit(1);
+    }
+    // Unknown topic
+    console.log(error(`Unknown topic: "${topic}"`));
+    console.log("Run 'qa-use docs --list' to see available topics.");
+    process.exit(1);
+});
+//# sourceMappingURL=docs.js.map

package/dist/src/cli/commands/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../../../src/cli/commands/docs.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/commands/setup.d.ts

@@ -1,5 +1,5 @@
 /**
- * qa-use setup - Interactive API key configuration
+ * qa-use setup - API key configuration (interactive and headless)
  */
 import { Command } from 'commander';
 export declare const setupCommand: Command;

package/dist/src/cli/commands/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/setup.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,eAAO,MAAM,YAAY,SA2DrB,CAAC"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/setup.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,eAAO,MAAM,YAAY,SAmIrB,CAAC"}

package/dist/src/cli/commands/setup.js

@@ -1,48 +1,108 @@
 /**
- * qa-use setup - Interactive API key configuration
+ * qa-use setup - API key configuration (interactive and headless)
  */
 import * as readline from 'node:readline/promises';
 import { Command } from 'commander';
 import { ApiClient } from '../../../lib/api/index.js';
-import { loadConfig, saveConfig } from '../lib/config.js';
-import { error, formatError, success } from '../lib/output.js';
+import { configExists, loadConfig, saveConfig } from '../lib/config.js';
+import { error, formatError, info, success, warning } from '../lib/output.js';
 export const setupCommand = new Command('setup')
     .description('Configure API key and default settings')
-    .action(async () => {
-    const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
-    });
+    .option('--api-key <key>', 'API key for authentication')
+    .option('--test-dir <path>', 'Test directory path (default: ./qa-tests)')
+    .option('--api-url <url>', 'Override API base URL')
+    .option('--skip-validation', 'Skip API key validation (offline/CI)')
+    .option('-y, --yes', 'Auto-confirm with current/default values')
+    .action(async (options) => {
     try {
-        console.log('🔧 QA-Use Setup\n');
-        // Load existing config
         const config = await loadConfig();
-        // Ask for API key
-        const apiKey = await rl.question(`API Key${config.api_key ? ` (current: ${config.api_key.slice(0, 8)}...)` : ''}: `);
-        if (apiKey.trim()) {
-            // Validate API key
-            const client = new ApiClient();
-            client.setApiKey(apiKey.trim());
-            console.log('\n  Validating API key...');
-            const validation = await client.validateApiKey();
-            if (validation.success) {
-                config.api_key = apiKey.trim();
-                console.log(success('API key validated'));
-                // Get default app config if available
-                if (validation.data?.app_config?.id) {
-                    config.default_app_config_id = validation.data.app_config.id;
-                    console.log(success(`Default app config: ${validation.data.app_config.id}`));
+        const hasExistingConfig = await configExists();
+        const hasAnyOption = !!(options.apiKey ||
+            options.testDir ||
+            options.apiUrl ||
+            options.skipValidation ||
+            options.yes);
+        // No-op: already configured and no options provided
+        if (hasExistingConfig && config.api_key && !hasAnyOption) {
+            console.log(success('Already configured (.qa-use-tests.json)'));
+            console.log(`  API key:    ${config.api_key.slice(0, 8)}...`);
+            console.log(`  Test dir:   ${config.test_directory || './qa-tests'}`);
+            if (config.default_app_config_id) {
+                console.log(`  App config: ${config.default_app_config_id}`);
+            }
+            console.log(`\n  Run ${info("'qa-use info'")} for full details, or pass options to update.`);
+            return;
+        }
+        // Determine mode
+        const isHeadless = !!options.apiKey;
+        const isAutoConfirm = !!options.yes;
+        let apiKey;
+        let testDir;
+        if (isHeadless) {
+            // Headless mode: all values from CLI options
+            apiKey = options.apiKey;
+            testDir = options.testDir || config.test_directory || './qa-tests';
+        }
+        else if (isAutoConfirm) {
+            // Auto-confirm mode: use existing/default values
+            apiKey = config.api_key;
+            testDir = options.testDir || config.test_directory || './qa-tests';
+            if (!apiKey) {
+                console.log(error('No existing API key found. Use --api-key <key> or run interactive setup.'));
+                process.exit(1);
+            }
+        }
+        else {
+            // Interactive mode
+            console.log('🔧 QA-Use Setup\n');
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            try {
+                apiKey = (await rl.question(`API Key${config.api_key ? ` (current: ${config.api_key.slice(0, 8)}...)` : ''}: `)).trim();
+                if (!apiKey) {
+                    apiKey = config.api_key;
                 }
+                const testDirAnswer = (await rl.question(`Test directory (default: ${config.test_directory || './qa-tests'}): `)).trim();
+                testDir = testDirAnswer || config.test_directory || './qa-tests';
+            }
+            finally {
+                rl.close();
+            }
+        }
+        // Apply API URL override if provided
+        if (options.apiUrl) {
+            config.api_url = options.apiUrl;
+        }
+        // Validate and store API key
+        if (apiKey) {
+            if (options.skipValidation) {
+                config.api_key = apiKey;
+                console.log(warning("API key validation skipped. Run 'qa-use info' to verify."));
             }
             else {
-                console.log(error(`Invalid API key: ${validation.message}`));
-                process.exit(1);
+                const client = new ApiClient(config.api_url);
+                client.setApiKey(apiKey);
+                console.log('  Validating API key...');
+                const validation = await client.validateApiKey();
+                if (validation.success) {
+                    config.api_key = apiKey;
+                    console.log(success('API key validated'));
+                    if (validation.data?.app_config?.id) {
+                        config.default_app_config_id = validation.data.app_config.id;
+                        console.log(success(`Default app config: ${validation.data.app_config.id}`));
+                    }
+                }
+                else {
+                    console.log(error(`Invalid API key: ${validation.message}`));
+                    process.exit(1);
+                }
             }
         }
-        // Ask for test directory
-        const testDir = await rl.question(`Test directory (default: ${config.test_directory || './qa-tests'}): `);
-        if (testDir.trim()) {
-            config.test_directory = testDir.trim();
+        // Set test directory
+        if (testDir) {
+            config.test_directory = testDir;
         }
         // Save configuration
         await saveConfig(config);
@@ -52,8 +112,14 @@ export const setupCommand = new Command('setup')
         console.log(error(`Setup failed: ${formatError(err)}`));
         process.exit(1);
     }
-    finally {
-        rl.close();
-    }
 });
+setupCommand.addHelpText('after', `
+Examples:
+  qa-use setup                                    Interactive setup
+  qa-use setup --api-key sk-xxx                   Non-interactive with validation
+  qa-use setup --api-key sk-xxx --test-dir ./e2e  Custom test directory
+  qa-use setup --api-key sk-xxx --skip-validation Offline/CI setup
+  qa-use setup --yes                              Accept defaults for missing fields
+  qa-use setup                                    No-op if already configured
+`);
 //# sourceMappingURL=setup.js.map

package/dist/src/cli/commands/setup.js.map

@@ -1 +1 @@
-{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../../../src/cli/commands/setup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../../../src/cli/commands/setup.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/generated/docs-content.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Auto-generated documentation content for the docs command.
+ * DO NOT EDIT MANUALLY — Generated from plugins/qa-use/skills/qa-use/
+ * Run 'bun run generate:docs' to regenerate.
+ */
+export declare const MAIN_DOC = "---\nname: qa-use\ndescription: E2E testing and browser automation with qa-use CLI. Use when the user needs to run tests, verify features, automate browser interactions, or debug test failures.\nallowed-tools: Bash(qa-use *)\n---\n\n# qa-use\n\nE2E testing and browser automation for AI-driven development workflows.\n\n## Critical Insight: Plugin Commands as Shortcuts\n\n**For AI Harnesses (codex, opencode, etc.):**\n\nPlugin commands (slash commands like `/qa-use:verify`) are **convenience shortcuts** that wrap CLI workflows. Harnesses with only the Bash tool can access ALL functionality via CLI commands documented below.\n\n**Pattern throughout this document:**\n- **CLI Workflow**: Step-by-step CLI commands (works for ALL harnesses)\n- **Plugin Shortcut**: Optional slash command (convenience)\n\n## Core Workflow\n\n### 1. Browser Control & Session Lifecycle\n\n**CLI Workflow:**\n```bash\n# Create browser session\nqa-use browser create --viewport desktop\n\n# For localhost testing\nqa-use browser create --tunnel --no-headless\n\n# Navigate\nqa-use browser goto https://example.com\n\n# Snapshot to get element refs (ALWAYS do this before interacting)\nqa-use browser snapshot\n\n# Interact by ref\nqa-use browser click e3\nqa-use browser fill e5 \"text\"\n\n# Close\nqa-use browser close\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:explore https://example.com\n```\n(Wraps create + goto + snapshot with autonomous exploration)\n\n**Critical:** Always run `snapshot` before your **first** interaction on a page. Never guess element refs.\n\n**Snapshot Diff Feature (use it to avoid unnecessary snapshots):**\nAfter each action (goto, click, fill, etc.), the browser automatically shows DOM changes:\n- **Summary**: \"5 elements added, 1 element modified\"\n- **Added elements**: `+ [e54] generic \"Thanks for agreeing!\"` (green)\n- **Modified elements**: `~ [e18] checkbox \"I agree...\"` with `+attrs: checked, active` (yellow)\n- **Removed elements**: `- [e99] button \"Submit\"` (red)\n\n**When you can skip a full `snapshot`:** If the diff output from your last action already shows the element ref you need to interact with next, use it directly \u2014 no need for an intermediate `snapshot`. For example, if clicking a button shows `+ [e54] button \"Submit\"` in the diff, you can `click e54` immediately.\n\n**When you still need a full `snapshot`:** Run `snapshot` when you need to find elements that weren't in the diff (e.g., pre-existing elements you haven't interacted with yet), or when the diff was truncated (shows \"... and N more changes\").\n\n### 2. Understanding Blocks\n\n**What are blocks?**\n\nBlocks are atomic recorded interactions from a browser session. They are:\n- Automatically captured during any browser interaction (click, fill, goto, scroll, etc.)\n- Stored server-side with the session\n- Retrieved via `qa-use browser get-blocks`\n- The foundation for test generation\n\n**Why blocks matter:**\n- **Record-once, replay-many**: Interactive recording becomes automated test\n- **AI-friendly**: Agents can analyze blocks to understand user intent\n- **Version control**: Blocks stored with session enable test iteration\n- **Bridge CLI \u2192 Tests**: Natural workflow from exploration to automation\n\n**How blocks work:**\n\n```bash\n# 1. Create session and interact\nqa-use browser create --tunnel --no-headless\nqa-use browser goto https://example.com\nqa-use browser snapshot        # Returns: [ref=e1] button\nqa-use browser click e1        # Records as block\nqa-use browser fill e5 \"text\"  # Records as block\n\n# 2. Retrieve blocks (JSON array)\nqa-use browser get-blocks\n# Returns:\n# [\n#   {\"type\": \"goto\", \"url\": \"...\", \"timestamp\": \"...\"},\n#   {\"type\": \"click\", \"ref\": \"e1\", \"timestamp\": \"...\"},\n#   {\"type\": \"fill\", \"ref\": \"e5\", \"value\": \"text\", \"timestamp\": \"...\"}\n# ]\n\n# 3. Generate test YAML from blocks\nqa-use browser generate-test -n \"my_test\" -o qa-tests/my_test.yaml\n\n# 4. Run generated test\nqa-use test run my_test\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record start my_test\n# ... perform interactions ...\n/qa-use:record stop\n```\n(Wraps the interactive workflow with AI-powered test generation)\n\n### 3. Test Management\n\n**CLI Workflow:**\n```bash\n# Run test by name\nqa-use test run login\n\n# Run with autofix (AI self-healing)\nqa-use test run login --autofix\n\n# Validate syntax\nqa-use test validate login\n\n# Show test details\nqa-use test info login\n\n# List test runs\nqa-use test runs --status failed\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:test-run login --autofix\n```\n(Convenience shortcut for common test execution)\n\n### 4. Test Sync Lifecycle\n\n**CLI Workflow:**\n```bash\n# Pull tests from cloud\nqa-use test sync pull\n\n# Push all local tests to cloud\nqa-use test sync push --all\n\n# Push specific test\nqa-use test sync push --id <uuid>\n\n# Force push (overwrite conflicts)\nqa-use test sync push --force\n\n# Compare local vs cloud\nqa-use test diff login.yaml\n```\n\n**No Plugin Shortcut** - Use CLI commands directly\n\n## Essential Commands\n\n### Browser Session Management\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser create` | Create remote browser session |\n| `qa-use browser create --tunnel` | Create local browser with API tunnel |\n| `qa-use browser create --no-headless` | Show browser window (tunnel mode only) |\n| `qa-use browser create --viewport <size>` | Set viewport: `desktop`, `tablet`, `mobile` |\n| `qa-use browser create --ws-url <url>` | Connect to existing WebSocket browser |\n| `qa-use browser create --after-test-id <uuid>` | Run a test first, then become interactive |\n| `qa-use browser create --var <key=value>` | Override app config variables (repeatable) |\n| `qa-use browser list` | List active sessions |\n| `qa-use browser status` | Show current session details (app_url, recording_url, etc.) |\n| `qa-use browser close` | Close active session |\n\nSessions auto-persist in `~/.qa-use.json`. One active session = no `-s` flag needed.\n\n### Navigation\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser goto <url>` | Navigate to URL |\n| `qa-use browser back` | Go back |\n| `qa-use browser forward` | Go forward |\n| `qa-use browser reload` | Reload page |\n\n### Element Interaction\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser click <ref>` | Click element by ref |\n| `qa-use browser click --text \"Button\"` | Click by semantic description |\n| `qa-use browser fill <ref> \"value\"` | Fill input field |\n| `qa-use browser type <ref> \"text\"` | Type with delays (for autocomplete) |\n| `qa-use browser press <key>` | Press key (e.g., `Enter`, `Tab`) |\n| `qa-use browser check <ref>` | Check checkbox |\n| `qa-use browser uncheck <ref>` | Uncheck checkbox |\n| `qa-use browser select <ref> \"option\"` | Select dropdown option |\n| `qa-use browser hover <ref>` | Hover over element |\n| `qa-use browser scroll down 500` | Scroll by pixels |\n| `qa-use browser scroll-into-view <ref>` | Scroll element into view |\n| `qa-use browser drag <ref> --target <ref>` | Drag element to target |\n| `qa-use browser mfa-totp [ref] <secret>` | Generate TOTP code (optionally fill) |\n| `qa-use browser upload <ref> <file>...` | Upload file(s) to input (base64-encoded, works remote & tunnel) |\n\n### Inspection & Snapshot Diff\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser snapshot` | Get full ARIA tree with element refs (use only when diff output is insufficient) |\n| `qa-use browser url` | Get current URL |\n| `qa-use browser screenshot` | Save screenshot.png |\n| `qa-use browser screenshot file.png` | Save to custom path |\n| `qa-use browser screenshot --base64` | Output base64 to stdout |\n| `qa-use browser evaluate <expression>` | Execute JavaScript in browser context |\n\nThe snapshot-diff feature automatically displays DOM changes after each browser action:\n- **Added elements**: Shown with `+` prefix and green color \u2014 these refs are immediately usable\n- **Modified elements**: Shown with `~` prefix and yellow color, including attribute changes (`+attrs: checked`)\n- **Removed elements**: Shown with `-` prefix and red color \u2014 do NOT use these refs\n\n**Downloads:** When an action triggers a file download (e.g., clicking a download link), the response includes download info: filename, size, and a presigned URL. Use `qa-use browser downloads` to list all downloads or `--save <dir>` to save them locally.\n\nUse diff output to interact with newly appeared elements directly, without running a full `snapshot` first.\n\n### Test Operations\n\n| Command | Description |\n|---------|-------------|\n| `qa-use test run <name>` | Run test by name |\n| `qa-use test run --all` | Run all tests |\n| `qa-use test run <name> --tunnel` | Run with local browser tunnel |\n| `qa-use test run <name> --autofix` | Enable AI self-healing |\n| `qa-use test run <name> --update-local` | Persist AI fixes to file |\n| `qa-use test run <name> --download` | Download assets to `/tmp/qa-use/downloads/` |\n| `qa-use test run <name> --var key=value` | Override variable |\n| `qa-use test validate <name>` | Validate test syntax |\n| `qa-use test list` | List available tests |\n| `qa-use test info <name>` | Show test details (steps, tags, description) |\n| `qa-use test info --id <uuid>` | Show cloud test details by ID |\n| `qa-use test runs [name]` | List test run history |\n| `qa-use test runs --id <uuid>` | Filter runs by test ID |\n| `qa-use test runs --status failed` | Filter runs by status |\n| `qa-use test init` | Initialize test directory |\n| `qa-use test sync pull` | Pull tests from cloud |\n| `qa-use test sync push --all` | Push all local tests to cloud |\n| `qa-use test sync push --id <uuid>` | Push specific test |\n| `qa-use test sync push --force` | Push tests, overwriting conflicts |\n| `qa-use test diff <file>` | Compare local vs cloud test |\n| `qa-use test schema [path]` | View test definition schema |\n\n### API Operations (Dynamic OpenAPI)\n\n`qa-use api` dynamically discovers operations from `/api/v1/openapi.json` and caches metadata locally for offline fallback.\n\n| Command | Description |\n|---------|-------------|\n| `qa-use api ls` | List available `/api/v1/*` routes from OpenAPI |\n| `qa-use api ls --refresh` | Force refresh OpenAPI cache |\n| `qa-use api ls --offline` | Use cached OpenAPI metadata only |\n| `qa-use api /api/v1/tests` | Call endpoint (method inferred when possible) |\n| `qa-use api -X GET /api/v1/test-runs -f limit=5` | GET with query fields |\n| `qa-use api -X POST /api/v1/tests-actions/run --input body.json` | POST with JSON body file |\n| `qa-use api -X GET /api/v1/test-runs/<id>` | Fetch detail endpoint by ID |\n\n**No Plugin Shortcut** - Use CLI commands directly.\n\n### Logs & Debugging\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser logs console` | View console logs from session |\n| `qa-use browser logs console -s <id>` | View logs from specific/closed session |\n| `qa-use browser logs network` | View network request logs |\n| `qa-use browser logs network -s <id>` | View network logs from specific session |\n| `qa-use browser downloads` | List downloaded files from session |\n| `qa-use browser downloads --save <dir>` | Save downloaded files to local directory |\n| `qa-use browser downloads --json` | Output download info as JSON |\n\n### Test Generation\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser generate-test` | Generate test YAML from recorded session |\n| `qa-use browser generate-test -s <id>` | Generate from specific session |\n| `qa-use browser generate-test -n <name>` | Specify test name |\n| `qa-use browser generate-test -o <path>` | Specify output path |\n| `qa-use browser get-blocks` | Get recorded interaction blocks (JSON) |\n\n### Waiting\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser wait <ms>` | Fixed wait |\n| `qa-use browser wait-for-selector \".class\"` | Wait for selector |\n| `qa-use browser wait-for-load` | Wait for page load |\n\n### Variable Overrides\n\nUse `--var` to override app config variables at runtime. Common variables:\n\n| Variable | Description |\n|----------|-------------|\n| `base_url` | Base URL for the app (e.g., preview deployment URL) |\n| `login_url` | Login page URL |\n| `login_username` | Username/email for authentication |\n| `login_password` | Password for authentication |\n\nExample with ephemeral preview URL:\n```bash\nqa-use browser create --after-test-id <login-test-uuid> \\\n  --var base_url=https://preview-123.example.com \\\n  --var login_url=https://preview-123.example.com/auth/login\n```\n\n## Common Patterns\n\n### Pattern 1: Feature Verification\n\n**CLI Workflow:**\n```bash\n# 1. Search for existing test\nqa-use test list | grep \"login\"\n\n# 2. Run test with autofix\nqa-use test run login --autofix\n\n# 3. Debug failures\nqa-use browser logs console\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:verify \"login works with valid credentials\"\n```\n(Wraps the above CLI workflow with AI-powered test discovery and analysis)\n\n### Pattern 2: Record & Generate Test\n\n**CLI Workflow:**\n```bash\n# 1. Create session\nqa-use browser create --tunnel --no-headless\n\n# 2. Navigate and interact\nqa-use browser goto https://example.com\nqa-use browser snapshot\nqa-use browser click e1\nqa-use browser fill e5 \"test\"\n\n# 3. Generate test from blocks\nqa-use browser get-blocks\nqa-use browser generate-test -n \"my_test\"\n\n# 4. Run test\nqa-use test run my_test\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record start my_test\n# ... perform interactions ...\n/qa-use:record stop\n```\n\n### Pattern 3: Authenticated Exploration\n\n**CLI Workflow:**\n```bash\n# Create session that runs login test first\nqa-use browser create --after-test-id <login-test-uuid>\n\n# Session now authenticated, explore\nqa-use browser goto /dashboard\nqa-use browser snapshot\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:explore /dashboard\n```\n(Automatically handles auth detection and session creation)\n\n### Pattern 4: Edit Existing Test\n\n**CLI Workflow:**\n```bash\n# 1. Open test file in editor\nvim qa-tests/login.yaml\n\n# 2. Validate syntax\nqa-use test validate login\n\n# 3. Run to verify\nqa-use test run login\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record edit login\n```\n(AI-assisted editing with validation)\n\n### Pattern 5: Using Snapshot Diff to Avoid Unnecessary Snapshots\n\n**CLI Workflow:**\n```bash\n# Create session and navigate\nqa-use browser create --tunnel --no-headless\nqa-use browser goto https://evals.desplega.ai/checkboxes\n\n# goto shows diff \u2014 initial page load shows all elements:\n# Changes: 45 elements added\n# + [e18] checkbox \"I agree to the terms and conditions\"\n# + [e19] generic \"I agree to the terms and conditions\"\n\n# \u2705 Use ref from diff directly \u2014 no snapshot needed!\nqa-use browser click e18\n\n# Diff shows what changed:\n# Changes: 5 elements added, 1 element modified\n# + [e54] generic \"Thanks for agreeing!\"\n# + [e55] link \"Terms and Conditions\"\n# ~ [e18] checkbox \"I agree to the terms and conditions\"\n#     +attrs: active, checked\n\n# \u2705 Can click e55 directly from diff output \u2014 no snapshot needed!\nqa-use browser click e55\n\n# \u274C Need to find an element NOT in the diff? Now run snapshot:\nqa-use browser snapshot\n```\n\n**Key principle:** Use diff output as your primary source of element refs after actions. Only fall back to `snapshot` when you need to find elements that weren't in the diff.\n\n**Benefits:**\n- Fewer API calls = faster automation\n- Diff refs are always fresh (just returned from the server)\n- Instantly see what changed (new elements, attribute changes, removals)\n\n**No Plugin Shortcut** - Automatic feature in all browser commands\n\n## CI/CD Integration\n\n### Running Tests in CI\n\n**Environment Variables:**\n```bash\nexport QA_USE_API_KEY=\"your-api-key\"\nexport QA_USE_REGION=\"us\"  # Optional: \"us\" or \"auto\"\n```\n\n**Basic Test Execution:**\n```bash\n# Run all tests\nqa-use test run --all\n\n# Run specific tag\nqa-use test run --tag smoke\n\n# Exit codes: 0 = pass, 1 = fail\n```\n\n### GitHub Actions Example\n\n```yaml\nname: QA Tests\non: [push, pull_request]\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - uses: actions/setup-node@v3\n        with:\n          node-version: '20'\n      - name: Install qa-use\n        run: npm install -g @desplega.ai/qa-use\n      - name: Run tests\n        run: qa-use test run --all\n        env:\n          QA_USE_API_KEY: ${{ secrets.QA_USE_API_KEY }}\n```\n\n### Test Artifacts\n\n**Screenshots:**\n- Automatically saved on failure\n- Location: `/tmp/qa-use/downloads/` (local) or cloud (remote)\n\n**Logs:**\n- Console logs: `qa-use browser logs console -s <session-id>`\n- Network logs: `qa-use browser logs network -s <session-id>`\n\n## Advanced Topics\n\n### Localhost Testing (Tunnel Mode)\n\n**When to use tunnel mode:**\n\n```\nTesting localhost (http://localhost:3000)?\n  \u251C\u2500 YES \u2192 Use --tunnel\n  \u2502   \u2514\u2500 qa-use browser create --tunnel [--no-headless]\n  \u2502       (Starts local Playwright, creates localtunnel, keeps running)\n  \u2502\n  \u2514\u2500 NO (Public URL) \u2192 Use remote browser (default)\n      \u2514\u2500 qa-use browser create\n          (Uses desplega.ai cloud browser via WebSocket)\n```\n\n**The `--tunnel` flag is a binary choice:**\n- **Local tunnel mode**: Playwright on your machine + localtunnel\n- **Remote mode**: WebSocket URL to cloud-hosted browser\n\n**For test execution:**\n```bash\n# Local app\nqa-use test run my_test --tunnel [--headful]\n\n# Public app\nqa-use test run my_test\n```\n\n**Plugin shortcuts handle tunnel detection automatically:**\n```\n/qa-use:explore http://localhost:3000\n/qa-use:record start local_test\n```\n\nSee [references/localhost-testing.md](references/localhost-testing.md) for troubleshooting.\n\n### Session Persistence\n\nSessions are stored in `~/.qa-use.json` and have:\n- **TTL**: 30 minutes (default)\n- **Auto-resolve**: One active session = no `-s` flag needed\n- **Cleanup**: Automatic on timeout or explicit `browser close`\n\n### Block Limitations\n\n**What's captured:**\n- goto, click, fill, type, check, uncheck, select, hover\n- scroll, scroll-into-view, drag, upload, press\n\n**What's NOT captured:**\n- Assertions (must be added manually)\n- Waits (inferred from timing, may need adjustment)\n- Complex interactions (multi-drag, hover sequences)\n\n**Manual editing:** Edit generated YAML to add assertions and refine selectors.\n\n### WebSocket Sessions\n\n**Sharing sessions across processes:**\n```bash\n# Process 1: Create session\nqa-use browser create --tunnel\n# Output: ws://localhost:12345/browser/abc123\n\n# Process 2: Connect to session\nqa-use browser goto https://example.com --ws-url ws://localhost:12345/browser/abc123\n```\n\n## Deep-Dive References\n\n| Document | Description |\n|----------|-------------|\n| [browser-commands.md](references/browser-commands.md) | Complete browser CLI reference with all flags |\n| [test-format.md](references/test-format.md) | Full test YAML specification |\n| [localhost-testing.md](references/localhost-testing.md) | Tunnel setup for local development |\n| [failure-debugging.md](references/failure-debugging.md) | Failure classification and diagnostics |\n| [ci.md](references/ci.md) | CI/CD integration patterns and examples |\n\n## Templates\n\n| Template | Description |\n|----------|-------------|\n| [basic-test.yaml](templates/basic-test.yaml) | Simple navigation and assertion |\n| [auth-flow.yaml](templates/auth-flow.yaml) | Login flow with credentials |\n| [form-test.yaml](templates/form-test.yaml) | Form submission with validation |\n\n## Test Format Overview\n\n```yaml\nname: Login Test\ndescription: Validates login functionality with valid credentials\ntags:\n  - smoke\n  - auth\napp_config: <app-config-id>\nvariables:\n  email: test@example.com\n  password: secret123\ndepends_on: setup-test  # Optional\nsteps:\n  - action: goto\n    url: /login\n  - action: fill\n    target: email input\n    value: $email\n  - action: click\n    target: login button\n  - action: to_be_visible\n    target: dashboard\n```\n\nSee [references/test-format.md](references/test-format.md) for complete specification.\n\n## Common Mistakes\n\n| \u274C Wrong | \u2705 Correct |\n|---------|-----------|\n| `browser navigate <url>` | `browser goto <url>` |\n| `browser destroy` | `browser close` |\n| `browser close <session-id>` | `browser close` |\n| Guessing element refs | Use refs from diff output or `snapshot` |\n| Running `snapshot` after every action | Use diff output; only `snapshot` when needed |\n| Testing localhost without `--tunnel` | Use `--tunnel` flag |\n| `test sync --pull` | `test sync pull` (subcommand, not flag) |\n| `test sync --push` | `test sync push` (subcommand, not flag) |\n\n## npx Alternative\n\nAll commands use `qa-use` assuming global install. For one-off use:\n```bash\nnpx @desplega.ai/qa-use browser <command>\n```\n";
+export declare const REFERENCE_DOCS: Record<string, {
+    title: string;
+    content: string;
+}>;
+export declare const TEMPLATES: Record<string, {
+    title: string;
+    content: string;
+}>;
+//# sourceMappingURL=docs-content.d.ts.map

package/dist/src/cli/generated/docs-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-content.d.ts","sourceRoot":"","sources":["../../../../src/cli/generated/docs-content.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,QAAQ,oxpBA0nBpB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAgnD7E,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAiIxE,CAAC"}