{"_id":"@acr-edge/qecopilot","_rev":"4-0c6e9bc3e443ee15c80d51cf9d41fa17","name":"@acr-edge/qecopilot","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.0":{"name":"@acr-edge/qecopilot","version":"1.0.0","keywords":["qe","ai","testing","playwright","mcp","llm","agent","natural-language","test-automation"],"license":"MIT","_id":"@acr-edge/qecopilot@1.0.0","maintainers":[{"name":"akhtarrs","email":"akhtarrs@gmail.com"},{"name":"akhtar-research","email":"akhtar.research@gmail.com"}],"homepage":"https://github.com/acr-edge/qe-runtime","bugs":{"url":"https://github.com/acr-edge/ai-test-automation/issues"},"bin":{"qe":"bin/qe.cjs","qecopilot":"bin/qe.cjs"},"dist":{"shasum":"de2126191a161ba69adb1f59a1d800a6923c7e2f","tarball":"https://registry.npmjs.org/@acr-edge/qecopilot/-/qecopilot-1.0.0.tgz","fileCount":14,"integrity":"sha512-ZwxUdN+xCjuzdJ/L0kR9HSalZVnGZg29ysOJOJsGw6hnkBhVFz7XB5eQwLYu0DBoyRbelesSL4vucOC17ujQMg==","signatures":[{"sig":"MEUCIQC4Rl0omzDbvr2pBG5U+dbZp766cGTM7MYzNQOb5M67GgIgJ/pdayEjaRoM5DMR6nPb20FGUR5RSRWWAGKPixZS0Z4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3042423},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"437b8e1c4739d7ac03346668a91cdbf0f95de986","scripts":{"dev":"node --no-deprecation node_modules/.bin/tsx src/cli/index.ts","lint":"eslint .","test":"vitest run","build":"tsup","clean":"rimraf dist coverage","test:ui":"vitest --ui","lint:fix":"eslint . --fix","typecheck":"tsc --noEmit","test:watch":"vitest","build:watch":"tsup --watch","format:check":"prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"","format:write":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","test:coverage":"vitest run --coverage","prepublishOnly":"npm run clean && npm run build && npm run typecheck && npm run test"},"_npmUser":{"name":"akhtar-research","email":"akhtar.research@gmail.com"},"repository":{"url":"git+https://github.com/acr-edge/ai-test-automation.git","type":"git","directory":"qeruntime"},"_npmVersion":"11.0.0","description":"QE — AI-Native Multi-Agent Execution Platform for Natural Language Software Testing","directories":{},"_nodeVersion":"22.12.0","dependencies":{"ora":"^8.2.0","zod":"^3.25.42","glob":"^11.0.2","pino":"^9.6.0","chalk":"^5.4.1","dotenv":"^16.5.0","openai":"^4.103.0","adm-zip":"^0.5.17","fastify":"^5.3.2","js-yaml":"^4.1.0","commander":"^13.1.0","@fastify/cors":"^10.0.2","@anthropic-ai/sdk":"^0.52.0","@fastify/sensible":"^6.0.3","@google/generative-ai":"^0.24.1","@modelcontextprotocol/sdk":"^1.12.1","@aws-sdk/client-bedrock-runtime":"^3.1065.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.4","tsup":"^8.5.0","eslint":"^9.27.0","rimraf":"^6.0.1","vitest":"^3.2.2","globals":"^17.6.0","prettier":"^3.5.3","@vitest/ui":"^3.2.2","typescript":"^5.8.3","@types/node":"^22.15.21","@types/adm-zip":"^0.5.8","@types/js-yaml":"^4.0.9","@vitest/coverage-v8":"^3.2.2","eslint-config-prettier":"^10.1.5","@typescript-eslint/parser":"^8.33.1","@typescript-eslint/eslint-plugin":"^8.33.1"},"optionalDependencies":{"pino-pretty":"^13.0.0"},"_npmOperationalInternal":{"tmp":"tmp/qecopilot_1.0.0_1781297604023_0.8715396491319471","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@acr-edge/qecopilot","version":"1.0.1","keywords":["qe","ai","testing","playwright","mcp","llm","agent","natural-language","test-automation"],"license":"MIT","_id":"@acr-edge/qecopilot@1.0.1","maintainers":[{"name":"akhtarrs","email":"akhtarrs@gmail.com"},{"name":"akhtar-research","email":"akhtar.research@gmail.com"}],"homepage":"https://qecopilot.com","bugs":{"url":"https://github.com/acr-edge/qecopilot/issues"},"bin":{"qe":"bin/qe.cjs","qecopilot":"bin/qe.cjs"},"dist":{"shasum":"d050da47078cb501ecc83c6db71f491e929398fb","tarball":"https://registry.npmjs.org/@acr-edge/qecopilot/-/qecopilot-1.0.1.tgz","fileCount":13,"integrity":"sha512-D+bWDERimmyXcXmXRw+vbnIse+VTvUGSAQPezKZEF9OJOM4sL1wHIpMP9RUYQkz63PrLD2SS7PyR5DpFB12xdQ==","signatures":[{"sig":"MEUCIQC8qIPLCKHM2DQDZSFYcRZJIOMG6g+U8WNizLfTw3EDowIgDTWumH1fKjg9n7XVKqkI3xDg+kBLsHmE62TvQDhOrZg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3994183},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"464d9d9f91e121f04c6eb93029221211f114ff51","scripts":{"dev":"node --no-deprecation node_modules/.bin/tsx src/cli/index.ts","lint":"eslint .","test":"vitest run","build":"tsup","clean":"rimraf dist coverage","test:ui":"vitest --ui","lint:fix":"eslint . --fix","typecheck":"tsc --noEmit","test:watch":"vitest","build:watch":"tsup --watch","format:check":"prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"","format:write":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","test:coverage":"vitest run --coverage","prepublishOnly":"npm run clean && npm run build && npm run typecheck && npm run test"},"_npmUser":{"name":"akhtar-research","email":"akhtar.research@gmail.com"},"overrides":{"esbuild":"^0.28.1","form-data":"^4.0.6"},"repository":{"url":"git+https://github.com/acr-edge/qecopilot.git","type":"git","directory":"qecopilot"},"_npmVersion":"11.0.0","description":"QECopilot (🥝 KIWI) — AI-Native Multi-Agent Execution Platform for Natural Language Software Testing","directories":{},"_nodeVersion":"22.12.0","dependencies":{"ora":"^8.2.0","zod":"^3.25.42","glob":"^11.0.2","pino":"^9.6.0","chalk":"^5.4.1","dotenv":"^16.5.0","openai":"^4.103.0","adm-zip":"^0.5.17","fastify":"^5.3.2","js-yaml":"^4.1.0","commander":"^13.1.0","@fastify/cors":"^10.0.2","@anthropic-ai/sdk":"^0.52.0","@fastify/sensible":"^6.0.3","@google/generative-ai":"^0.24.1","@modelcontextprotocol/sdk":"^1.12.1","@aws-sdk/client-bedrock-runtime":"^3.1065.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.4","tsup":"^8.5.0","eslint":"^9.27.0","rimraf":"^6.0.1","vitest":"^3.2.2","globals":"^17.6.0","prettier":"^3.5.3","@vitest/ui":"^3.2.2","typescript":"^5.8.3","@types/node":"^22.15.21","@types/adm-zip":"^0.5.8","@types/js-yaml":"^4.0.9","@vitest/coverage-v8":"^3.2.2","eslint-config-prettier":"^10.1.5","@typescript-eslint/parser":"^8.33.1","@typescript-eslint/eslint-plugin":"^8.33.1"},"optionalDependencies":{"pino-pretty":"^13.0.0"},"_npmOperationalInternal":{"tmp":"tmp/qecopilot_1.0.1_1781575049570_0.609713393739983","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@acr-edge/qecopilot","version":"1.0.2","keywords":["qe","ai","testing","playwright","mcp","llm","agent","natural-language","test-automation"],"license":"Apache 2.0","_id":"@acr-edge/qecopilot@1.0.2","maintainers":[{"name":"akhtarrs","email":"akhtarrs@gmail.com"},{"name":"akhtar-research","email":"akhtar.research@gmail.com"}],"homepage":"https://qecopilot.com","bugs":{"url":"https://github.com/acr-edge/qecopilot/issues"},"bin":{"qe":"bin/qe.cjs","kiwi":"bin/qe.cjs","qecopilot":"bin/qe.cjs"},"dist":{"shasum":"4c856dd5645ab779cbce8e9dc3511171f0ac3fbb","tarball":"https://registry.npmjs.org/@acr-edge/qecopilot/-/qecopilot-1.0.2.tgz","fileCount":14,"integrity":"sha512-qAh2dK3hbcOZSwb/M+zgYPLrkGCUKs8U4tZFwttwYAW4HVyIvl3IH9EDcfafYmeD/OOi427XmkDfNla/SJdiqw==","signatures":[{"sig":"MEQCIF2JQ8z/8VUMbWGtaGdZLRHIpF7l79jPx36BW+3DB5eRAiAH21fE7lXqDdtQMMYE8AOlXUJeQeDtPiz/fo0guJzDVA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3981565},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=22.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"4e79d3626d88a23726fb02363b8bf79e26bc11eb","scripts":{"dev":"node --no-deprecation node_modules/.bin/tsx src/cli/index.ts","lint":"eslint .","test":"vitest run","build":"tsup","clean":"rimraf dist coverage","test:ui":"vitest --ui","lint:fix":"eslint . --fix","typecheck":"tsc --noEmit","test:watch":"vitest","build:watch":"tsup --watch","format:check":"prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"","format:write":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","test:coverage":"vitest run --coverage","prepublishOnly":"npm run clean && npm run build && npm run typecheck && npm run test"},"_npmUser":{"name":"akhtar-research","email":"akhtar.research@gmail.com"},"overrides":{"glob":"^13.0.0","esbuild":"^0.28.1","form-data":"^4.0.6"},"repository":{"url":"git+https://github.com/acr-edge/qecopilot.git","type":"git","directory":"qecopilot"},"_npmVersion":"10.9.8","description":"QECopilot (🥝 KIWI) — AI-Native Multi-Agent Execution Platform for Natural Language Software Testing","directories":{},"_nodeVersion":"22.22.3","dependencies":{"ora":"^9.4.0","zod":"^4.4.3","glob":"^13.0.0","pino":"^10.3.1","chalk":"^5.4.1","dotenv":"^17.4.2","openai":"^6.42.0","adm-zip":"^0.5.17","fastify":"^5.3.2","js-yaml":"^4.1.0","commander":"^15.0.0","@fastify/cors":"^11.2.0","@anthropic-ai/sdk":"^0.104.2","@fastify/sensible":"^6.0.3","@google/generative-ai":"^0.24.1","@modelcontextprotocol/sdk":"^1.12.1","@aws-sdk/client-bedrock-runtime":"^3.1065.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.4","jiti":"^2.7.0","tsup":"^8.5.0","eslint":"^10.0.0","rimraf":"^6.0.1","vitest":"^4.1.9","globals":"^17.6.0","prettier":"^3.5.3","@eslint/js":"^10.0.1","@vitest/ui":"^4.1.9","typescript":"^6.0.3","@eslint/css":"^1.3.0","@types/node":"^22.19.21","@eslint/json":"^2.0.0","@types/adm-zip":"^0.5.8","@types/js-yaml":"^4.0.9","typescript-eslint":"^8.61.1","@vitest/coverage-v8":"^4.1.9","eslint-config-prettier":"^10.1.5"},"optionalDependencies":{"pino-pretty":"^13.0.0"},"_npmOperationalInternal":{"tmp":"tmp/qecopilot_1.0.2_1781615538296_0.5488018351815309","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@acr-edge/qecopilot","version":"1.0.3","description":"QECopilot (🥝 KIWI) — AI-Native Multi-Agent Execution Platform for Natural Language Software Testing","keywords":["qe","ai","testing","playwright","mcp","llm","agent","natural-language","test-automation"],"homepage":"https://qecopilot.com","repository":{"type":"git","url":"git+https://github.com/acr-edge/qecopilot.git","directory":"qecopilot"},"license":"Apache 2.0","type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","bin":{"qe":"dist/cli/index.js","qecopilot":"dist/cli/index.js","kiwi":"dist/cli/index.js"},"scripts":{"build":"tsup","build:watch":"tsup --watch","dev":"node --no-deprecation node_modules/.bin/tsx src/cli/index.ts","format:check":"prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"","format:write":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","lint":"eslint .","lint:fix":"eslint . --fix","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","test:ui":"vitest --ui","typecheck":"tsc --noEmit","clean":"rimraf dist coverage","prepublishOnly":"npm run clean && npm run build && npm run typecheck && npm run test"},"dependencies":{"@anthropic-ai/sdk":"^0.104.2","@aws-sdk/client-bedrock-runtime":"^3.1065.0","@fastify/cors":"^11.2.0","@fastify/sensible":"^6.0.3","@google/generative-ai":"^0.24.1","@modelcontextprotocol/sdk":"^1.12.1","adm-zip":"^0.5.17","chalk":"^5.4.1","commander":"^15.0.0","dotenv":"^17.4.2","fastify":"^5.3.2","glob":"^13.0.0","js-yaml":"^4.1.0","openai":"^6.42.0","ora":"^9.4.0","pino":"^10.3.1","zod":"^4.4.3"},"optionalDependencies":{"pino-pretty":"^13.0.0"},"devDependencies":{"@eslint/css":"^1.3.0","@eslint/js":"^10.0.1","@eslint/json":"^2.0.0","@types/adm-zip":"^0.5.8","@types/js-yaml":"^4.0.9","@types/node":"^22.19.21","@vitest/coverage-v8":"^4.1.9","@vitest/ui":"^4.1.9","eslint":"^10.0.0","eslint-config-prettier":"^10.1.5","globals":"^17.6.0","jiti":"^2.7.0","prettier":"^3.5.3","rimraf":"^6.0.1","tsup":"^8.5.0","tsx":"^4.19.4","typescript":"^6.0.3","typescript-eslint":"^8.61.1","vitest":"^4.1.9"},"overrides":{"esbuild":"^0.28.1","form-data":"^4.0.6","glob":"^13.0.0"},"engines":{"node":">=22.0.0"},"publishConfig":{"access":"public"},"_id":"@acr-edge/qecopilot@1.0.3","gitHead":"22b977c60bee94367c5a802992207d0e2225cb05","bugs":{"url":"https://github.com/acr-edge/qecopilot/issues"},"_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-Od+gpb0rulHH1jeCBoF+s/taL01s9ogavGgLwH9jL7gWTkREHLPFnyhPmYejWc5XbVMfCRyvvQ0Mku/fBuZiSQ==","shasum":"6bf90318426132f13b7f4e169fcced5ea396da8e","tarball":"https://registry.npmjs.org/@acr-edge/qecopilot/-/qecopilot-1.0.3.tgz","fileCount":13,"unpackedSize":3981435,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEBbAOsNolBtkWK+pLgVg7vVOfz69eAzElKjxYozujuYAiBoSENQceqmmxJRhcWncqQ3COO3NuysxaCTRansoGYSQg=="}]},"_npmUser":{"name":"akhtar-research","email":"akhtar.research@gmail.com"},"directories":{},"maintainers":[{"name":"akhtarrs","email":"akhtarrs@gmail.com"},{"name":"akhtar-research","email":"akhtar.research@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/qecopilot_1.0.3_1781617687855_0.6866574813620401"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-12T20:53:23.895Z","modified":"2026-06-16T13:48:08.171Z","1.0.0":"2026-06-12T20:53:24.183Z","1.0.1":"2026-06-16T01:57:29.777Z","1.0.2":"2026-06-16T13:12:18.548Z","1.0.3":"2026-06-16T13:48:08.029Z"},"bugs":{"url":"https://github.com/acr-edge/qecopilot/issues"},"license":"Apache 2.0","homepage":"https://qecopilot.com","keywords":["qe","ai","testing","playwright","mcp","llm","agent","natural-language","test-automation"],"repository":{"type":"git","url":"git+https://github.com/acr-edge/qecopilot.git","directory":"qecopilot"},"description":"QECopilot (🥝 KIWI) — AI-Native Multi-Agent Execution Platform for Natural Language Software Testing","maintainers":[{"name":"akhtarrs","email":"akhtarrs@gmail.com"},{"name":"akhtar-research","email":"akhtar.research@gmail.com"}],"readme":"> 🤖 **If you are an AI agent:** Read **`AGENT.md`** first — that is your operating manual.\n\n---\n\n# qecopilot (🥝 KIWI) — AI-Native Test Automation Framework\n\n> **Declarative YAML test cases. Zero automation scripts. Driven entirely by AI.**\n\nqecopilot (nick name KIWI 🥝) is an open-source test automation framework where you write tests in plain-language YAML and run them three ways: via the **qecopilot CLI**, the **interactive TUI**, or directly through any **AI agent** (GitHub Copilot, Claude, Codex).\n\nNo test scripts. No selectors. No boilerplate. Just describe what to test.\n\n---\n\n## How It Works\n\n1. You write test cases in YAML — steps, expected outcomes, test data\n2. qecopilot (or your AI agent) reads the YAML and plans execution\n3. The browser is driven through [Playwright MCP](https://github.com/microsoft/playwright-mcp) tools (`browser_navigate`, `browser_click`, etc.)\n4. Screenshots, HTML/JSON reports, and a self-updating knowledge graph are written automatically\n\n```\nYAML Test Cases  →  qecopilot (Planner → Executor → Validator → Reporter)  →  Reports + Evidence\n```\n\n---\n\n## Three Ways to Run\n\nChoose the mode that fits your workflow — all three run the same YAML test cases.\n\n### 1 · qecopilot CLI — direct command execution\n\n```bash\nqecopilot run suite smoke\nqecopilot run test TC-001\nqecopilot validate\n```\n\nBest for: **CI/CD pipelines**, automated scripts, quick targeted runs.\n\n---\n\n### 2 · qecopilot TUI — interactive terminal\n\n```bash\nqecopilot          # no arguments → launches full-screen TUI\n```\n\nOn launch, the animated logo appears:\n\n```\n         ██████╗  ███████╗\n        ██╔═══██╗ ██╔════╝  copilot - 🥝 KIWI\n        ██║   ██║ █████╗    ──────────────────────────\n        ██║▄▄ ██║ ██╔══╝    AI-Native Test Automation\n        ╚██████╔╝ ███████╗  v1.0.2\n         ╚══▀▀═╝  ╚══════╝\n\n    Project  project-name  ·  Suite  smoke  ·  Env  qa\n    Type help to see commands\n```\n\nFull-screen interface with autocomplete, live run progress, command history, and LLM status bar:\n\n```\n  ┌─────────────────────────────────────────────────────────────────────┐\n  │  Run progress and responses appear here                             │\n  ├─────────────────────────────────────────────────────────────────────┤\n  │  qe ›  run suite _                                                  │\n  │  ↑↓ history  ·  tab complete  ·  PgUp/Dn scroll  ·  ctrl+c exit     │\n  ├─────────────────────────────────────────────────────────────────────┤\n  │  1 suite  ·  3 tests               ✔ gpt-4o [work]                 │\n  └─────────────────────────────────────────────────────────────────────┘\n```\n\nBest for: **local development**, exploratory testing, onboarding new team members.\n\n---\n\n### 3 · AI Agent Mode — natural language\n\nUse any AI agent that has CLI or MCP access:\n\n```\n# GitHub Copilot CLI\nRun the smoke suite\n\n# Claude, Cursor, or any MCP-capable agent\nRun suite smoke and show me the failures\n```\n\nThe agent reads your YAML project, invokes qecopilot (or drives Playwright MCP directly), and streams results back into the conversation.\n\nBest for: **developers who live in their AI agent** and want testing as part of their coding flow.\n\n---\n\n## Prerequisites\n\n### System Requirements\n\n| Requirement | Minimum | Recommended |\n|---|---|---|\n| **Node.js** | 22.0.0 | **22.22.3 LTS** |\n| **npm** | 10.0.0 | 10.9.x *(bundled with Node 22)* |\n| **OS** | Windows 10 x64, macOS 12+, Ubuntu 20.04+ | — |\n\nVerify before installing:\n\n```bash\nnode --version   # ≥ 22.0.0 required\nnpm --version    # ≥ 10.0.0 required\n```\n\n> **Install / upgrade Node.js**\n>\n> **macOS / Linux — via nvm:**\n> ```bash\n> nvm install 22.22.3\n> nvm use 22.22.3\n> node --version   # v22.22.3\n> ```\n>\n> **Windows — via nvm-windows or Winget:**\n> ```powershell\n> winget install OpenJS.NodeJS.LTS\n> # or download from https://nodejs.org/\n> ```\n>\n> **Docker** — see the included `Dockerfile` and `docker-compose.yml`.\n\n---\n\n### 1 · Install qecopilot\n\n```bash\nnpm install -g @acr-edge/qecopilot\n```\n\nBoth `qecopilot`, `qe`, and `kiwi` 🥝 are available after install:\n\n```bash\nqecopilot --version\nqe --version        # shorthand\nkiwi --version      # same thing\n```\n\n### 2 · Configure an LLM\n\nqecopilot requires an LLM to plan and validate test cases. The recommended approach is a named global profile — set once, used across all projects.\n\n```bash\n# Add a profile (stored in ~/.qecopilot/config.json)\nqe config profile add work \\\n  --provider openai \\\n  --model gpt-4o \\\n  --api-key sk-...\n\n# Set it as active\nqe config profile use work\n\n# Verify it is reachable\nqe llm status\n```\n\nSupported providers:\n\n| Provider | Flag | Required env var |\n|---|---|---|\n| OpenAI | `--provider openai` | `OPENAI_API_KEY` |\n| Anthropic | `--provider anthropic` | `ANTHROPIC_API_KEY` |\n| Google Gemini | `--provider gemini` | `GEMINI_API_KEY` |\n| Ollama (local) | `--provider ollama` | *(none)* |\n| AWS Bedrock | `--provider bedrock` | `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` |\n| OpenAI-compatible | `--provider openai-compatible` | `--base-url <url>` |\n\n> **CI / CD** — use the `QE_LLM_PROFILE` env var to pass credentials inline without writing a file:\n> ```bash\n> export QE_LLM_PROFILE='{\"provider\":\"openai\",\"model\":\"gpt-4o\",\"api_key\":\"sk-...\"}'\n> ```\n\n### 3 · Configure Playwright MCP (for AI Agent Mode only)\n\n> **Skip this if you only use CLI or TUI mode** — qecopilot launches Playwright MCP automatically.\n\n#### GitHub Copilot CLI\n\nCreate `~/.copilot/mcp-config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"playwright\": {\n      \"type\": \"local\",\n      \"command\": \"npx\",\n      \"args\": [\"@playwright/mcp@latest\", \"--browser\", \"msedge\"],\n      \"env\": {},\n      \"tools\": [\"*\"]\n    }\n  }\n}\n```\n\n> **Windows:** Use `msedge` (pre-installed). **macOS/Linux:** Use `\"chrome\"` instead.\n\nOr add interactively:\n```\n/mcp add\n# Server Name: playwright\n# Server Type: Local (STDIO)\n# Command: npx @playwright/mcp@latest --browser msedge\n```\n\nVerify:\n```\n/mcp show playwright\n```\n\n#### Claude (Claude Code / Claude Desktop)\n\nAdd to `.claude/settings.local.json` in your project root:\n```json\n{\n  \"mcpServers\": {\n    \"playwright\": {\n      \"command\": \"npx\",\n      \"args\": [\"@playwright/mcp@latest\", \"--browser\", \"msedge\"]\n    }\n  }\n}\n```\n\n#### GitHub Copilot Cloud Agent\n\nNo setup needed — Playwright MCP is built in.\n\n#### OpenAI Codex\n\nConfigure per your Codex deployment environment.\n\n---\n\n## Quick Start\n\n### Option A — Blank project (bring your own app)\n\n```bash\n# 1. Scaffold a new project from the golden template\nqe init my-app-tests\ncd my-app-tests\n\n# 2. Set up your environment\ncp .env.example .env\n# Edit .env: set BASE_URL and credentials for your app\n\n# 3. Fill in application knowledge (optional but recommended)\n# Edit knowledge/modules.json   — UI elements, button labels, field types\n# Edit knowledge/entities.json  — data models, ID formats\n# Edit knowledge/workflows.json — business workflows\n\n# 4. Write your first test case\n# Copy templates/testcase.yml → testcases/<feature>/TC-001.yml\n\n# 5. Run it\nqe run suite smoke\n# or launch TUI:\nqe\n```\n\n### Option B — Scaffold from a starter example\n\nStarters give you a complete, runnable test suite for a real application. Great for exploring the framework before wiring it to your own app.\n\n```bash\n# List all available starters\nqe starter list\n\n# Get details about a starter\nqe starter info saucedemo\n\n# Scaffold with the saucedemo starter (SauceLabs demo e-commerce app)\nqe init my-saucedemo-tests --starter saucedemo\ncd my-saucedemo-tests\n\nqe run suite smoke\n```\n\n#### Available starters\n\n| Name | App | What's included |\n|---|---|---|\n| `saucedemo` | [saucedemo.com](https://www.saucedemo.com) — SauceLabs demo e-commerce | Login, cart, checkout flows |\n| `fieldforce360` | FieldForce360 field service app | Work orders, dispatch, appointments |\n\n> **Adding your own starter** — set `QE_STARTERS_REPO=owner/repo` to point at your own starter repository.\n\n---\n\n## CLI Reference\n\n### Project scaffolding\n\n| Command | Description |\n|---|---|\n| `qe init <project>` | Scaffold a new blank project from the golden template |\n| `qe init <project> --starter <name>` | Scaffold and overlay a starter example |\n| `qe init <project> --local <path>` | Scaffold from a local directory |\n| `qe starter list` | List all available starter examples |\n| `qe starter info <name>` | Show details about a specific starter |\n\n### Running tests\n\n### Running tests\n\n| Command | Description |\n| `qecopilot run test <id>` | Run a single test case by ID |\n| `qecopilot compile` | Pre-compile all test plans (AOT) — faster, deterministic runs |\n| `qecopilot compile --suite <name>` | Pre-compile a specific suite only |\n| `qecopilot compile --force` | Force recompile even if plans are up to date |\n| `qecopilot runs [--limit <n>]` | List recent runs |\n| `qecopilot validate` | Validate all YAML assets in the project |\n| `qecopilot report latest` | Show path to the latest run report |\n| `qecopilot report show <run-id>` | Show path to a specific run's report |\n| `qecopilot llm status` | Check LLM provider health |\n| `qecopilot mcp status` | Check browser adapter status |\n\n### Global LLM Profile Commands\n\n| Command | Description |\n|---|---|\n| `qecopilot config profile add <name>` | Add or replace a named LLM profile |\n| `qecopilot config profile list` | List all profiles |\n| `qecopilot config profile use <name>` | Set the active profile |\n| `qecopilot config profile remove <name>` | Remove a profile |\n\nProfiles are stored in `~/.qecopilot/config.json` and shared across all projects.\n\n### TUI Commands (inside `qecopilot` interactive session)\n\n| Command | Description |\n|---|---|\n| `run suite <name>` | Run a suite with live progress |\n| `run test <id>` | Run a single test case |\n| `list suites` | Show all suites |\n| `list tests [<suite>]` | Show test cases |\n| `validate` | Validate YAML assets |\n| `config` | Show current LLM and project config |\n| `help` | Show all available commands |\n| `exit` / Ctrl+C | Exit |\n\n### Exit Codes\n\n| Code | Meaning |\n|---|---|\n| 0 | All tests passed |\n| 1 | One or more tests failed |\n| 2 | Config / YAML validation error |\n| 3 | LLM provider unreachable |\n| 4 | Application under test unreachable |\n\n---\n\n## Running with AI Agents (Copilot CLI)\n\nEvery new Copilot CLI session requires two setup commands:\n\n```\n/allow-all\n```\nGrants all tool, file, and URL permissions — without this, Copilot prompts for approval on every browser action.\n\n```\n/mcp show playwright\n```\nVerifies the Playwright MCP server is active. You should see `browser_navigate`, `browser_click` etc.\n\n**Recommended flow every session:**\n```\ncd /path/to/my-app-tests\ngh copilot\n\n/allow-all\n/mcp show playwright\n\nRun the smoke suite\n```\n\n> `/allow-all` resets on exit — run it at the start of every new session.\n\n---\n\n## Framework Structure\n\n```\nqecopilot/\n├── AGENT.md                   ← AI agent operating manual (read this first)\n├── README.md\n├── .env                       ← Runtime secrets (gitignored)\n├── .env.example               ← Template — copy to .env\n│\n├── configs/\n│   ├── ai-test-config.yml     ← Global settings (browser, suite, environment, artifacts)\n│   ├── qa.yml                 ← QA environment (base_url, api_url, flags)\n│   ├── uat.yml                ← UAT environment\n│   └── prod.yml               ← Production environment\n│\n├── testcases/                 ← Test case definitions (YAML)\n│   └── <feature>/TC-NNN.yml\n│\n├── actions/                   ← Reusable action libraries (YAML)\n│   ├── action-catalog.yml     ← Master index of all actions\n│   └── common/\n│       ├── auth.yml           ← Login / logout\n│       └── navigation.yml     ← Navigation actions\n│\n├── testdata/\n│   ├── users.yml              ← User personas and credentials\n│   ├── entities.yml           ← Domain entities\n│   └── environments.yml       ← Environment URLs and flags\n│\n├── knowledge/                 ← Application knowledge graph (auto-updated each run)\n│   ├── modules.json           ← UI elements, button labels, field types per module\n│   ├── entities.json          ← Data models, ID formats, field constraints\n│   ├── workflows.json         ← Business workflows and status transitions\n│   ├── api_catalog.json       ← REST API endpoints\n│   └── learning-log.json      ← Cross-run learning history\n│\n├── suites/\n│   └── smoke.yml              ← Test suite definitions\n│\n├── templates/                 ← Blank templates for creating new assets\n│   ├── testcase.yml\n│   ├── action.yml\n│   └── defect.md\n│\n├── pipelines/\n│   └── execution-pipeline.yml\n│\n├── runs/                      ← Auto-generated run evidence (gitignored)\n└── reports/                   ← Quick-access reports (gitignored)\n    ├── latest/\n    └── history/\n```\n\n---\n\n## Configuration Reference\n\nqecopilot reads `configs/ai-test-config.yml` from the project root. The LLM section is not in this file — it comes from your global profile or environment variables (see Prerequisites above).\n\n```yaml\nframework:\n  name: \"My Application Test Suite\"   # your project name\n  version: \"1.0\"\n  spec: \"AGENT.md\"\n\nexecution:\n  mode: mcp                        # mcp only (v1)\n  browser: msedge                  # msedge | chrome | firefox | webkit\n  headless: false                  # true for CI, false for local\n  maximize: true\n  timeout_seconds: 30\n  page_load_timeout_seconds: 15\n  retry_failed: 1                  # retry a failed step once before marking FAIL\n  slow_mo_ms: 0                    # ms pause between actions (0 = no delay)\n\nenvironment:\n  target: qa                       # matches configs/<target>.yml\n  config: configs/qa.yml\n\nsuite:\n  name: smoke                      # matches suites/<name>.yml\n  file: suites/smoke.yml\n\nartifacts:\n  base_path: runs/\n  screenshots: true\n  videos: false\n  traces: false\n  screenshot_on_action_boundary: true\n  screenshot_on_failure: true\n\nmcp:\n  snapshot_before_action: true\n  snapshot_after_action: false\n  tool_timeout_seconds: 10\n\nreporting:\n  formats: [json, html]\n  output_path: reports/\n  copy_to_latest: true\n  history_retention_runs: 50\n```\n\n### Environment file (`configs/qa.yml`)\n\n```yaml\nenvironment:\n  name: qa\n  base_url: \"${env.QA_BASE_URL}\"\n  api_url: \"${env.QA_API_URL}\"\n```\n\n> **Single-environment project model:** one qecopilot project maps to one target environment. If you need to run the same automation against UAT, staging, or another environment, scaffold a **separate project folder** for that environment instead of switching envs at runtime. This keeps compiled plans, healing history, reports, and knowledge clean and easy to maintain.\n\n---\n\n## Writing Test Cases\n\nCopy `templates/testcase.yml` to `testcases/<feature>/TC-NNN.yml`:\n\n```yaml\ntest_case:\n  id: TC-001\n  title: \"Create a new record\"\n  feature: \"Records\"\n  priority: high\n  persona: admin\n\n  test_data:\n    user: users.admin1\n\n  steps:\n    - Login as Admin\n    - Navigate to Records\n    - Create Record\n    - Save\n\n  step_params:\n    Create Record:\n      name: \"${testdata.entities.record1.name}\"\n\n  expected:\n    - \"Record is created successfully\"\n    - \"Record appears in the list\"\n```\n\n---\n\n## Writing Actions\n\nCopy `templates/action.yml` to `actions/<category>/<name>.yml`:\n\n```yaml\nactions:\n  - action_id: create_record\n    name: \"Create Record\"\n    description: \"Opens the new record form and fills required fields\"\n    parameters:\n      - name: name\n        required: true\n    steps:\n      - description: \"Click the New button\"\n        tool: browser_click\n        params:\n          element: \"New Record button\"\n      - description: \"Type record name\"\n        tool: browser_type\n        params:\n          element: \"Name input\"\n          text: \"${params.name}\"\n      - description: \"Screenshot of filled form\"\n        tool: browser_take_screenshot\n```\n\nRegister it in `actions/action-catalog.yml`:\n\n```yaml\nactions:\n  - id: create_record\n    file: actions/records/create-record.yml\n```\n\n---\n\n## Test Results\n\n**Quick access — `reports/latest/`** (and `reports/history/<run-id>/`):\n\n| File | Contents |\n|---|---|\n| `report.html` | Human-readable pass/fail summary with screenshots |\n| `report.json` | Machine-readable run summary |\n\n**Full evidence — `runs/<run-id>/`**:\n\n| Path | Contents |\n|---|---|\n| `artifacts/screenshots/` | Step screenshots named `<TC-ID>-<tool>-<step>.png` |\n| `context/` | Resolved environment, test data, and execution plan used for the run |\n| `defects/BUG-NNN.md` | Auto-generated defect report per failure |\n| `ai-reasoning/` | Agent decision logs (planner, executor, validator, reporter) |\n| `execution.log` | One-line-per-step audit log of every MCP tool call |\n| `knowledge-updates.json` | UI element discoveries made during this run |\n\n---\n\n## Supported AI Agents\n\n| Agent | Playwright MCP | Notes |\n|---|---|---|\n| qecopilot CLI / TUI | ✅ Auto-launched | No MCP setup needed — qecopilot manages it |\n| GitHub Copilot CLI | ✅ Manual config | See Prerequisites above |\n| GitHub Copilot Cloud Agent | ✅ Built-in | No setup needed |\n| Claude Code / Claude Desktop | ✅ Via settings.local.json | See Prerequisites above |\n| OpenAI Codex | ✅ Via deployment config | Configure per environment |\n\n---\n\n## License\n\nApache License 2.0 — see [LICENSE](LICENSE) for details.","readmeFilename":"README.md"}