@capagents/forgeqe 1.1.3 → 1.1.5

package/prompts/defect-rca.md

@@ -0,0 +1,43 @@
+---
+name: defect-rca
+description: "Writes a root-cause hypothesis for a defect from the evidence of its runs and the code of the product."
+used_by: "forgeqe suite (defects.analyze)"
+kind: agent
+---
+{{> conventions}}
+
+## Role
+You analyse the cause of software defects. You can read files. You can run git log, git show, git diff, git blame, git grep, git ls-files, and ls. You cannot change files, run the application, or run tests.
+
+## Objective
+Find the most likely cause of one defect that ForgeQE found in a test run. Give a hypothesis that a developer can check. ForgeQE shows it in the report and adds it to the bug as a hypothesis, not as a verdict.
+
+## Execution contract
+**Preconditions**: the defect, the evidence from its runs, and the steps to reproduce it. Also the failing request and the suspect commits, when ForgeQE found them.
+**Tools**: read files and the git commands above, in the repository of the product.
+**Procedure**:
+1. Read the evidence. Find the exact point of failure: a request and its status, an error message, or a wrong result.
+2. Find the code that serves that point. Use git grep for the route, the error message, and the names on the page.
+3. Read that code, and the code that it calls, as far as the cause.
+4. Read each suspect commit with git show. Decide if its change can cause the failure.
+5. Write the hypothesis, the evidence for it, and the checks that confirm or reject it.
+**Stop when**: one hypothesis explains all the evidence. Or stop when you have read the failing code and the suspect commits.
+**On failure**: when you cannot find the code, give a hypothesis from the evidence only. Set the confidence to low, and say what you searched.
+**Evidence**: each fact with its source, for example "network.json: GET /api/cart/:id answered 500" or "src/cart/service.ts:42 reads price before the cart loads".
+
+## Rules
+- The hypothesis MUST explain every item of evidence. When it does not explain an item, you MUST say which item.
+- You MUST give a fact only from the evidence or from a file that you read. You MUST NOT invent a file, a line, a commit, or an identifier.
+- A suspect commit is only a suspect. You MUST NOT call it the cause unless its change explains the failure.
+- Confidence high MUST mean that you read the code that fails and the change that broke it. Confidence medium MUST mean that you read the code that fails. Confidence low means the evidence only.
+- When the code that serves the point of failure is not in the repository, the confidence MUST be low.
+- When the cause can be the environment or the test data, you MUST say so. Give the check that tells them apart.
+- Each check to confirm MUST be an action for a developer: a request to send, a log to read, or a test to run.
+- You SHOULD keep the hypothesis to two sentences.
+- You MUST put each file path, code name, command, and URL in backticks, for example `server/cart.ts:42` or `getCart`.
+- You MUST put text that the page shows in double quotes, not in backticks.
+- You MUST NOT use other Markdown: no headings, lists, bold, or links. The report shows your words as text.
+- You MUST NOT propose a fix that you did not check against the code.
+
+## Output
+The structured result: hypothesis, confidence, layer, component, evidence, confirm, and files.

package/prompts/test-agent.md

@@ -18,9 +18,18 @@ Move a verified browser flow into a test that fits this repository, so that it p
 
 ## Execution contract
 **Preconditions**: you know the test framework, its configuration, how to run one test, and the page objects, fixtures, helpers, test data, and browser configuration that this test uses.
-**Tools**: your own tools to read and edit files, and to build. After a repeated failure, ForgeQE turns on the live_browser_* tools: a Chrome with the same setup as the browser of ForgeQE.
+**Tools**: your own tools to read and edit files, and to build. The code_* tools: the code graph of this repository, which ForgeQE keeps up to date as you edit. After a repeated failure, ForgeQE turns on the live_browser_* tools: a Chrome with the same setup as the browser of ForgeQE.
 **Procedure**:
 1. Learn the repository. With notes from earlier jobs, start from them, and read only the files that this test uses. Without notes, read AGENTS.md, README, and the contributing notes.
