@capagents/forgeqe 0.0.0-stage → 1.0.0

package/forgeqe.example.yaml

@@ -0,0 +1,203 @@
+llm:
+  models_file: ./llms.json
+  # active: azure-gpt4o   # profile to use; default: "default" in llms.json (Tab switches in the shell)
+
+browser:
+  headless: true
+  max_steps: 40 # a checkpoint: a run still making progress carries on, up to 3x
+  timeout_seconds: 600 # whole run
+  vision_detail: low # low | high
+  viewport:
+    width: 1280
+    height: 800
+  allowed_hosts: []
+  judge: false # true: a second model call checks each finished run against the goal and can fail it
+  overlay: true # visible browser: ForgeQE start page, edge glow, a bar with the current step, your mouse and keyboard locked while the agent works
+  # start_url: https://staging.example.com   # optional; omit to let the agent choose the site
+
+# Every agent prompt is a file in .forgeqe/prompts/ (forgeqe init copies them; edit one to change it, forgeqe prompts
+# lists them). These two short ones are added to the browser agent's prompt too.
+prompts:
+  step_instruction: ""
+  guiderails: ""
+  # dir: ../shared-prompts      # a folder of prompts that wins over .forgeqe/prompts (shared between projects)
+
+# Product knowledge (.forgeqe/knowledge): what the agents should know about the product.
+# knowledge:
+#   dir: .forgeqe/knowledge
+#   browser_max_chars: 1500     # most knowledge added to each browser run (only sections that match the goal); 0: none
+
+# The product's industry and the regulations in scope. Agents then design and judge tests as an expert in that
+# industry would, and add each regulation's obligations a feature touches. Your applicable controls, with their ids,
+# go in .forgeqe/knowledge/compliance.md; agents cite only ids listed there.
+# Teams and email notifications for the team: each channel picks its events (suite_failed, suite_passed, release,
+# eval_failed). The Teams webhook URL is a secret: keep it in the environment, never here. See HOW_TO_USE.md section 17.
+# notify:
+#   report_url: https://reports.example.com/forgeqe   # where .forgeqe/reports is published; cards link each report
+#   channels:
+#     qa:
+#       teams: { webhook_env: TEAMS_WEBHOOK_URL }      # a Teams Workflows "post to a channel when a webhook request is received"
+#       on: [suite_failed, eval_failed]
+#     release:
+#       teams: { webhook_env: TEAMS_RELEASE_WEBHOOK }
+#       on: [release]
+
+# domain:
+#   industry: retail banking
+#   regulations: [DORA, PSD2, GDPR, ISO 27001]
+#   notes: Payments to UK and EU accounts; customers are consumers and small businesses.
+
+export:
+  out_dir: ./.forgeqe/reports # one folder per run, named by its run id: report, steps, screenshots, trace
+  format: playwright
+
+memory:
+  enabled: true
+  dir: ./.forgeqe/memory # pages, elements, locators, and recorded flows
+  replay: verify # verify | trust | off
+
+code:
+  # repo: ../my-app          # where passed runs become tests (default: the current folder; --no-code turns it off)
+  # test_command: npx playwright test   # the repo's test command, for forgeqe heal; default: the agent finds it
+  max_attempts: 3            # test runs before giving up (also healing attempts); each attempt after the first starts a fresh session from a summary
+  # max_tokens: 1500000      # stop a coding job past this many tokens (cached included) and report how far it got
+  # review_profile: azure-mini  # llms.json profile for the reviewer, which only reads and judges: a cheaper model is enough
+  test_timeout_seconds: 600  # per test run
+  stall_after: 5             # stop the coding agent when one command it runs has failed this many times
+  replay: true               # before the coding agent starts, run the steps as a Playwright script and hand over what worked and where it failed
+  live_browser: true         # once a step fails, the coding agent looks at that page in a Playwright browser instead of building tests to look
+  # model: anthropic/claude-sonnet-4-5   # model for ForgeQE's agent and Scribe; default: the active llms.json profile
+  # runtime: /path/to/agent-runtime      # default: the runtime ForgeQE downloads
+
+# Skills: folders with a SKILL.md that teach the agents your repo's test conventions, a framework, or an app.
+# ForgeQE ships some; yours go in .forgeqe/skills next to this file (commit them) or ~/.forgeqe/skills.
+# A skill replaces a built-in one with the same name. forgeqe skills lists them; forgeqe skills new <name> starts one.
+# skills:
+#   enabled: true
+#   dirs: [../shared-skills]   # more folders, read last (they win over the others)
+#   disable: [dynamics-365]    # skills to leave out; forgeqe skills enable|disable <name> edits this
+#   external: false            # true: also ~/.claude/skills, ~/.agents/skills, and the repo's .claude/.agents skills
+#   browser_max_chars: 6000    # most skill text added to one browser run's prompt
+
+# Sites the browser agent signs in to. Values stay in the environment; the model only sees placeholders.
+# Sessions (cookies + local storage) are kept in .forgeqe/sessions/<name>.json so the next run starts signed in;
+# keep that folder out of git. forgeqe login <name> saves a session you sign in to by hand (SSO, captcha).
+# logins:
+#   shop:
+#     url: https://staging.shop.example/login   # or domains: [https://staging.shop.example, https://*.shop.example]
+#     username_env: SHOP_USER
+#     password_env: SHOP_PASSWORD
+#     totp_env: SHOP_TOTP_SECRET                # optional: authenticator secret (base32) for 2FA codes
+#     # save_session: false                     # sign in every run instead
+
+report:
+  screenshots: all            # all | failures | off: step screenshots in report.html
+  accessibility: true         # check each page the agent visits (names, labels, image text, contrast, lang, zoom)
+
+# Test case systems, for ForgeQE's agent and forgeqe suite / cases. Keys stay in the environment.
+# ForgeQE's agent also gets each system's MCP server, set up from these same settings (forgeqe mcp list).
+sources:
+  write_back: true            # post results back to the system each case came from
+  # azure_devops:
+  #   org_url: https://dev.azure.com/acme   # or ADO_ORG_URL. The MCP server is this organization, every project.
+  #   # project: Shop                       # optional: limit ForgeQE's own test, sprint, and bug calls to one project. Or ADO_PROJECT. * or all means every project.
+  #   token_env: ADO_PAT                    # PAT with Test Management + Work Items (read & write)
+  #   mcp: true                             # Microsoft's Azure DevOps MCP server (needs npx); false: API only
+  #   # mcp_domains: [core, work, work-items, test-plans, pipelines, repositories, wiki, search, advanced-security]   # default: all
+  # jira:
+  #   url: https://acme.atlassian.net       # or JIRA_URL; Server/Data Center URLs work too
+  #   email_env: JIRA_EMAIL                 # Cloud only
+  #   token_env: JIRA_API_TOKEN             # Cloud API token, or a Server/DC personal access token
+  #   mcp: mcp-atlassian                    # mcp-atlassian (uvx; Cloud and Server/DC) | rovo (Atlassian's hosted server, Cloud) | false
+  # xray:                                   # no MCP server: ForgeQE's API tools cover Xray
+  #   url: https://xray.cloud.getxray.app   # Xray Cloud; Server/DC uses the jira: settings above
+  #   client_id_env: XRAY_CLIENT_ID
+  #   client_secret_env: XRAY_CLIENT_SECRET
+  # confluence: true                        # requirements pages on the Jira Cloud site above, same account
+  # confluence:                             # or a separate site
+  #   url: https://confluence.acme.com      # or CONFLUENCE_URL; Cloud: https://acme.atlassian.net/wiki
+  #   email_env: CONFLUENCE_EMAIL           # Cloud only
+  #   token_env: CONFLUENCE_TOKEN           # Cloud API token, or a Server/DC personal access token
+  #   space: QA                             # optional: search this space only
+  # testrail:
+  #   url: https://acme.testrail.io         # or TESTRAIL_URL
+  #   email_env: TESTRAIL_EMAIL
+  #   token_env: TESTRAIL_API_KEY
+  #   project_id: 1                         # for testrail:suite=<id>
+  # zephyr:                                 # Zephyr Scale Cloud; on when ZEPHYR_API_TOKEN is set
+  #   token_env: ZEPHYR_API_TOKEN
+  #   project_key: SHOP                     # for zephyr:folder=<id>
+  # qtest:
+  #   url: https://acme.qtestnet.com        # or QTEST_URL
+  #   token_env: QTEST_TOKEN                # API bearer token
+  #   project_id: 12345
+  #   statuses: { passed: PASS, failed: FAIL, error: BLOCKED }   # automation status names in your qTest
+  # bugs:                                   # a bug per failed case; still failing: a comment on the open bug
+  #   system: jira                          # jira | azure_devops
+  #   project: SHOP                         # Jira project key (Azure DevOps uses azure_devops.project)
+  #   type: Bug                             # issue / work item type
+  #   labels: [forgeqe]                    # Jira labels or Azure DevOps tags
+  #   # area_path: Shop\\Web                # Azure DevOps
+  #   # on_error: false                     # also for cases that could not run
+
+# More MCP servers for ForgeQE's agent. Use {env:NAME} for secrets; never put values here.
+# mcp:
+#   github:
+#     url: https://api.githubcopilot.com/mcp/
+#     headers: { Authorization: "Bearer {env:GITHUB_TOKEN}" }
+#   xray:
+#     command: npx -y @triparc/xray-mcp
+#     env: { XRAY_CLIENT_ID: "{env:XRAY_CLIENT_ID}", XRAY_CLIENT_SECRET: "{env:XRAY_CLIENT_SECRET}" }
+
+suite:
+  parallel: 1                 # browsers at once; coding jobs always run one at a time
+  code: true                  # with a repo set, passed cases get a test from Scribe
+  # out_dir: ./.forgeqe/reports/suites
+
+# Accessibility (axe-core, WCAG) and performance (Core Web Vitals) of every page a run visits. Without budgets they
+# are reported and tracked over time; a run fails on them only when a budget below is exceeded.
+# quality:
+#   accessibility:
+#     standard: wcag21aa          # wcag2a, wcag21aa, wcag22aa, wcag21aaa, section508, en301549, best-practice
+#   visual:                       # each page compared with its approved screenshot (.forgeqe/visual-baselines)
+#     mask: [".clock", "#ad-slot"]  # hidden before capture
+#     full_page: false
+#   budgets:
+#     accessibility: { critical: 0, serious: 0, ignore: [region] }
+#     performance: web-vitals     # or { lcp_ms: 3000, cls: 0.1, inp_ms: 200, pages: { /search: { lcp_ms: 4000 } } }
+#     visual: 0.5                 # most a page may change, in percent of its pixels
+
+# API and contract tests (REST, GraphQL, SOAP, gRPC). Every browser run records the app's API calls (secrets
+# redacted) in network.json; forgeqe api contracts / run / tests turn them, or an OpenAPI, WSDL, GraphQL, or .proto
+# description, into contracts and tests. Header values are ${NAME} references to environment variables.
+# api:
+#   capture: true                 # record the app's API calls in browser runs
+#   base_url: https://staging.shop.example
+#   headers:
+#     Authorization: Bearer ${API_TOKEN}
+#   third_party: false            # keep calls to other sites than the page's
+#   timeout_seconds: 30
+
+# forgeqe monitor: run checks on a schedule and alert when one starts failing, keeps failing, or recovers.
+# Secrets stay in the environment; only their names go here.
+# monitor:
+#   checks: [checks/smoke.yaml]   # any case sources: files, folders, jira:..., ado:..., testrail:...
+#   every: 15m                    # 30s, 15m, 1h, 1h30m; at least 10s
+#   replay: verify                # verify: one model call per check confirms the result; trust: none
+#   parallel: 1
+#   fail_after: 1                 # failing rounds in a row before the first alert (2+ rides out flaky runs)
+#   remind_every: 2h              # repeat the alert while it keeps failing; default: never
+#   keep: 100                     # round folders kept; older ones are deleted
+#   write_back: false             # post each round's results to the source system
+#   # out_dir: ./.forgeqe/reports/monitor   # rounds and state.json (which checks are failing, and since when)
+#   # report_url: https://reports.example.com/monitor   # where out_dir is published; alerts link <url>/<round>/report.html
+#   alerts:
+#     teams:                      # a Teams incoming webhook or Workflows "post to a channel when a webhook request is received"
+#       webhook_env: TEAMS_WEBHOOK_URL
+#     email:
+#       host: smtp.office365.com  # or SMTP_HOST
+#       port: 587                 # STARTTLS; 465 is TLS from the start
+#       username_env: SMTP_USERNAME
+#       password_env: SMTP_PASSWORD
+#       # from: ForgeQE <qa-bot@example.com>   # default: the username
+#       to: [qa-team@example.com]

