@capagents/forgeqe 2.2.0 → 2.2.2

package/docs/user-guide.html

@@ -379,7 +379,7 @@ forgeqe docs --copy ./docs   # copy the guide, the architecture page, and the re
 </code></pre>
 </div>
 <h3 class="band-title">Every feature</h3>
-<div class="area"><a class="area-name" href="#area-browser"><span class="mono">Browser</span></a><ul class="tiles"><li><a class="tile" href="#cap-browser-goals"><b>Run any goal in a real browser</b><span>Go to booking.com and search hotels in Mumbai for next weekend</span></a></li><li><a class="tile" href="#cap-logins"><b>Saved logins for the application under test</b><span>Sign in to the admin site and keep the session</span></a></li></ul></div>
+<div class="area"><a class="area-name" href="#area-browser"><span class="mono">Browser</span></a><ul class="tiles"><li><a class="tile" href="#cap-browser-goals"><b>Run any goal in a real browser</b><span>Go to booking.com and search hotels in Mumbai for next weekend</span></a></li><li><a class="tile" href="#cap-logins"><b>Saved logins for the application under test</b><span>Sign in to the admin site and keep the session</span></a></li><li><a class="tile" href="#cap-record-web"><b>Record a web test by hand</b><span>I'll show you the checkout steps in the shop: record them</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-test-cases"><span class="mono">Test cases</span></a><ul class="tiles"><li><a class="tile" href="#cap-run-test-cases"><b>Run manual test cases in browsers</b><span>Run SHOP-12 and SHOP-14 from Jira, two browsers at once</span></a></li><li><a class="tile" href="#cap-test-case-quality"><b>Check and improve test cases</b><span>Are the cases in test plan 12 good enough to run?</span></a></li><li><a class="tile" href="#cap-write-test-cases"><b>Write test cases from a story</b><span>Write test cases for story 1234 and save them</span></a></li><li><a class="tile" href="#cap-domain-compliance"><b>Domain and regulatory test design</b><span>Write test cases for story 1234, covering our DORA and PSD2 obligations</span></a></li><li><a class="tile" href="#cap-exploratory-testing"><b>Exploratory testing of a story</b><span>Explore story 1234 and find bugs</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-setup"><span class="mono">Setup</span></a><ul class="tiles"><li><a class="tile" href="#cap-test-apps"><b>Test environments and their apps</b><span>Place an order in the shop, then check its invoice in Billing, in UAT</span></a></li><li><a class="tile" href="#cap-generated-code"><b>What ForgeQE wrote</b><span>How much of the code ForgeQE wrote is still there?</span></a></li><li><a class="tile" href="#cap-forgeqe-commands"><b>Every forgeqe command from the shell</b><span>Show me the context budget</span></a></li><li><a class="tile" href="#cap-setup-help"><b>Setup, skills, and documentation</b><span>What can you do?</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-desktop"><span class="mono">Desktop</span></a><ul class="tiles"><li><a class="tile" href="#cap-desktop-apps"><b>Automate Windows desktop apps</b><span>Create an invoice for Contoso in the Billing app and save it as a test</span></a></li></ul></div>
@@ -997,6 +997,99 @@ forgeqe memory stats                        # how often memory stood in for the
 </section>
 </div>
 </article>