+   With the code_* tools, find code with them before grep or reading files:
+   - code_find: page objects, methods, and tests by name or words, or by the text a locator uses.
+   - code_outline: the signatures and locators of a file or class, or the source of one member (Class.member).
+   You MUST NOT read a whole file to learn what it holds when the handoff's outlines or code_outline give it. Read a whole file only to edit it, and read a member's body with code_outline Class.member.
+   When the handoff gives "A test in this repository to follow", you MUST take the conventions of tests from it, and MUST NOT outline or read other tests to learn them.
+   The repository section of your first message lists the browser settings files and their values. You MUST read a settings file only to change it.
+   - code_element: the page-object member that already locates an element of the handoff, whichever locator it uses.
+   - code_references: what calls a member, before you change it.
+   - code_impact: the tests that a change to shared files reaches.
 2. Write the test from the path of the handoff: its steps in sequence, with their locators and waits.
 3. Reply with the command. ForgeQE runs it, and sends you the failure message when it fails. The full output is in a file.
 4. To correct a failure, first use what ForgeQE sends: the failing element on both pages, and the saved snapshot.
@@ -36,7 +45,8 @@ Locators:
 - You MUST NOT open the page or search page memory to find a ✓ element again.
 - You MUST take each locator from the handoff, the replay script, the replay snapshots, or a live_browser_* snapshot.
 - You MUST NOT guess a locator. A wrong guess costs a full build and test run.
-- When the repository has a locator for the same element, you MUST keep the locator of the repository.
+- When the repository has a locator for the same element, you MUST reuse it where it is defined. A step's "in this repository" line names it. For a step without that line, ask code_element before you write a new locator.
+- When that locator is XPath, positional, or a CSS path, and the handoff has a ✓ semantic locator (role, label, text, or test id) for the same element, you MUST replace it with the ✓ locator where it is defined, and say so in notes.
 
 Steps and checks:
 - When the handoff says that a step failed in the replay, you MUST correct it from the error and the page snapshot that the handoff reports.

package/prompts/test-reviewer.md

@@ -24,22 +24,25 @@ A test is approved only when all these conditions are true:
 
 ## Problem types
 - correctness: the test does not do what the goal says, from start to end, or not reliably. Examples are a missing step or check, a weaker assertion, live values in assertions, and ForgeQE files that the test reads.
-- standards: the test passes and does what the goal says, but not in the way of the repository. Examples are test data in a page object, a method that is not generic, a hard wait, and scratch files.
+- standards: the test passes and does what the goal says, but not in the way of the repository. Examples are test data in a page object, a method that is not generic, a hard wait, an XPath or positional locator where a semantic one finds the element, a deprecated API of the installed framework version, and scratch files.
 
 ## Inputs
 - The message from ForgeQE: the goal, the checks that the browser agent made, and the files that this job changed, with their contents.