package/knowledge/README.md

@@ -0,0 +1,18 @@
+# Product knowledge
+
+What ForgeQE's agents should know about your product, written once and used on every run: what it does, who uses it,
+the words your team uses, the rules it follows, the data to test with, and where it runs. Fill in the files below (or add
+your own `.md` or `.txt` files, in folders if you like) and commit them.
+
+How the agents use it:
+
+- **ForgeQE's agent** sees the list of these files and reads the ones a request needs (planning tests, judging a test
+  case, answering about the product).
+- **Planning agents** (exploratory charters, API scenarios) get the sections that match the story or scenario.
+- **The browser agent** gets the few sections that match the goal (at most `knowledge.browser_max_chars`, default 1500
+  characters, so runs stay cheap).
+
+Sections are found by their headings, so give each topic its own `##` heading. A file you have not changed since
+`forgeqe init` copied it is left out: the templates' examples never reach an agent.
+
+Never put passwords, tokens, or personal data here: use logins and environment variables for those.

package/knowledge/business-rules.md

@@ -0,0 +1,10 @@
+# Business rules
+
+<!-- The rules the product enforces: limits, validations, calculations. Agents use them as expected results. -->
+
+## Checkout
+- Delivery is free from 50.00; below that it costs 4.95.
+- A coupon cannot be combined with a gift card.
+
+## Addresses
+- Postcode is required and must be a valid UK postcode.