+<article class="spec feat" id="cap-record-web">
+<div class="hd"><span class="mono">Browser</span><h3>Record a web test by hand</h3></div>
+<p class="ds">Opens a browser with the Recorder panel docked in the page while the user does the steps of a web test themself, and saves their clicks, typing, choices and keys in order as a run, with the checks, kept values, test data and notes they add; the coding agent then turns it into a test in the repository's framework.</p>
+<div class="facts">
+<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>I'll show you the checkout steps in the shop: record them</li><li>Record my steps on the cart page and make a test of it</li></ul></div>
+<div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need opt">Optional</span><span>The coding agent, Scribe: a live model profile (or code.model) and the agent runtime, which forgeqe setup installs</span></li></ul></div>
+<div class="fact"><span class="mono">Limits</span><ul class="plainlist"><li>Local Chrome or Chromium only, one recording at a time; drag and drop and steps inside iframes are not recorded yet</li></ul></div>
+<div class="fact"><span class="mono">Tools</span><p class="tools"><code>web_record</code></p></div>
+</div>
+<div class="detail"><span class="mono">In detail</span>
+<section class="doc" id="doc-how_to_use-recording-a-web-test-by-hand">
+<h4>Recording a web test by hand</h4>
+<div class="prose"><p>When you would rather show the steps than describe them, record them. ForgeQE opens Chrome on the app's page with the
+<strong>Recorder</strong> panel docked in a corner of the page, in the same window: you click, type and choose as usual, and each
+action is listed in the panel as a numbered step, in order. Drag the panel by its title to another corner, or make it
+small (a pill that shows the step count); it comes back where you left it on every page.</p>
+<pre><code class="language-bash">forgeqe record shop --name &quot;Apply a coupon at checkout&quot;     # a web app from env.yaml
+forgeqe record --url https://staging.shop.test/cart         # or any page
+</code></pre>
+<p>In the shell, say &quot;I'll show you the checkout, record it&quot; (or <code>/record shop</code>). What you can add while recording:</p>
+<div class="tbl"><table>
+<thead>
+<tr><th>In the panel</th><th>In the page: Ctrl+Shift+Space, then</th><th>What it adds</th></tr>
+</thead>
+<tbody>
+<tr><td>Check, then click an element</td><td><strong>A</strong></td><td>A check: its text, or its value for a field, or checked for a checkbox. Change the kind (text, visible, hidden, value) and mark <strong>live data</strong> (check the pattern, not this value) in the panel</td></tr>
+<tr><td>Variable, then click an element</td><td><strong>V</strong></td><td>Keeps the element's text for later steps: typing the same text later is written as <code>{{name}}</code></td></tr>
+<tr><td>Wait for, then click an element</td><td><strong>W</strong></td><td>The test waits for the element to show</td></tr>
+<tr><td>Test data</td><td><strong>D</strong></td><td>The last value you typed becomes test data the test reads from its data</td></tr>
+<tr><td><code>note: …</code> in the box</td><td><strong>N</strong></td><td>A note on the last step: &quot;this is the cart page object&quot;</td></tr>
+<tr><td>Pause / Undo / Stop, ✕ on a step</td><td><strong>P</strong> / <strong>Z</strong> / <strong>S</strong></td><td>Pause records nothing until you resume; ✕ removes that step</td></tr>
+</tbody>
+</table></div>
+<p>Type a check in words in the panel's box, or in the terminal: <code>the total shows &quot;$40.00&quot;</code>. Quoted text the page shows
+becomes a check on the element showing it; without quotes, one model call finds the text that shows it on the page. A
+check the page cannot show yet is kept in your words, and the coding agent writes it. In the terminal, <code>undo</code>, <code>pause</code>,
+<code>delete 4</code> and <code>stop</code> work too.</p>
+<p>What is recorded: clicks (a double click as one step), the final text of each field you typed in (not each key), choices
+in drop-downs, Enter and Escape, key chords, pages you open from the address bar, and Back. A click on a menu item that
+opened when the pointer went over its trigger gets a hover on the trigger first. Password fields are written as an
+environment variable (the saved login's <code>password_env</code>, or <code>&lt;SITE&gt;_PASSWORD</code>), and text equal to a saved login's value
+as its variable: what you type in them is never stored. A file you choose for an upload is recorded by its path in the
+working folder; one outside it, a hidden file (<code>.env</code>, anything under <code>.git</code>), or one named like credentials or keys is
+listed as not recorded. Drag and drop is listed as not recorded. <code>--signed-in</code> starts with the saved sessions of
+<code>logins:</code>; without it, record the sign-in too.</p>
+<p><strong>Data that changes from run to run.</strong> A test that spells out this recording's price, date, or order number fails on
+the next run, so ForgeQE keeps what holds and makes the rest a pattern, a variable, or a value made fresh:</p>
+<div class="tbl"><table>
+<thead>
+<tr><th>In the recording</th><th>In the test</th></tr>
+</thead>
+<tbody>
+<tr><td>A check of a price, date, time, order number, or count (&quot;$14.15&quot;, &quot;2,463 found&quot;)</td><td>A check of its pattern: <code>/^\$\d[\d,]*\.\d{2}$/</code></td></tr>
+<tr><td>The same value checked again later (the product's price, then the cart total)</td><td>The first check keeps it as <code>{{price}}</code>; the later one checks <code>{{price}}</code></td></tr>
+<tr><td>A link or button named with such data (&quot;Combination Pliers $14.15&quot;)</td><td>Found by the part that holds: <code>getByRole(&quot;link&quot;, { name: /Combination Pliers/ })</code></td></tr>
+<tr><td>A date you typed</td><td>The date the same number of days from today: <code>{{$date:+3:%Y-%m-%d}}</code></td></tr>
+<tr><td>A value the app refuses twice (a new account's email)</td><td>A part new on each run: <code>alice+{{$unique}}@example.com</code></td></tr>
+</tbody>
+</table></div>
+<p>Prices, dates, times, ids, and long numbers are found by their form; a small number on its own (&quot;1&quot; in the cart) stays
+exact, as it is usually what the check is about. When you stop, one model call sorts the values the forms cannot
+tell (a new account's email, &quot;today's deal&quot;); without a model, those stay as recorded. Each change shows in the panel
+with a tick box: untick it to keep the value as recorded.</p>
+<p><strong>Recording a test case.</strong> <code>forgeqe record --case SHOP-12</code> (any source ForgeQE reads cases from: Jira, Azure DevOps,
+Xray, TestRail, a file) starts on the case's page and shows its steps as a checklist in the panel. Click the step you
+are on (or <strong>Next case step</strong>): what you record belongs to it, and a check you add there takes its expected result.
+Each expected result shows <strong>✓ checked</strong> or <strong>no check yet</strong>; Stop warns once about the ones with no check, and a second
+Stop stops. The test is named and tagged for the case, and mapped to it once it passes.</p>
+<p>When you stop, the run folder holds <code>workflow.yaml</code> and <code>trace.md</code> as for any run. With a repository (<code>--repo</code>, or
+<code>code.repo</code>), ForgeQE asks whether to turn it into a test. First a planner reads the repository and shows the plan:</p>
+<pre><code>Test      tests/add-to-cart.spec.ts › adds pliers to the cart
+Steps
+   2. search: HomePage.searchFor()
+   4. open the product: new HomePage.product(name)
+   6. add to the cart: new ProductPage.addToCart()
+New code
+  ProductPage in pages/ProductPage.ts
+Checks
+  after step 5: expect(product.price).toHaveText(/^\$\d+\.\d{2}$/)
+  after step 6: expect(product.cartQuantity).toHaveText(&quot;1&quot;)
+</code></pre>
+<p>It asks at most three questions where the repository allows two good answers (a new file, or the existing spec?), then
+<strong>Write it</strong>, <strong>Change the plan</strong> (say what to change, in your words), or <strong>Cancel</strong>. The coding agent replays the
+recording in Playwright, writes the test to the plan you agreed in the repository's framework, and asserts each check at
+the step where you added it. In the shell, &quot;change the plan&quot; comes back to ForgeQE's agent, which asks you what to
+change. <code>--no-plan</code> (or <code>--yes</code>) skips the plan. Later: <code>forgeqe code &lt;run folder&gt;</code>.</p>
+<p>The recorder runs in an isolated world in each page, so the page's own scripts can neither see it nor add steps, and it
+records only real input: clicks and keys a script fakes are ignored. The panel's own clicks and keys never reach the page
+and are never recorded, and it stays above the page's dialogs. Recording uses local Chrome or Chromium.</p>
+</div>
+</section>
+</div>
+</article>
 </section>
 <section class="chapter" id="area-test-cases" aria-labelledby="area-test-cases-h">
 <header class="chead"><span class="mono">05</span><h2 id="area-test-cases-h">Test cases</h2><p>Run, check, write, and explore manual test cases</p></header>
@@ -2653,11 +2746,26 @@ Run the tests added since 2026-09-01
 <p>Through <code>forgeqe mcp</code>, ForgeQE cannot ask you, so <code>run_tests</code> returns the list and runs only when called again with <code>confirmed: true</code>; the MCP client should ask you first.</p>
 </div>
 </section>
+<section class="doc" id="doc-how_to_use-reports-for-tests-run-outside-forgeqe">
+<h4>Reports for tests run outside ForgeQE</h4>
+<div class="prose"><p>ForgeQE's HTML report is not only for runs it makes. <code>run_tests</code> and <code>pr-tests --run</code> write one, and so can any run in a terminal, an IDE's test runner, or CI:</p>
+<pre><code class="language-bash">forgeqe report test-results/junit.xml               # from JUnit XML or TRX: any framework, after the run
+forgeqe report setup                                # a report after every Playwright or pytest run, automatically
+</code></pre>
+<p><code>forgeqe report</code> reads JUnit XML or TRX files, or the folder they are in (Playwright <code>--reporter=junit</code>, pytest <code>--junitxml=results.xml</code>, <code>dotnet test --logger trx</code>), and exits 1 when a test failed. Each report is saved in <code>&lt;out_dir&gt;/results/&lt;time&gt;/</code>, so its Trends and Flaky tests pages cover the earlier runs, whoever ran them. JUnit carries one line per failure; a skipped test is counted, not shown.</p>
+<p><code>forgeqe report setup</code> sets up the framework the repository uses:</p>
+<ul>
+<li><strong>Playwright</strong>: it copies a reporter to <code>.forgeqe/playwright-reporter.mjs</code> (commit it) and prints the line to add to <code>playwright.config</code>: <code>reporter: [[&quot;list&quot;], [&quot;./.forgeqe/playwright-reporter.mjs&quot;]]</code>. Every run then ends with a report, from <code>npx playwright test</code>, the VS Code Playwright extension, or CI. With <code>screenshot: &quot;only-on-failure&quot;</code> and <code>trace: &quot;retain-on-failure&quot;</code>, each failure shows its screenshot, the full error and stack, and the trace.</li>
+<li><strong>pytest</strong>: install <code>forgeqe-cli</code> in the environment that runs the tests (<code>pip install forgeqe-cli</code>). Its plugin loads by itself, from the terminal, VS Code's test explorer, or CI, in a folder with <code>forgeqe.yaml</code> or <code>.forgeqe/</code> (elsewhere with <code>pytest --forgeqe-report</code>). A test that passes when pytest-rerunfailures runs it again is reported as flaky.</li>
+</ul>
+<p><code>FORGEQE_REPORT=0</code> turns the reporters off for a run (ForgeQE's own <code>run_tests</code> does this, as it writes its own report). The reporters call <code>forgeqe</code> on PATH, or <code>FORGEQE_BIN</code>; without it they keep the results file and print the command that builds the report. Screenshots and traces are copied into the report only from the working folder, never from a hidden folder or a file named like a key.</p>
+</div>
+</section>
 </div>
 </article>
 <article class="spec feat" id="cap-regression-packs">
 <div class="hd"><span class="mono">Automated tests</span><h3>Regression packs for a release</h3></div>
-<p class="ds">Builds a regression pack from what goes into a release (an Azure DevOps sprint or work items, a commit range, pull requests, or changes read from any connected tool): the tests those changes can break, each with why, plus risk-area and smoke tests, and the changes no test covers. Runs it locally, on TestMu AI, or in a pipeline, and compares each run with the last.</p>
+<p class="ds">Builds a regression pack from what goes into a release (an Azure DevOps sprint or work items, a commit range, pull requests, or changes read from any connected tool): the tests those changes can break, each with why, plus risk-area and smoke tests, and the changes no test covers. Runs it locally, on TestMu AI, or in a pipeline, compares each run with the last, and triages each failure: flaky, environment, broken test code, heal, or an AI browser re-run to tell a test the app outgrew from an app bug.</p>
 <div class="facts">
 <div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Build a regression pack for sprint 12 and run it on TestMu</li><li>Which tests should we run for the PRs merged this week?</li></ul></div>
 <div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need input">You give</span><span>a repository with tests</span></li><li><span class="need opt">Optional</span><span>Azure DevOps or Jira, to read a sprint's or release's work items: set up under sources: in forgeqe.yaml, or sign in with /auth</span></li></ul></div>
@@ -2697,7 +2805,22 @@ Build a pack for Jira fix version 2.4 and the commits since release/2.3 in ../sh
 <li><em>This machine</em>: ForgeQE builds one command for exactly the pack's tests, the way the repository already runs a test (for .NET, a <code>--filter</code> with each test, the settings an earlier job used, TRX results), runs it, and reads each result. A failed test runs once more; one that then passes is flaky.</li>
 <li><em>TestMu AI</em>: the same command, with the variable <code>FORGEQE_PW_WS_ENDPOINT</code> set to TestMu AI's Playwright endpoint for the browser and platform in <code>testmu.yaml</code> (the access key goes in the variable, never in the command, and is removed from the output). The tests must connect to it when it is set: for NUnit, override <code>ConnectOptionsAsync</code> in the test base class; for Playwright Test, set <code>connectOptions</code> from it in <code>playwright.config</code>. ForgeQE refuses a TestMu run when the tests do not read the variable, so a run never looks remote while it ran locally.</li>
 </ul>
-<p>Each run is kept with the pack: the card says which tests fail now that passed in the last run, and which were fixed. Packs are saved in <code>.forgeqe/packs/&lt;name&gt;.json</code> and <code>&lt;name&gt;.md</code>; run output and results in <code>.forgeqe/reports/packs/&lt;name&gt;/&lt;time&gt;/</code>.</p>
+<p>Each run is kept with the pack: the card says which tests fail now that passed in the last run, and which were fixed.</p>
+<p><strong>Triage: heal, re-run, or file a bug?</strong> After each run ForgeQE sorts every failed or flaky test into one route, from evidence that costs nothing first (the retry in the same run, the failure message, the test's history), so the AI is spent only where it decides something:</p>
+<div class="tbl"><table>
+<thead>
+<tr><th>Route</th><th>When</th><th>What happens</th></tr>
+</thead>
+<tbody>
+<tr><td>flaky</td><td>it passed when run again in the same run, or its history flip-flops</td><td>not healed: quarantine it, or fix the cause it flakes on</td></tr>
+<tr><td>environment</td><td>network errors, 5xx, a crashed browser, sign-in failing</td><td>run again once the environment works; no heal and no bug</td></tr>
+<tr><td>test code broken</td><td>a missing module, a compile error, a missing fixture</td><td>fix the test's code; healing against the page cannot fix it</td></tr>
+<tr><td>heal</td><td>an element the test uses is no longer found (high confidence when it passed its last runs)</td><td>the healing agent re-runs the flow in the browser and updates the steps and locators</td></tr>
+<tr><td>AI re-run decides</td><td>an expected value does not hold, a timeout, or something covers the element</td><td>the healing agent re-runs the flow in the browser: heals the test when the flow works, reports an app bug when it fails at the same step</td></tr>
+</tbody>
+</table></div>
+<p>Failures that name the same element or the same message are shown as <strong>one cause</strong> (a page object or a shared step changed), so one fix can heal them together. When most failures are the environment, ForgeQE says to run the pack again before healing anything, and <code>heal_tests</code> refuses until you name the tests.</p>
+<p>The triage is on the run's card and in <code>triage.md</code> and <code>triage.json</code> in the run's folder. To heal only the tests it sent to healing, ask &quot;heal the failures of pack release-1.5&quot;, or run <code>forgeqe pack heal release-1.5</code> (<code>--tests</code> for some of them): ForgeQE builds a command for just those tests and the healing agent re-runs each flow in the browser before it changes anything. <code>forgeqe pack triage &lt;name&gt;</code> shows the last run's triage again. Packs are saved in <code>.forgeqe/packs/&lt;name&gt;.json</code> and <code>&lt;name&gt;.md</code>; run output and results in <code>.forgeqe/reports/packs/&lt;name&gt;/&lt;time&gt;/</code>.</p>
 </div>
 </section>
 </div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capagents/forgeqe",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "ForgeQE: a browser agent CLI that runs goals and test cases in local Chrome or Chromium, or BrowserStack and TestMu AI/LambdaTest when configured, and turns passing runs into tests in your repo",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -10,6 +10,7 @@
   },
   "files": [
     "bin/",
+    "reporters/",
     "dist/",
     "py/forgeqe_engine/*.py",
     "py/forgeqe_desktop/*.py",

package/prompts/README.md

@@ -9,6 +9,7 @@ project; leave it as it is to keep getting ForgeQE's improvements when you updat
 | 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 |
+| test-plan.md | Plans how a test you recorded by hand (`forgeqe record`) fits your repository, for you to agree before Scribe writes it |
 | 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 |

package/prompts/brain.md

@@ -255,6 +255,8 @@ When the user asks for a regression pack, or which tests to run for a release, a
 - You MUST report the tests by why they are in, the changes no test covers with the closest test for each, and the risk areas.
 - When the user did not say where to run the pack, you MUST ask one question: on this machine, on TestMu AI, or in a pipeline. You MUST NOT run a pack until the user agrees.
 - After a run, you MUST name the failing tests with their messages, and the tests that fail now but passed in the last run.
+- You MUST give the triage of the run: each failing test's route (flaky, environment, test code broken, heal, or an AI re-run decides) and why. You MUST offer only what the triage says. For heal and AI re-run tests, offer heal_tests with pack. When the environment was down, offer to run the pack again first. You MUST NOT offer heal_tests for flaky, environment, or test code failures.
+- You MUST file a bug only for an app_bug that heal_tests reports, not for a failure the triage routed.
 
 ### Writing tests
 When the user asks, or when the setup below says that passed runs become tests:
@@ -281,7 +283,7 @@ When the user asks, or when the setup below says that passed runs become tests:
 
 ### Repairing broken tests
 When the user says that tests fail, broke after a release, or need healing:
-- You MUST call heal_tests. Give the command when the user gave one or you know it. Otherwise use the test command below, or let the healing agent find it.
+- You MUST call heal_tests. After a regression pack run, give pack, and tests when the user named some. Otherwise give the command when the user gave one or you know it. Otherwise use the test command below, or let the healing agent find it.
 - You MUST report the verdict for each test: healed and confirmed, an application bug, or not healed. For an application bug, give what the browser run found.
 - You MUST also report the files that changed, and heal.md.
 - You MUST NOT delete, skip, or make tests weaker yourself to make a run pass.

package/prompts/test-plan.md

@@ -0,0 +1,61 @@
+---
+name: test-plan
+description: "Plans how a test recorded by hand fits the repository, for the tester to agree before Scribe writes it."
+used_by: "forgeqe record, write_test for a recording"
+kind: structured
+---
+{{> conventions}}
+
+## Role
+You plan how a test that a tester recorded by hand fits a test repository. You do not write or change files.
+
+## Objective
+Tell the tester where the test goes and which code it uses. The tester agrees before Scribe writes it.
+
+## Inputs
+- The handoff: the recorded steps in order, their locators, the tester's checks, variables, test data, and notes.
+- The repository's test setup: the framework, the page objects, the fixtures, and the test data.
+- The tools code_outline, code_element, and code_references. They show what the page objects already locate and do.
+
+## Rules
+Reading:
+- You MUST find the page-object members and methods that already locate each element of the steps. Use the code tools.
+- You SHOULD read only the files that the plan needs.
+
+Where the test goes:
+- You MUST name the test file and the test name. Follow the names and folders of the tests that are there.
+- When an existing test already does the first steps, you MAY propose to extend it. Name that test.
+
+Steps:
+- For each step, you MUST say which existing member or method does it, or which new one the test adds, and where.
+- A new member MUST go in the page object of the page where the step is.
+- You MUST NOT change what an existing member does for the other tests.
+
+Checks and data:
+- For each CHECK line, you MUST say the assertion and the step after which it comes.
+- A check that the tester gave only in words MUST stay in the plan. Say what on the page will show it.
+- For each value marked as test data, you MUST name its source: a fixture, a data file, or a parameter.
+- You MUST keep the secrets as environment variables.
+
+Questions:
+- You MUST ask a question only when the repository allows two good answers and the tester's choice changes the code.
+- You MUST NOT ask more than 3 questions. Give each question 2 to 4 short options, the recommended option first.
+- You MUST NOT ask what the handoff or the repository already answers.
+
+## Output
+The structured result: test_file, test_name, mode, steps, new members, checks, test data, questions, and a short summary.
+
+## Examples
+### Example 1
+Handoff: open the shop, search "pliers", open the first result, add it to the cart, CHECK the cart badge shows "1". The repository has pages/HomePage.ts with searchFor() and no product page object.
+- test_file tests/add-to-cart.spec.ts, test_name "adds pliers to the cart", mode new.
+- Steps: search with HomePage.searchFor(); open the product with a new HomePage.product(name); add to the cart with a new ProductPage.addToCart() in pages/ProductPage.ts.
+- Checks: after the add, expect ProductPage.cartQuantity to have the text "1".
+- Questions: none.
+
+### Example 2
+Handoff: sign in, type the coupon "SAVE10" (test data: coupon), CHECK the total shows text like "$40.00". The repository has tests/data/coupons.json and a fixture that signs in.
+- Steps: sign in with the signedIn fixture; type the coupon with a new CartPage.applyCoupon(code).
+- Test data: read the coupon from tests/data/coupons.json, with SAVE10 as the first entry.
+- Checks: after the coupon, expect CartPage.total to match /^\$\d+\.\d{2}$/.
+- Questions: "Add the coupon test to tests/cart.spec.ts, or a new file?" Options: "tests/cart.spec.ts", "A new file".

package/py/forgeqe_engine/cli.py

@@ -9,6 +9,7 @@ Engine process protocol, used by the Bun CLI:
 
   python -m forgeqe_engine run
   python -m forgeqe_engine login   (stdin: {url, logins}, then "save")
+  python -m forgeqe_engine record  (stdin: {start_url, out_dir, ...}, then commands; "stop" or EOF ends it)
   python -m forgeqe_engine doctor
   python -m forgeqe_engine token   (stdin: an llms.json profile with auth: entra; prints {token, expires_on})
   python -m forgeqe_engine probe   (stdin: an llms.json profile; prints {ok, ms, structured, vision, error?})
@@ -155,6 +156,47 @@ def _login(out: TextIO) -> int:
     return asyncio.run(main())
 
 
+def _record(out: TextIO) -> int:
+    """stdin line 1: the recording request (recordsession.py); later lines are commands ("stop", or JSON {"cmd": ...}); EOF stops."""
+    from .recordsession import record_web
+
+    line = sys.stdin.readline()
+    payload = json.loads(line) if line.strip() else {}
+    lock = threading.Lock()
+
+    def emit(event: Dict[str, Any]) -> None:
+        with lock:
+            out.write(json.dumps(event, ensure_ascii=False, default=str) + "\n")
+            out.flush()
+
+    async def main() -> int:
+        loop = asyncio.get_running_loop()
+        commands: asyncio.Queue = asyncio.Queue()
+
+        def watch_stdin() -> None:
+            for raw in sys.stdin:
+                text = raw.strip()
+                if not text:
+                    continue
+                try:
+                    cmd = json.loads(text) if text.startswith("{") else {"cmd": text.lower()}
+                except ValueError:
+                    continue
+                if isinstance(cmd, dict):
+                    loop.call_soon_threadsafe(commands.put_nowait, cmd)
+            loop.call_soon_threadsafe(commands.put_nowait, {"cmd": "stop"})
+
+        threading.Thread(target=watch_stdin, daemon=True).start()
+        try:
+            result = await record_web(payload, emit, commands)
+        except Exception as e:
+            result = {"success": False, "error": f"{type(e).__name__}: {e}"}
+        emit({"type": "done", "result": result})
+        return 0 if result.get("success") else 1
+
+    return asyncio.run(main())
+
+
 def _token(out: TextIO) -> int:
     """stdin: an llms.json profile with auth: entra. Prints {token, expires_on} for its scope, or {error}."""
     from .llm import entra_credential, entra_scope
@@ -204,6 +246,8 @@ def main(argv: list[str] | None = None) -> int:
         return _run(out)
     if cmd == "login":
         return _login(out)
+    if cmd == "record":
+        return _record(out)
     if cmd == "token":
         return _token(out)
     if cmd == "probe":

package/py/forgeqe_engine/dynamic.py

@@ -0,0 +1,149 @@
+"""
+Data that changes from one run to the next, in what a recording keeps: prices, dates, times, ids and order numbers,
+long numbers and counts in a sentence. A test that spells this run's value out fails on the next run, so the recorder
+keeps the parts that hold and makes the rest a pattern, a variable, or a value made fresh on each run.
+
+- ``parts(text)``: the spans of ``text`` that change, with their kind.
+- ``pattern_of(text)``: a regular expression (JavaScript and Python alike) that the text matches on any run: the stable
+  parts as they are, each changing part by its kind.
+- ``stable_part(text)``: the longest part that holds, for a locator that finds the element by it.
+- ``relative_date(text, today)``: a typed date as days from today, for ``{{$date:+N:FORMAT}}``.
+
+A small number on its own ("1" in a cart badge, "3" items) is not changing data: it is usually what the check is about.
+"""
+from __future__ import annotations
+
+import re
+from datetime import date, datetime, timedelta
+from typing import List, Optional, Tuple
+
+_MONTHS = "jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec|january|february|march|april|june|july|august|september|october|november|december"
+
+# (kind, what finds it, the pattern a test asserts instead). Order matters: the first kind to claim a span keeps it.
+_KINDS: List[Tuple[str, "re.Pattern[str]", str]] = [
+    ("uuid", re.compile(r"\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b", re.I), r"[0-9a-fA-F-]{36}"),
+    ("date", re.compile(r"\b\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2})?(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)?\b"), r"\d{4}-\d{2}-\d{2}(?:[T ][\d:.]+(?:Z|[+-][\d:]+)?)?"),
+    ("date", re.compile(r"\b\d{1,2}[/.]\d{1,2}[/.]\d{2,4}\b"), r"\d{1,2}[/.]\d{1,2}[/.]\d{2,4}"),
+    ("date", re.compile(rf"\b(?:\d{{1,2}}\s+(?:{_MONTHS})\.?,?\s+\d{{4}}|(?:{_MONTHS})\.?\s+\d{{1,2}},?\s+\d{{4}})\b", re.I), r"[\w.]+\s+[\w.]+,?\s+\d{4}"),
+    ("time", re.compile(r"\b\d{1,2}:\d{2}(?::\d{2})?\s?(?:[ap]\.?m\.?)?(?![\d:])", re.I), r"\d{1,2}:\d{2}(?::\d{2})?\s?(?:[aApP]\.?[mM]\.?)?"),
+    ("money", re.compile(r"(?:[$€£¥₹]\s?|\b(?:USD|EUR|GBP|INR|JPY|AUD|CAD)\s?)\d[\d,]*(?:\.\d{1,2})?\b|\b\d[\d,]*(?:\.\d{1,2})?\s?(?:USD|EUR|GBP|INR|JPY|AUD|CAD|€|£)", re.I), r"(?:[$€£¥₹]\s?|[A-Z]{3}\s?)?\d[\d,]*(?:\.\d{1,2})?(?:\s?(?:[A-Z]{3}|€|£))?"),
+    ("id", re.compile(r"(?<![\w-])(?=[A-Z0-9-]*\d)(?=[A-Z0-9-]*[A-Z])[A-Z0-9]{1,6}-[A-Z0-9]{2,}(?:-[A-Z0-9]+)*(?![\w-])"), r"[A-Z0-9]+(?:-[A-Z0-9]+)+"),
+    ("id", re.compile(r"#\d{3,}\b"), r"#\d+"),
+    ("id", re.compile(r"\b(?=[A-Za-z0-9]*\d)(?=[A-Za-z0-9]*[A-Za-z])[A-Za-z0-9]{10,}\b"), r"[A-Za-z0-9]{10,}"),
+    ("number", re.compile(r"\b\d{1,3}(?:,\d{3})+(?:\.\d+)?\b|\b\d{4,}(?:\.\d+)?\b|\b\d+\.\d+\b"), r"\d[\d,]*(?:\.\d+)?"),
+]
+# A count in a sentence: "2,463 properties found", "12 results", "3 items in your cart".
+_COUNT = re.compile(r"\b\d[\d,]*(?=\s+(?:results?|items?|products?|properties|matches|hits|records|rows|orders|reviews|comments|people|days|hours|minutes|seconds|left|available|found|in stock)\b)", re.I)
+_COUNT_PATTERN = r"\d[\d,]*"
+
+
+def _spans(text: str) -> List[Tuple[int, int, str, str]]:
+    """(start, end, kind, the pattern of the matcher that found it), in order."""
+    t = text or ""
+    found: List[Tuple[int, int, str, str]] = []
+
+    def free(a: int, b: int) -> bool:
+        return all(b <= s or a >= e for s, e, _, _ in found)
+
+    for kind, rx, pat in _KINDS:
+        for m in rx.finditer(t):
+            if free(m.start(), m.end()):
+                found.append((m.start(), m.end(), kind, pat))
+    for m in _COUNT.finditer(t):
+        if free(m.start(), m.end()):
+            found.append((m.start(), m.end(), "count", _COUNT_PATTERN))
+    return sorted(found)
+
+
+def parts(text: str) -> List[Tuple[int, int, str]]:
+    """The spans of `text` that change from run to run, in order, as (start, end, kind)."""
+    return [(s, e, k) for s, e, k, _ in _spans(text)]
+
+
+def is_dynamic(text: str) -> bool:
+    return bool(parts(text))
+
+
+def _token_pattern(kind: str, value: str, matched: str) -> str:
+    if kind == "date" and re.fullmatch(r"\d{4}-\d{2}-\d{2}", value):
+        return r"\d{4}-\d{2}-\d{2}"
+    if kind == "money":
+        # Keep the currency the run showed; the amount changes.
+        cur = re.match(r"^([$€£¥₹]|[A-Za-z]{3})\s?", value)
+        amount = r"\d[\d,]*(?:\.\d{1,2})?"
+        if cur:
+            return re.escape(cur.group(1)) + r"\s?" + amount
+        tail = re.search(r"\s?([A-Za-z]{3}|€|£)$", value)
+        return amount + (r"\s?" + re.escape(tail.group(1)) if tail else "")
+    return matched
+
+
+def pattern_of(text: str, anchored: bool = False) -> Optional[str]:
+    """A regular expression the text matches on any run, or None when nothing in it changes."""
+    t = " ".join((text or "").split())
+    spans = _spans(t)
+    if not spans:
+        return None
+    out, at = [], 0
+    for s, e, kind, matched in spans:
+        out.append(re.escape(t[at:s]).replace("\\ ", r"\s+"))
+        out.append(_token_pattern(kind, t[s:e], matched))
+        at = e
+    out.append(re.escape(t[at:]).replace("\\ ", r"\s+"))
+    body = "".join(out)
+    return f"^{body}$" if anchored else body
+
+
+def stable_part(text: str, min_len: int = 3) -> str:
+    """The longest stretch of `text` with nothing that changes in it, trimmed; "" when none is long enough."""
+    t = " ".join((text or "").split())
+    cuts, at = [], 0
+    for s, e, _ in parts(t):
+        cuts.append(t[at:s])
+        at = e
+    cuts.append(t[at:])
+    best = max((c.strip(" ,.:;|/-–·") for c in cuts), key=len, default="")
+    return best if len(best) >= min_len and re.search(r"[A-Za-z]", best) else ""
+
+
+def values(text: str) -> List[str]:
+    """The changing values in `text`, as shown ("$14.15", "A-1042")."""
+    t = " ".join((text or "").split())
+    return [t[s:e] for s, e, _ in parts(t)]
+
+
+_DATE_FORMATS = (("%Y-%m-%d", r"\d{4}-\d{2}-\d{2}"), ("%d/%m/%Y", r"\d{2}/\d{2}/\d{4}"), ("%m/%d/%Y", r"\d{2}/\d{2}/\d{4}"), ("%d.%m.%Y", r"\d{2}\.\d{2}\.\d{4}"))
+MAX_DATE_DAYS = 3660
+
+
+def relative_date(text: str, today: Optional[date] = None) -> Optional[str]:
+    """
+    A typed date, as ``{{$date:+N:FORMAT}}`` (N days from today) when it is the whole value and reads one way only;
+    None otherwise. 03/04/2026 could be either day-first or month-first: it is left as typed.
+    """
+    t = (text or "").strip()
+    today = today or date.today()
+    hits = []
+    for fmt, rx in _DATE_FORMATS:
+        if not re.fullmatch(rx, t):
+            continue
+        try:
+            hits.append((fmt, datetime.strptime(t, fmt).date()))
+        except ValueError:
+            continue
+    if len({d for _, d in hits}) != 1:
+        return None
+    fmt, d = hits[0]
+    days = (d - today).days
+    if abs(days) > MAX_DATE_DAYS:
+        return None
+    return "{{$date:%s%d:%s}}" % ("+" if days >= 0 else "-", abs(days), fmt)
+
+
+def date_from(template: str, today: Optional[date] = None) -> str:
+    """The date a ``{{$date:+N:FORMAT}}`` stands for today (for tests of this module and the replay's own)."""
+    m = re.fullmatch(r"\{\{\$date:([+-])(\d+):([^}]+)\}\}", template)
+    if not m:
+        return template
+    d = (today or date.today()) + timedelta(days=int(m.group(2)) * (1 if m.group(1) == "+" else -1))
+    return d.strftime(m.group(3))