@capagents/forgeqe 1.1.2 → 1.1.4

package/HOW_TO_USE.md

@@ -1,6 +1,6 @@
 # How to use ForgeQE
 
-ForgeQE is a browser agent CLI. Say what you want in plain language: a goal to carry out in a browser, test cases to run from Jira, Azure DevOps, Xray or a file, a test to write, or a CI pipeline to set up. ForgeQE's agent works out what that needs, the ForgeQE engine drives Chrome, and a run that passes becomes a test in your repo, written by **Scribe**, ForgeQE's coding agent.
+ForgeQE is a browser agent CLI. Say what you want in plain language: a goal to carry out in a browser, test cases to run from Jira, Azure DevOps, Xray or a file, a test to write, or a CI pipeline to set up. ForgeQE's agent works out what that needs, the ForgeQE engine drives a local Chrome or Chromium by default or BrowserStack or TestMu AI/LambdaTest when configured, and a run that passes becomes a test in your repo, written by **Scribe**, ForgeQE's coding agent.
 
 No server, database, or Docker. You configure a model and run it from the terminal.
 
@@ -32,7 +32,7 @@ forgeqe docs --copy ./docs   # copy the guide, the architecture page, and the re
 | Name | What it does | May change files |
 |------|----------------|------------------|
 | `forgeqe` | Reads the request and calls the tools below | No |
-| Browser agent | Drives Chrome one step at a time | No |
+| Browser agent | Drives the configured browser one step at a time | No |
 | `forgeqe-read` | Learns the repo's test setup before a handoff | No |
 | `forgeqe-test` | Scribe: writes the test in the repo's own framework | Yes, in the repo |
 | `forgeqe-review` | Approves that test, or sends issues back | No |
@@ -47,7 +47,7 @@ Everything ForgeQE can do, by area. ForgeQE's agent answers "can you…?" questi
 <!-- capabilities:start (generated from src/capabilities/registry.ts by bun scripts/gen-capabilities.ts; do not edit) -->
 | Area | Capability | Tools | |
 |------|------------|-------|-|