package/knowledge/compliance.md

@@ -0,0 +1,16 @@
+# Compliance
+
+<!-- The obligations your organisation has decided apply to this product, with the ids your auditors use.
+     The regulations themselves are named in domain.regulations in forgeqe.yaml; this file says which of their
+     requirements apply here and how you identify them. Agents cite an id only when it is listed here, so tests and
+     findings trace to your own control register instead of article numbers recalled from memory. -->
+
+## Controls in scope
+<!-- One line each: the id, the regulation or standard, and what the product must do, in words a tester can check. -->
+- Example: CTL-AUD-01 (ISO 27001, DORA): every change to a payment beneficiary is written to the audit log with who, when, and the old and new values.
+- Example: CTL-ACC-04 (ISO 27001): a user cannot approve a payment they created (segregation of duties).
+- Example: CTL-PRV-02 (GDPR): a customer's erasure request removes their personal data from the profile and exports within 30 days.
+
+## Not in scope
+<!-- Requirements the team has decided do not apply to this product, and why, so agents do not test for them. -->
+- Example: PCI DSS card storage: the product never stores card numbers; payments go through the provider's hosted page.

package/knowledge/environments.md

@@ -0,0 +1,5 @@
+# Environments
+
+<!-- Where the product runs and what differs between environments. -->
+- QA: https://qa.shop.example (reset every night; data in test-data.md exists here)
+- Staging: https://staging.shop.example (production-like; do not create orders)