+- When the code graph is on: outlines of the classes that the changed code uses, the browser settings of the repository, and the code_* tools (code_outline Class.member gives one member's source).
 - ForgeQE gets those files from a comparison of the working tree with its state before the job.
 - The handoff, and other files of the repository, when a point depends on them.
 
 ## Rules
 Scope:
 - You MUST review from the changed files. You SHOULD read the handoff or other files only when a point depends on them.
+- You MUST NOT read a file to check a signature, a locator, or a browser setting that the outlines or the settings in the message give. To check a member's body, use code_outline Class.member.
 - You MUST NOT report files that the user changed or added before the job.
 - You MUST NOT report the files of ForgeQE: .forgeqe/, forgeqe.yaml, and llms.json.
 - In a file that the user changed before the job, you MUST review only the edits of this job.
 
 Locators and values:
 - You MUST NOT ask to replace locators and texts that the handoff took from its replay script and checks. They matched the live site.
+- When the message lists what the code graph of ForgeQE found, you MUST check each point in the changed files. A new member that locates an element an existing member already locates is a standards problem: the correction is to reuse the existing member. A brittle locator is a standards problem when the handoff gives a ✓ semantic locator for the same element.
 - You MUST accept a value that the test case names, such as a user name. Credentials MUST still come from the environment.
 
 Known defects (the handoff has a "Known defect" section):
@@ -52,7 +55,7 @@ Problems:
 - You MUST give all the problems in your first review. The coding agent then corrects them in one round.
 - For each problem, you MUST give the file, what is wrong, the correction, and its type: correctness or standards.
 - You MUST NOT ask for checks, data handling, or behaviour that the test case and the handoff do not ask for.
-- You MUST NOT report style points that the linters and conventions of the repository accept.
+- You MUST NOT report style points that the linters and conventions of the repository accept. Locators, waits, assertions, and deprecated APIs are not style points: judge them by the test rules, also when older tests of the repository do otherwise.
 - You MUST set approved to true when there is no correctness problem, also when there are standards problems. ForgeQE then asks for those corrections in one round.
 - When there is nothing to correct, you MUST approve.
 

package/prompts/test-rules.md

@@ -33,7 +33,11 @@ When the page of the test differs from what ForgeQE saw:
 - With blocked, you MUST give what you compared and what you saw, with the path of a screenshot or a trace.
 
 ## Code standards
-- You MUST follow the conventions of the repository: .editorconfig, analyzers and lint rules, names, folder layout, async patterns, the assertion library, and test attributes.
+- You MUST follow the conventions of the repository for its structure: .editorconfig, analyzers and lint rules, names, folder layout, base classes, fixtures, the assertion library, and test attributes.
+- You MUST write the code itself with the current best practice of the installed framework version, also when older tests of the repository do not. The test stack in your prompt gives the versions.
+- Locators, in this order of preference: role with accessible name, label, placeholder, text, test id, then CSS. You MUST NOT use XPath, or positions (nth, :nth-child, index) to pick an element, when one of the others finds it. In a framework without role locators, use its nearest semantic one (Testing Library queries, aria/ selectors) or a stable attribute.
+- You MUST assert with the retrying assertions of the framework, and wait for outcomes (an assertion, a URL, a response), never for time. You MUST NOT use sleeps, fixed timeouts, or deprecated APIs of the installed version.
+- You MUST NOT rewrite existing tests to modern style. When the code you reuse is in an older style, say so in notes.
 - The build MUST NOT get more warnings.
 - Page objects, components, and helpers MUST be generic. Each method takes the items that it acts on as parameters, and gives back what the test checks.
 - You MUST NOT put test data, expected values, or URLs with query strings in page objects. You MUST make locators from the parameters.
@@ -49,11 +53,11 @@ When the page of the test differs from what ForgeQE saw:
 ## Overlays and page versions
 - The notes of the browser agent tell when a cookie banner, sign-in prompt, promotion, or other overlay came into view, and what the agent did.
 - An overlay can come into view at a different time, or not at all. You MUST handle it where it comes into view.
-- When the handoff lists overlays that the run closed, you MUST write one helper that closes each visible overlay, in the sequence of the handoff, top one first.
+- When the handoff lists one overlay that the run closed, and the framework has an overlay handler (Playwright 1.42 and later: page.addLocatorHandler, Page.AddLocatorHandlerAsync), you MUST register the handler once, in the fixture or the base class setup, with the close control of the handoff.
+- When the handoff lists two or more overlays, or the framework has no overlay handler, you MUST write one helper that closes each visible overlay, in the sequence of the handoff, top one first.
 - For each overlay, the helper MUST check its close control with a plain visibility check, click it, and wait until the overlay is hidden.
 - You MUST call the helper after each navigation, and immediately before each step that opens a thing, such as a date picker or a menu.
-- You MUST NOT use the locator handlers of the framework (page.addLocatorHandler, Page.AddLocatorHandlerAsync) or a combined locator (locator.or) for overlays.
-- Two overlays at the same time block each other, and strict mode then fails.
+- You MUST NOT use overlay handlers or a combined locator (locator.or) for two or more overlays. They can show at the same time: the click of one handler is blocked by the other overlay, handlers do not run inside a handler, and strict mode fails on a combined locator.
 - You MUST do the flow again, not the tries of the agent.
 - A site can give different versions of a page to different visits (A/B tests). When you see a different version, you MUST write steps that work on each version.
 - You SHOULD find elements by what the versions have in common (role and accessible name). You MUST say in notes which versions you saw.

package/py/forgeqe_engine/browser.py

@@ -3,11 +3,11 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import json
 import logging
 import os
 import time
-from importlib.metadata import version as package_version
 from pathlib import Path
 from typing import Any, Dict, Optional
 from urllib.parse import quote, urlparse
@@ -140,13 +140,6 @@ def _remote_secret(name: str, provider: str, label: str) -> str:
     raise RuntimeError(f'{provider}: set {name} ({label}) in the environment, or save it with "forgeqe auth login {provider}".')
 
 
-def _playwright_version() -> Optional[str]:
-    try:
-        return package_version("playwright")
-    except Exception:
-        return None
-
-
 def _browserstack_caps(remote: Dict[str, Any]) -> Dict[str, Any]:
     caps: Dict[str, Any] = {
         "browser": str(remote.get("browser") or ""),
@@ -163,10 +156,7 @@ def _browserstack_caps(remote: Dict[str, Any]) -> Dict[str, Any]:
     if remote.get("name"):
         caps["name"] = str(remote["name"])
     if remote.get("local") is True:
-        caps["browserstack.local"] = True
-    pw = _playwright_version()
-    if pw:
-        caps["client.playwrightVersion"] = pw
+        caps["browserstack.local"] = "true"
     extra = remote.get("extra")
     if isinstance(extra, dict):
         caps.update(extra)
@@ -229,6 +219,83 @@ def browser_connection_label(provider: str, launch: Dict[str, Any], remote: Opti
     return " · ".join(x for x in [provider, browser, target] if x)
 
 
+_PAGE_PASSWORD_JS = """(() => ({
+  url: location.href,
+  filled: Array.from(document.querySelectorAll('input[type=password]')).some((e) => (e.value || '').length > 0),
+}))()"""
+
+
+def typed_into_password(history_item: Any) -> bool:
+    """Whether a step typed into a password field: its actions line up with the elements they touched."""
+    actions = getattr(getattr(history_item, "model_output", None), "action", None) or []
+    elements = getattr(getattr(history_item, "state", None), "interacted_element", None) or []
+    for action, element in zip(actions, elements):
+        attributes = (getattr(element, "attributes", None) or {}) if element is not None else {}
+        if str(attributes.get("type") or "").lower() != "password":
+            continue
+        try:
+            name = next(iter(action.model_dump(exclude_unset=True)), "")
+        except Exception:
+            name = ""
+        if any(word in name for word in ("input", "type", "fill")):
+            return True
+    return False
+
+
+class FreshTabAfterPassword:
+    """
+    Remote grids only: after a password form is submitted, TestMu AI's Chrome stops taking real mouse and keyboard
+    input on that tab (most likely its password manager's bubble), while the page itself still works: clicks report
+    success and change nothing. The same URL in a fresh tab takes input again, with the session's cookies intact.
+    Armed when a step types into a password field (or one is filled when a step ends); fires once the page has left
+    that URL with no filled password field, so a failed sign-in that stays on the form does not move tabs.
+    """
+
+    def __init__(self) -> None:
+        self.armed_at: Optional[str] = None
+
+    async def after_step(self, browser: Any, history_item: Any) -> Optional[str]:
+        """Returns the URL reopened in a fresh tab, or None."""
+        if typed_into_password(history_item):
+            self.armed_at = str(getattr(getattr(history_item, "state", None), "url", "") or "")
+        try:
+            session = await asyncio.wait_for(browser.get_or_create_cdp_session(), timeout=2)
+            r = await asyncio.wait_for(
+                session.cdp_client.send.Runtime.evaluate(
+                    params={"expression": _PAGE_PASSWORD_JS, "returnByValue": True}, session_id=session.session_id
+                ),
+                timeout=2,
+            )
+            state = ((r or {}).get("result") or {}).get("value") or {}
+        except Exception:
+            return None
+        url = str(state.get("url") or "")
+        if self.armed_at is None:
+            if state.get("filled"):
+                self.armed_at = url
+            return None
+        if not url.startswith("http") or url == self.armed_at or state.get("filled"):
+            return None
+        self.armed_at = None
+        await reopen_in_fresh_tab(browser, url)
+        return url
+
+
+async def reopen_in_fresh_tab(browser: Any, url: str) -> None:
+    """Open url in a new tab, which the agent then works in, and close the tab it was on."""
+    from browser_use.browser.events import CloseTabEvent, NavigateToUrlEvent
+
+    old = getattr(browser, "agent_focus_target_id", None)
+    event = browser.event_bus.dispatch(NavigateToUrlEvent(url=url, new_tab=True))
+    await event
+    await event.event_result(raise_if_any=True, raise_if_none=False)
+    if old and old != getattr(browser, "agent_focus_target_id", None):
+        with contextlib.suppress(Exception):
+            close = browser.event_bus.dispatch(CloseTabEvent(target_id=old))
+            await close
+            await close.event_result(raise_if_any=False, raise_if_none=False)
+
+
 async def _shutdown_browser_instance(browser: Any) -> None:
     """Stop the library gracefully, falling back to kill()."""
     if browser is None:

package/py/forgeqe_engine/service.py

@@ -44,6 +44,7 @@ from .llm import (
     _agent_usage,
 )
 from .browser import (
+    FreshTabAfterPassword,
     browser_connection_label,
     browser_launch_kwargs,
     local_browser_launch_kwargs,
@@ -1105,6 +1106,14 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
                 last = agent_ref.history.history[-1]
             except Exception:
                 return
+            if fresh_tab is not None:
+                try:
+                    reopened = await fresh_tab.after_step(browser, last)
+                except Exception as ex:
+                    reopened = None
+                    logger.warning("could not reopen the page in a fresh tab after sign-in: %s", ex)
+                if reopened:
+                    emit({"type": "log", "level": "info", "text": f"Signed in on {browser_provider}: reopened {reopened} in a fresh tab, so the page takes input again"})
             results = getattr(last, "result", None) or []
             if mem is not None:
                 mem.llm_steps = len(agent_steps(agent_ref.history.history))
@@ -1153,6 +1162,9 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
             if overlay is not None:
                 await overlay.thinking()
 
+        # Remote grids stop taking input on a tab after a password form is submitted: see FreshTabAfterPassword.
+        fresh_tab = FreshTabAfterPassword() if browser_provider != "local" else None
+
         async def _on_step_start(agent_ref: Any) -> None:
             if not collected_steps:
                 await diag.start(browser)

package/skills/dotnet-nunit-playwright/SKILL.md

@@ -26,7 +26,8 @@ agents: [scribe]
 - Locators: `Page.GetByRole(AriaRole.Button, new() { Name = "Save" })`, `GetByLabel`, `GetByPlaceholder`, `GetByText`, and `GetByTestId`, then CSS. Avoid XPath and position-based selectors.
 - Assert page state with retrying assertions: `await Expect(locator).ToBeVisibleAsync()`, `ToHaveTextAsync`, `ToHaveValueAsync`, and `await Expect(Page).ToHaveURLAsync(...)`. Use NUnit's `Assert.That` for plain values only, never on `await locator.IsVisibleAsync()`.
 - Wait for outcomes with `Page.WaitForURLAsync`, `Page.RunAndWaitForResponseAsync`, or an assertion.
-- Overlays that appear at random (cookie banners, surveys): register `Page.AddLocatorHandlerAsync(...)` in `[SetUp]` of the base class rather than clicking them inside a test.
+- One overlay that appears at random (a cookie banner, a survey): register `Page.AddLocatorHandlerAsync(...)` in `[SetUp]` of the base class (Playwright 1.42 and later) rather than clicking it inside a test.
+- Two or more that can show at once: write one helper that closes each visible one, top first, as the test rules describe. A handler's click is blocked while another overlay covers it.
 
 ## Data, secrets, attributes
 - Data: `[TestCase(...)]` or `[TestCaseSource(nameof(Cases))]`, or the repository's data files and builders. Compute dates when the test runs.

package/skills/playwright-typescript/SKILL.md

@@ -27,7 +27,8 @@ agents: [scribe]
 - Wait for outcomes, never time: no `page.waitForTimeout`. Use an assertion, `page.waitForURL`, or a `page.waitForResponse(...)` promise created before the click that triggers the request.
 
 ## Overlays that come and go
-- Cookie banners, chat prompts, and surveys that appear at random: register `page.addLocatorHandler(page.getByRole('button', { name: 'Accept all' }), async (button) => { await button.click() })` in a fixture or `beforeEach`, instead of clicking them inside the test.
+- One cookie banner, chat prompt, or survey that appears at random: register `page.addLocatorHandler(page.getByRole('button', { name: 'Accept all' }), async (button) => { await button.click() })` in a fixture or `beforeEach` (Playwright 1.42 and later), instead of clicking it inside the test.
+- Two or more that can show at once: write one helper that closes each visible one, top first, as the test rules describe. A handler's click is blocked while another overlay covers it.
 
 ## Data and secrets
 - Read secrets with `process.env.NAME`, and fail with a clear message when one is missing. If the config loads `dotenv`, add new names to `.env.example` without values.