-| Browser | **Run any goal in a real browser**: Carries out a plain-language goal in Chrome one step at a time and verifies the outcome, with screenshots, a report, and the steps it took. Page memory replays steps that already worked on a site, so repeat runs are faster and cheaper. | `browser_run`, `run_details`, `page_memory` | [docs](#4-without-the-shell) |
+| Browser | **Run any goal in a real browser**: Carries out a plain-language goal in a real browser one step at a time and verifies the outcome, with screenshots, a report, and the steps it took. The browser comes from forgeqe.yaml: local Chrome or Chromium by default, or BrowserStack or TestMu AI/LambdaTest when configured. Page memory replays steps that already worked on a site, so repeat runs are faster and cheaper. | `browser_run`, `run_details`, `page_memory` | [docs](#4-without-the-shell) |
 | Browser | **Saved logins for the application under test**: Signs the browser agent in with saved credentials (including TOTP) and reuses the session; a user can also sign in by hand once in a browser. | `logins` | [docs](#signing-in) |
 | Test cases | **Run manual test cases in browsers**: Reads test cases from Azure DevOps, Jira, Xray, TestRail, Zephyr Scale, qTest, a file, or pasted text, runs each in a real browser with a verdict per step, writes report.html and junit.xml, posts results back, and files or updates bugs for failures. | `find_test_cases`, `run_test_cases` | [docs](#7-test-cases-and-suites) |
 | Test cases | **Check and improve test cases**: Checks test cases before they run (vague or missing expected results, missing test data, placeholders, duplicates) against the story, feature, and epic they test, then rewrites Azure DevOps cases once the user agrees. | `check_test_cases`, `update_test_case` | [docs](#checking-test-cases-before-they-run) |
@@ -71,7 +71,7 @@ Everything ForgeQE can do, by area. ForgeQE's agent answers "can you…?" questi
 | Systems | **Work with Azure DevOps, Jira, and Confluence**: Reads anything in the configured systems (work items, issues, queries, boards, pages), makes changes the user asks for, and builds Azure DevOps dashboards and wiki pages. | `query_api`, `read_confluence`, `create_ado_dashboard`, `write_ado_wiki_page` | [docs](README.md#azure-devops-jira-and-other-systems) |
 | Setup | **Setup, skills, and documentation**: Shows the model profiles and MCP servers, installs or repairs the browser engine, creates a forgeqe.yaml, manages skills, and answers questions about ForgeQE from its documentation and this list. | `forgeqe_setup`, `capabilities` | [docs](#2-scaffold-config) |
 
-Not supported: Native mobile apps (iOS, Android) and desktop applications (instead: web applications in Chrome or Chromium); Load, stress, or soak testing with many simultaneous users (instead: per-page Core Web Vitals with budgets); Penetration testing or dynamic security scanning (instead: security findings in pull request reviews).
+Not supported: Native mobile apps (iOS, Android) and desktop applications (instead: web applications in local Chrome or Chromium, or configured remote web grids such as BrowserStack and TestMu AI/LambdaTest); Load, stress, or soak testing with many simultaneous users (instead: per-page Core Web Vitals with budgets); Penetration testing or dynamic security scanning (instead: security findings in pull request reviews).
 <!-- capabilities:end -->
 
 ---
@@ -91,7 +91,7 @@ Not supported: Native mobile apps (iOS, Android) and desktop applications (inste
 
 | Optional | Why |
 |----------|-----|
-| **Google Chrome** | Used when installed; otherwise ForgeQE installs Chromium |
+| **Google Chrome** | Used when installed; otherwise ForgeQE installs Chromium. Or set `browser.provider` to BrowserStack or TestMu AI/LambdaTest |
 | **A repo with tests** | Where passed runs become tests (`--repo`, or `code.repo`); without one, tests go in the current folder |
 | **Jira, Azure DevOps, Xray, TestRail, Zephyr Scale, qTest, Confluence** | Sources of test cases and requirements, and where results go back |
 | **`gh` or `az`** | For pipelines: pushing, secrets, and triggering runs |

package/README.md

@@ -1,6 +1,6 @@
 # ForgeQE
 
-Browser agent CLI. Say what you want in plain language: a goal to carry out in a browser, test cases to run from Jira, Azure DevOps, Xray or a file, a test to write, or a CI pipeline to set up. ForgeQE's agent works out what that needs and calls ForgeQE's tools. The ForgeQE engine drives Chrome locally, or BrowserStack and TestMu AI/LambdaTest through their Playwright CDP endpoints, and a run that passes becomes a test in your repo's own language and framework, written by **Scribe**, ForgeQE's coding agent. Skills (`SKILL.md` folders, built in or in `.forgeqe/skills`) teach the agents your repo's conventions and the apps you test.
+Browser agent CLI. Say what you want in plain language: a goal to carry out in a browser, test cases to run from Jira, Azure DevOps, Xray or a file, a test to write, or a CI pipeline to set up. ForgeQE's agent works out what that needs and calls ForgeQE's tools. The ForgeQE engine drives Chrome locally, or BrowserStack and TestMu AI/LambdaTest through their Chrome DevTools Protocol (CDP) endpoints, and a run that passes becomes a test in your repo's own language and framework, written by **Scribe**, ForgeQE's coding agent. Skills (`SKILL.md` folders, built in or in `.forgeqe/skills`) teach the agents your repo's conventions and the apps you test.
 
 The engine is the browser service from test-agent-nexus, copied into this package (`py/forgeqe_engine`). It keeps the nexus behaviour: error-recovery system prompt, fast-mode agent tuning, Chrome launch flags, the search/select loop breaker, the 600 s run timeout, compact workflow YAML with semantic locators. There is no dependency on test-agent-nexus, FastAPI, or a database.
 
@@ -64,9 +64,12 @@ ForgeQE sends no telemetry and turns it off in everything it starts:
 | `.forgeqe/prompts/` | Every agent prompt as a markdown file, to change how an agent works (`forgeqe prompts` lists them) |
 | `.forgeqe/skills/` | The built-in skills, to adapt; add your own beside them |
 | `.forgeqe/knowledge/` | Product knowledge templates: product, roles, glossary, business rules, test data, environments |
+| `.forgeqe/browserstack.yaml` / `.forgeqe/testmu.yaml` | Sample remote-browser provider configs, ready to point `browser.providers` at |
 
 An unchanged copy keeps following ForgeQE's updates; once you edit it, yours wins.
 
+For remote browsers, `forgeqe.yaml` can now point at provider-specific YAML files under `browser.providers` such as `browserstack` and `testmu`, so the BrowserStack or TestMu AI connection details do not have to live inline under `browser.remote`. `forgeqe init` drops sample files at `.forgeqe/browserstack.yaml` and `.forgeqe/testmu.yaml`. When both are present, the separate file supplies the provider defaults and the inline `browser.remote` values override only the active provider. ForgeQE's agent can also switch providers per request by passing `browser_provider` to `browser_run` or `run_test_cases`, and the CLI can pin one with `--browser-provider`. ForgeQE drives remote browsers over CDP, so `remote.browser` must be Chrome or Edge, and the default endpoints are the providers' CDP (`/puppeteer`) ones. On a remote grid, the browser stops taking real clicks and keystrokes on a tab once a password form has been submitted (most likely the browser's password manager), so after a sign-in leaves the login page ForgeQE reopens the page it landed on in a fresh tab, with the session intact, and the run log says so.
+
 ```bash
 forgeqe models
 forgeqe run "Read the homepage of example.com" --plain
@@ -237,7 +240,7 @@ Every suite writes `report.html`, `junit.xml`, and `suite.json` to `.forgeqe/rep
 
 ### Static BI
 
-`forgeqe bi` adds an offline BI layer on top of those reports. It exports curated CSV datasets from ForgeQE's own suite history and release-readiness reports, plus optional Azure DevOps WIQL and Jira JQL datasets from `bi.datasets` in `forgeqe.yaml`, scaffolds an [Evidence](https://github.com/evidence-dev/evidence) project, and runs `evidence build` to produce static HTML. No backend service stays up between runs: the refresh happens during `forgeqe bi sync` or `forgeqe bi build`, and the output is a static site in the configured build directory.
+`forgeqe bi` adds an offline BI layer on top of those reports. It exports curated CSV datasets from ForgeQE's own suite history and release-readiness reports, plus optional Azure DevOps WIQL and Jira JQL datasets from `bi.datasets` in `forgeqe.yaml`, into an [Evidence](https://github.com/evidence-dev/evidence) project that reads them through its CSV source, then runs `evidence sources` and `evidence build` to produce a static site in the configured build directory. ForgeQE uses the open-source Evidence line (`@evidence-dev/evidence` 40.x, pinned in the generated `package.json`), because the newer Evidence Studio CLI has no local build and keeps data in its cloud. Building it needs Node.js 18 or later; serve the folder to view it (`npx serve`), since it cannot load its data when opened from disk. When Node.js is missing or the Evidence build fails, `forgeqe bi build` writes ForgeQE's own self-contained page from the same data instead, which opens straight from disk, and says why; `--static` always does that, and `--evidence` fails instead of falling back. Dataset ids become table names (`forgeqe.<id>`), so they use letters, digits, and `_`. Pages ForgeQE generates carry a "Managed by forgeqe bi" comment in their front matter; a page without it is yours and is never overwritten. Tables with no rows yet stay out of the Evidence project (Evidence cannot build over an empty table), and their sections read "None yet." No backend service stays up between runs.
 
 ```yaml
 bi:
@@ -257,8 +260,9 @@ bi:
 ```
 
 ```bash
-forgeqe bi init
-forgeqe bi build
+forgeqe bi init            # scaffold the Evidence project and install its packages
+forgeqe bi build           # refresh the data and build the site (ForgeQE's own page if Evidence cannot build)
+forgeqe bi build --static  # ForgeQE's own page only, no Node.js needed
 ```
 
 ## Signing in

package/browserstack.example.yaml

@@ -0,0 +1,14 @@
+provider: browserstack
+remote:
+  browser: chrome
+  browser_version: latest
+  os: osx
+  os_version: sequoia
+  username_env: BROWSERSTACK_USERNAME
+  access_key_env: BROWSERSTACK_ACCESS_KEY
+  project: ForgeQE
+  build: nightly
+  name: checkout smoke
+  local: false
+  extra:
+    browserstack.console: errors