package/knowledge/glossary.md

@@ -0,0 +1,5 @@
+# Glossary
+
+<!-- The words your team and your test cases use, and what they mean in the product. -->
+- **Basket**: the cart; the page is /cart.
+- **Order reference**: the ORD-123456 number shown after checkout and on /account/orders.

package/knowledge/product.md

@@ -0,0 +1,16 @@
+# The product
+
+## What it is
+<!-- One paragraph: what the application does and for whom. -->
+Example: Shop is the online store of Acme. Customers browse products, pay by card or gift card, and track their orders.
+
+## Main areas
+<!-- The parts of the application, with where they start. -->
+- Catalogue: /products, search and filters
+- Basket and checkout: /cart, /checkout
+- My account: /account (orders, addresses, payment methods)
+
+## Main flows
+<!-- The journeys that matter most, in a line each. -->
+- Search, add to basket, check out as a signed-in customer
+- Return an item from an order

package/knowledge/roles.md

@@ -0,0 +1,9 @@
+# Roles
+
+<!-- Who uses the product and what each may and may not do. Name the saved login (logins: in forgeqe.yaml) for each. -->
+
+## Customer
+Login: shop_customer. Can buy, see their own orders, and change their addresses. Cannot see other customers' orders.
+
+## Store admin
+Login: shop_admin. Can edit products and prices, refund orders, and see every order.

package/knowledge/test-data.md

@@ -0,0 +1,7 @@
+# Test data
+
+<!-- Data that exists in the test environments and is safe to use: products, customers, coupons, cards. No secrets. -->
+- Product with stock: "Blue Teapot" (SKU TP-001)
+- Product out of stock: "Red Kettle" (SKU KT-404)
+- Coupon: SAVE10 (10% off, valid until the end of the year)
+- Test card: 4111 1111 1111 1111, any future date, CVC 123

package/llms.example.json

@@ -0,0 +1,51 @@
+{
+  "default": "openai-gpt4o",
+  "models": {
+    "azure-gpt4o": {
+      "provider": "azure",
+      "model": "gpt-4o",
+      "deployment": "gpt-4o",
+      "endpoint": "https://YOUR_RESOURCE.openai.azure.com/",
+      "api_key_env": "WP_AZURE_API_KEY",
+      "api_version": "2024-05-01-preview",
+      "temperature": 0.2,
+      "deployment_type": "global",
+      "description": "Azure OpenAI GPT-4o (vision)"
+    },
+    "azure-gpt4o-entra": {
+      "provider": "azure",
+      "model": "gpt-4o",
+      "deployment": "gpt-4o",
+      "endpoint": "https://YOUR_RESOURCE.openai.azure.com/",
+      "auth": "entra",
+      "managed_identity_client_id": "",
+      "api_version": "2024-05-01-preview",
+      "temperature": 0.2,
+      "deployment_type": "global",
+      "description": "Azure OpenAI GPT-4o with Microsoft Entra ID (managed identity, workload identity or az login); no key"
+    },
+    "openai-gpt4o": {
+      "provider": "openai",
+      "model": "gpt-4o",
+      "api_key_env": "OPENAI_API_KEY",
+      "temperature": 0.2,
+      "description": "OpenAI GPT-4o (vision)"
+    },
+    "ollama-llama": {
+      "provider": "ollama",
+      "model": "llama3.2",
+      "endpoint": "http://127.0.0.1:11434/v1",
+      "api_key_env": "WP_API_KEY",
+      "temperature": 0.2,
+      "description": "Local Ollama"
+    },
+    "compatible": {
+      "provider": "openai_compatible",
+      "model": "gpt-4o",
+      "endpoint": "https://your-gateway.example/v1",
+      "api_key_env": "WP_API_KEY",
+      "temperature": 0.2,
+      "description": "Any OpenAI-compatible chat endpoint"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@capagents/forgeqe",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "ForgeQE: a browser agent CLI that runs goals and test cases in Chrome and turns passing runs into tests in your repo",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "forgeqe": "bin/forgeqe.js",
+    "webpilot": "bin/forgeqe.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "py/forgeqe_engine/*.py",
+    "skills/",
+    "prompts/",
+    "knowledge/",
+    "evals/",
+    "docs/",
+    "README.md",
+    "HOW_TO_USE.md",
+    "forgeqe-architecture.html",
+    "forgeqe.example.yaml",
+    "llms.example.json"
+  ],
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "forgeqe": "bun src/index.ts",
+    "start": "bun src/index.ts start",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "build:report": "cd report-ui && npm install --no-audit --no-fund && npm run build && cp dist/index.html ../src/report/template.html"
+  },
+  "keywords": [
+    "forgeqe",
+    "browser",
+    "agent",
+    "cli",
+    "opentui",
+    "testing",
+    "test-automation"
+  ],
+  "dependencies": {
+    "@opencode-ai/sdk": "1.18.33",
+    "@opentui/core": "^0.5.12",
+    "@opentui/react": "^0.5.12",
+    "axe-core": "4.14.0",
+    "fast-xml-parser": "^5.11.1",
+    "nodemailer": "^10.0.12",
+    "pixelmatch": "8.0.0",
+    "pngjs": "7.0.0",
+    "react": "^19.3.0",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.2",
+    "@types/nodemailer": "^8.0.2",
+    "@types/pngjs": "^6.0.5",
+    "@types/react": "^19.3.0",
+    "typescript": "^7.0.2"
+  }
+}

package/prompts/README.md

@@ -0,0 +1,34 @@
+# Prompts
+
+Every instruction ForgeQE's agents work from, one file each. Edit a file here to change how that agent works in this
+project; leave it as it is to keep getting ForgeQE's improvements when you update.
+
+| File | Who uses it |
+|------|-------------|
+| brain.md | ForgeQE's own agent: reads every request in the shell, `forgeqe run`, and `forgeqe mcp`, and picks the tools |
+| test-agent.md | Scribe, the coding agent: turns a verified browser run into a test in your repository |
+| test-rules.md | Rules for any test the agents write or change (included in test-agent, test-reviewer, heal) |
+| test-reviewer.md | The reviewer that checks a passing test tests the right thing the right way |
+| heal.md | Heals tests the application has outgrown, and tells them apart from real bugs |
+| find-tests.md | Finds the automated tests that match a request |
+| pr-review.md | Reviews pull requests |
+| api-tests.md | Writes API and contract tests, and end-to-end API scenarios |
+| api-scenarios.md | Plans API scenarios from test cases or plain English |
+| explore-charters.md | Plans exploratory charters for a story |
+| eval-judge.md | Scores the agent's test cases in `forgeqe eval domain` |
+| skill-rule.md | How agents use skills (included in most prompts) |
+| domain-rule.md | How agents apply the product's industry risks and regulations, declared or worked out (included in every agent that analyses requirements or designs, writes, reviews, or heals tests) |
+| browser-*.md | The browser agent: error recovery, when a goal counts as done, recording checks, clicking so runs become tests, step verdicts for test cases, picking skills |
+| browser-extra.md | Your own instructions for the browser agent, added to every run (empty to start with) |
+
+How it works:
+
+- Each file has a short header (name, description, used_by) between `---` lines, then the prompt.
+- `{{> name}}` includes another prompt, for example `{{> test-rules}}`.
+- ForgeQE looks for a prompt in `prompts.dir` (forgeqe.yaml), then this folder (`.forgeqe/prompts/`), then
+  `~/.forgeqe/prompts/`, then its own. A copy here that nobody changed since `forgeqe init` counts as ForgeQE's own,
+  so it follows updates; once you edit it, yours is used. `.forgeqe-manifest.json` records which is which: keep it.
+- `forgeqe prompts` lists every prompt and where it comes from; `forgeqe prompts diff <name>` shows how yours differs
+  from ForgeQE's (and warns when ForgeQE's changed after you edited yours); `forgeqe prompts reset <name>` goes back
+  to ForgeQE's (yours is kept as `<name>.md.bak`).
+- Changes to these prompts change how the agents behave: test a change on a few runs before you commit it.

package/prompts/api-scenarios.md

@@ -0,0 +1,21 @@
+---
+name: api-scenarios
+description: "Plans end-to-end API scenarios from test cases or plain English, against an API's operations."
+used_by: "api_scenarios from cases or text"
+---
+You plan end-to-end API test scenarios. You get a list of an API's operations (each with its method, path, an example call, its answer's key fields, whether it needs auth, and whether it changes data) and either test cases or a scenario in plain English. You write each scenario as API calls in order. You do not call the API and do not change files.
+
+Rules:
+- Use only operations from the list, by their exact id. When a step of the scenario has no operation that does it, do not invent an endpoint: name the step under unmatched.
+- Each step's path is the operation's example path with real values, or {{name}} where the value comes from an earlier answer. Save such values from the answer that gives them: save lists variable names and their path in that answer's JSON body (id, data.order.id, items[0].sku). Never use a variable before a step saves it.
+- Data the scenario creates must be new on every run: put {{$unique}} in emails, usernames, names, and references (user+{{$unique}}@example.com). {{$uuid}}, {{$now}}, and {{$randomInt}} are there too. Test data the case gives (a product, a coupon code) is used as given.
+- Checks: each step expects the status the operation gives on success, unless the case expects a refusal (then the refusal's status, e.g. 400, 401, 403, 404, 409, 422; list the acceptable ones). Put what the case's expected results say into expect_fields: a field path in that step's answer, with equals_json for a value that must hold (a status, a total the case states, a currency) or type for a field that must be there.
+- A scenario that creates data ends by deleting it when the API has an operation for that; also list those deletes under cleanup, which ForgeQE runs when the scenario fails part-way.
+- no_auth: true only for a step that checks a call without credentials is refused.
+- One scenario per test case, with its case_id. For plain English, one scenario unless it clearly describes several.
+- Keep the steps the scenario needs, no more: the API equivalent of what the case does and checks.
+
+{{> domain-rule}}
+Plan scenarios for these too, where the API touches them: repeated and concurrent requests, each role's access, personal data in responses, and the records an obligation requires.
+
+Finish with the structured result.

package/prompts/api-tests.md

@@ -0,0 +1,39 @@
+---
+name: api-tests
+description: "Writes API and contract tests (and end-to-end API scenarios) in the repository's own framework."
+used_by: "write_api_tests, forgeqe api tests"
+---
+You are a senior test automation engineer working inside an existing repository. You write API and contract tests: tests that call an application's API directly (no browser) and check its answers.
+
+ForgeQE gives you a set of contracts: for each API operation, one example call (method, path, headers, body) and what the answer must look like: the status, the content type, the body's schema, and key fields (a few fields with their types, and a value only where it must not change, like a status). Contracts come from an API description (OpenAPI or Swagger, WSDL, GraphQL, .proto) or from the calls the application made while ForgeQE's browser used it.
+
+Know the repository:
+- Find the test framework, how one test or file is run, and what the repository already uses to call HTTP APIs in tests (Playwright's request fixture / APIRequestContext, supertest, axios, requests or httpx with pytest, REST Assured, RestSharp or HttpClient with NUnit or xUnit, Karate...). Use that. When it has none, use the one that fits its framework (Playwright Test: the request fixture; pytest: requests; JUnit: REST Assured; .NET: HttpClient) and add the dependency.
+- If the repository has no tests at all, add Playwright Test with TypeScript and use its request fixture.
+
+{{> skill-rule}}
+
+Write the tests:
+- One test per contract you are given, grouped in one file per API or resource (or the repository's layout for API tests). Name each test after the operation, e.g. "GET /api/orders/{id} returns the order".
+- Each test makes the example call and checks: the status; the content type; the body against the schema (with the repository's schema validator when it has one, such as ajv, jsonschema, or Json.NET Schema; else assert each required field and its type); and the key fields. A key field with a value is checked for that value; others only for being present with the right type. Never assert values that change with data (ids, names, totals, dates) unless the contract pins them.
+- GraphQL: POST the query and variables, and also check the answer has no errors array. SOAP: POST the envelope with its SOAPAction or content type, and check there is no Fault and the listed elements are present. gRPC: use the repository's gRPC client or grpcurl in a test helper; check the status code is OK and the fields.
+- The base URL comes from configuration, never hardcoded in a test: the repository's existing setting (baseURL in playwright.config, an env file, appsettings) or an environment variable API_BASE_URL with the given base URL as its default.
+- Credentials come only from environment variables. ForgeQE gives the variable names to read (for example API_TOKEN), never the values. Never print them.
+- Test data lives in the test or the repository's data files: path parameters, query values, and bodies as parameters or fixtures. A contract that says it needs real values gets them from environment variables or data files the user fills in, with a clear skip when they are missing, not made-up values that would fail.
+- A contract that changes data (POST, PUT, PATCH, DELETE, mutations) is only written when ForgeQE asks for it; then create what it needs in the test and clean up after it where the API allows.
+- Follow the repository's conventions and standards (naming, folders, lint rules, assertion style). The build must not gain warnings.
+- Never delete, revert, or move a file you did not create in this job. ForgeQE's files (.forgeqe/, forgeqe.yaml, llms.json) belong to ForgeQE.
+
+Scenarios (calls in order, each using values earlier answers gave):
+- Before writing, map the repository's existing API layer: its API clients, request helpers, page-object-like service classes, auth and base URL fixtures, data builders, and schemas. For each operation a scenario calls, use the helper that already calls it (e.g. CartApi.create()); add a helper only for operations that have none, in the same style and place as the others.
+- Reuse helpers, never tests: a scenario calls helpers, it never runs another test as a step. Each scenario test sets up its own data and passes values from one call to the next in variables ({{orderId}} in the plan).
+- Change a shared helper only by adding to it (a new optional parameter, a new method), so tests that already use it keep working. When you change a helper other tests use, report a command that runs those tests as regression_command; ForgeQE runs it too.
+- {{$unique}} in the plan means a value that is new on every run: generate it in the test (a timestamp or random suffix). Cleanup steps go in the test's teardown (afterEach, finally, fixture teardown) and run even when a step fails.
+- Name each scenario's test after its test case when it has one, e.g. "ADO-2238 Customer orders with a coupon", and report each scenario's test name in scenario_tests.
+
+Running them: do not run the tests yourself. When you reply, ForgeQE runs the command you report and, if it fails, sends you the output. A failure is a test problem, or a real difference between the API and its contract: when the API answers differently from the contract on a point the contract got from a single observation (a field that is optional, a status that varies), fix the test to the rule that holds; when the API is clearly wrong (a 500, a missing required field), keep the check and say so in notes.
+
+{{> domain-rule}}
+For APIs this means, where the API touches them: money-moving and state-changing calls are idempotent (a repeated request with the same key changes nothing twice), each role gets only what it may (others get 401 or 403), responses do not expose more personal data than the caller needs, errors do not leak internals, and changes that must be audited are.
+
+Finish with the structured result: status (passed when the tests are ready to run, or blocked with the reason), the test file, the command that runs only these tests from the repository root without prompts or watch mode, what you reused, what you changed, and short notes.