@skyramp/mcp 0.4.1 → 0.4.2-rc.2

package/build/prompts/enhance-assertions/uiAssertionsPrompt.js

@@ -1,388 +0,0 @@
-import { getPersonaPrefix } from "../personas.js";
-import { maintenanceTaskSuffix, renderRule, } from "./sharedAssertionRules.js";
-const UI_ASSERTION_CATEGORIES = [
-    {
-        name: "Critical UI Assertions",
-        rules: [
-            {
-                title: "Exercise the changed interaction (dynamic behavior)",
-                description: "When the PR introduces or changes interactive behavior (toggle, theme switch, expand/collapse, dialog open/close, focus management, optimistic update), the test MUST perform the triggering action and assert BOTH the state before AND after the action — not only the default or resting state. WHY: the PR's change IS the transition; a test that asserts only the initial/resting state would still pass even if the interaction were completely broken, so it gives zero coverage of what changed. If the test asserts only the resting state, add the action that triggers the change and assert the resulting transition — never mark this not applicable merely because the generated test lacks an action.",
-                subPoints: [
-                    "Toggle / switch: click the control and assert the observable flips (e.g. data-theme 'light' -> 'dark'), then click again and assert it reverses.",
-                    "Dialog / modal: open it and assert focus moves into the dialog; close via ESC or Cancel and assert focus returns to the trigger.",
-                    "The after-state must differ from the before-state — a single assertion of the unchanged default value does not verify the change.",
-                ],
-                examples: [
-                    {
-                        language: "javascript",
-                        code: `await expect(page.locator('html')).toHaveAttribute('data-theme', 'light');
-await page.getByTestId('theme-toggle').click();
-await expect(page.locator('html')).toHaveAttribute('data-theme', 'dark');`,
-                    },
-                    {
-                        // Python (playwright-python) — same before/after transition pattern
-                        language: "python",
-                        code: `trigger = page.get_by_test_id('delete-recipe')
-trigger.click()
-expect(page.get_by_role('dialog')).to_be_focused()
-page.keyboard.press('Escape')
-# focus returns to the trigger
-expect(trigger).to_be_focused()`,
-                    },
-                ],
-            },
-            {
-                title: "Selector constraints",
-                description: "Every assertion uses a selector already in the file. Never invent `data-testid`, role names, or classes. One exception: a `data-*` attribute + value listed in `uiContext.removedElements` (from the `skyramp_analyze_changes` output in your context) may be asserted `toBeHidden()` even though no element carries it any more — `getByTestId(value)` for `data-testid`, `page.locator('[data-cy=\"value\"]')` for any other attribute — see Removed element guard. A `-` line in the raw diff is not enough on its own: renames and moved elements also appear there.",
-                subPoints: [
-                    "No tautological assertions — locating an element by text X, then asserting it contains X.",
-                ],
-                examples: [
-                    {
-                        language: "javascript",
-                        code: `await expect(page.getByTestId('badge-count')).toHaveText('3');`,
-                    },
-                ],
-            },
-            {
-                title: "Removed element guard",
-                description: "When the PR deletes a rendered element (a `data-*` attribute + value listed in `uiContext.removedElements`) and the test visits the page that rendered it, assert `toBeHidden()` on it — `getByTestId(value)` when the attribute is `data-testid`, otherwise `page.locator('[<attribute>=\"<value>\"]')` (never `getByTestId` for `data-cy`/`data-qa`: Playwright resolves it against `data-testid` and the guard would pass vacuously). `toBeHidden` passes when the locator matches nothing or a single non-visible node (it is strict on multiple matches, like every locator assertion), which is the right contract for a removed element; do not substitute a `toBeVisible` on an unrelated element. Pair it with at least one positive assertion on a retained element of the same page so the test cannot pass on a blank or un-rendered page.",
-                subPoints: [
-                    "Anchor on the removed attribute+value or role+name, never on text or position — a text-based absence check breaks when unrelated siblings change.",
-                    "Do not add a guard for an element whose whole page or route was removed — that is maintenance of the tests that covered it, not a new assertion; a spec that opens a deleted route must be anchored on a surviving page first (a retained element asserted on a live page in the same spec) — a spec whose only visited page is the dead URL is not a valid guard.",
-                    "A renamed test id or accessible name (a removed `aria-label` included) is not a removed element: assert the element under its new identifier and never assert the retired identifier `toBeHidden()` — it passes today and turns into a false failure the day the name is reused.",
-                    "An element that exists only inside a control the page has to open — an `option` of a `select`, an item of a closed menu or dropdown — takes `toHaveCount(0)`, not `toBeHidden()`. A closed control's contents have no bounding box, so `toBeHidden()` passes whether the element was removed or not, and the guard stays green the day it comes back. If the spec opens the control before asserting, the element would have had a box had it survived, so assert both.",
-                    "The positive companion for that guard is counted or read, never `toBeVisible`: the same missing bounding box that makes `toBeHidden()` a false green on the removed entry makes `toBeVisible()` a false red on the one that stayed. Assert a retained sibling with `toHaveCount(1)` or `toHaveText`, or assert the control itself, which does have a box.",
-                ],
-                examples: [
-                    {
-                        language: "javascript",
-                        code: `await expect(page.getByTestId('navbar-sessionid-row')).toBeHidden();
-await expect(page.locator('[data-cy="checkout-btn"]')).toBeHidden();
-await expect(page.getByTestId('navbar-products')).toHaveText('Products');`,
-                    },
-                    {
-                        language: "python",
-                        code: `expect(page.get_by_test_id('navbar-sessionid-row')).to_be_hidden()
-expect(page.get_by_test_id('navbar-products')).to_have_text('Products')`,
-                    },
-                ],
-            },
-            {
-                title: "Page errors",
-                description: "Register `page.on('pageerror', ...)` before the first navigation and assert `expect(errors).toHaveLength(0)` at the end of the test.",
-                examples: [],
-            },
-            {
-                title: "Correct intended behavior",
-                description: "Assertions encode the expected outcome of the action, not the buggy runtime output observed in the trace.",
-                examples: [
-                    {
-                        language: "javascript",
-                        code: `await expect(page.locator('[data-testid="session-row"]')).toHaveCount(3);`,
-                    },
-                ],
-            },
-            {
-                title: "Tests target the changed behavior introduced by the pull request",
-                description: "Every test needs at least one assertion that fails when the behaviour it claims is broken. This is the rule the others support: a test that satisfies every rule below and still does not distinguish the behaviour working from the behaviour broken has not been enhanced. Target it on populated or updated state, not only on empty or zero state, and assert it on the page where the behaviour shows. When the PR changed the behaviour, the expected value is the one the diff, the PR description, or the referenced spec establishes — even when the running app still renders the old value; the test is expected to fail until the code is fixed.",
-                examples: [],
-            },
-            {
-                title: "Collection / repeated UI elements",
-                description: "For every collection page or selector matching multiple rendered nodes (items, rows, cards, badges, tabs, chips, definition rows, nav items), assert the exact count plus per-item content.",
-                subPoints: [
-                    "Use `toHaveCount(N)` where N comes from the trace array length or rendered DOM (`0` for empty state).",
-                    "Add at least one concrete per-item content assertion (`toHaveText`, `toHaveValue`, `toHaveAttribute`).",
-                    "Empty trace → `toHaveCount(0)` paired with the empty-state text.",
-                ],
-                examples: [
-                    {
-                        language: "javascript",
-                        code: `await expect(page.getByRole('row')).toHaveCount(2);
-await expect(page.getByRole('cell', { name: 'admin@example.com' })).toHaveText('admin@example.com');`,
-                    },
-                    {
-                        language: "javascript",
-                        code: `await expect(page.getByTestId('notification-badge')).toHaveText('3');
-await expect(page.getByTestId('notification-row')).toHaveCount(3);`,
-                    },
-                    {
-                        language: "javascript",
-                        code: `await expect(page.getByTestId('definition-row')).toHaveCount(3);
-await expect(page.getByTestId('definition-row').nth(0)).toHaveText('Version 10.2.1');`,
-                    },
-                ],
-            },
-            {
-                title: "Positive-path companion",
-                description: "Negative-only checks and URL-only routing tests must include at least one positive rendered-element assertion such as a heading, breadcrumb, title, link, count, or exact text.",
-                examples: [
-                    {
-                        language: "javascript",
-                        code: `await expect(page).toHaveURL(/\\/users/);
-await expect(page.getByRole('heading')).toHaveText('User Directory');`,
-                    },
-                ],
-            },
-            {
-                title: "Captured network responses",
-                description: "For every `page.waitForResponse`, `page.on`, or `page.route`, assert at least one status, body, or header field. Body values used downstream must also appear as visible UI text.",
-                examples: [
-                    {
-                        language: "javascript",
-                        code: `const loginResp = await page.waitForResponse('**/login');
-expect(loginResp.status()).toBe(200);
-expect((await loginResp.json()).user.email).toBe('admin@example.com');`,
-                    },
-                ],
-            },
-        ],
-    },
-    {
-        name: "Computed Values",
-        rules: [
-            {
-                title: "Exact rendered values",
-                description: "When the exact text, value, or attribute is knowable from the trace or source, use `toHaveText`, `toHaveValue`, or `toHaveAttribute` — never `toBeVisible` or `toContainText`.",
-                subPoints: [
-                    "Definition / info pages: assert the actual displayed values (version, count, date), not just the static label text.",
-                    "Images: assert `toHaveAttribute('src', ...)` with the exact src — never visibility alone.",
-                ],
-                examples: [
-                    {
-                        language: "javascript",
-                        code: `await expect(page.getByTestId('status')).toHaveText('Active');`,
-                    },
-                    {
-                        language: "javascript",
-                        code: `await expect(page.getByTestId('product-image')).toHaveAttribute('src', /expected-pattern/);`,
-                    },
-                ],
-            },
-        ],
-    },
-    {
-        name: "Post-edit State",
-        description: "Apply only when the test contains a state-changing action. Otherwise mark NOT APPLICABLE.",
-        rules: [
-            {
-                title: "Post-action visible state",
-                description: "After a state-changing action (form fill+submit, save / delete / create / toggle, checkbox click, hover / mouseout, refresh, reload, JS update, form edit), assert the visible updated outcome via `toHaveText`, `toHaveValue`, `toHaveAttribute`, or `toBeChecked`. The displayed values must reflect the edit.",
-                subPoints: [
-                    "Toggle / checkbox renames: assert the new label or state, not `toBeVisible` on the renamed element.",
-                    "Hover / mouseout: assert the overlay or state visible / hidden after the event.",
-                    "List edit: when the test submits N items, assert exactly N rows. When the count is unknown before the action, read it before and assert the delta after.",
-                ],
-                examples: [
-                    {
-                        language: "javascript",
-                        code: `await expect(page.getByTestId('description-checkbox')).toBeChecked();
-await expect(page.getByTestId('description-label')).toHaveText('check_box Description');`,
-                    },
-                    {
-                        language: "javascript",
-                        code: `await expect(page.getByTestId('total')).toHaveText('$19.98');`,
-                    },
-                    {
-                        language: "javascript",
-                        code: `await expect(page.getByTestId('version')).toHaveText('10.2.1');`,
-                    },
-                ],
-            },
-        ],
-    },
-];
-function renderCategories(categories) {
-    let index = 0;
-    return categories
-        .map((category) => {
-        const rendered = category.rules
-            .map((rule) => {
-            index += 1;
-            return renderRule(index, rule);
-        })
-            .join("\n\n");
-        const header = `#### ${category.name}`;
-        return category.description
-            ? `${header}\n${category.description}\n\n${rendered}`
-            : `${header}\n${rendered}`;
-    })
-        .join("\n\n");
-}
-function renderAssertionCategoriesTemplate(categories) {
-    return categories
-        .map((category) => {
-        const ruleKeys = category.rules
-            .map((rule) => `      "${rule.title}": []`)
-            .join(",\n");
-        return `    "${category.name}": {\n${ruleKeys}\n    }`;
-    })
-        .join(",\n");
-}
-export function getUIAssertionsPrompt(testFile, enhanceType) {
-    const categoryTemplate = renderAssertionCategoriesTemplate(UI_ASSERTION_CATEGORIES);
-    return `${getPersonaPrefix()}Your task is to enhance assertions for the given UI test file: \`${testFile}\`.${maintenanceTaskSuffix(enhanceType)}
-
-### What to assert
-Each test evaluates ONE behaviour — the one the recommendation it came from asked for. Assert that behaviour on the page where it shows, and the rendered values it depends on, exactly. A page the test only passes through, and an element the behaviour does not touch, need no assertion: asserting them makes the test fail for reasons the test is not about and buries what the test is for. The rules below say how to assert a value, not how many values to assert.
-
-### First Check
-If the generated test file has no \`expect()\` assertions, you MUST manually add them before anything else. Use \`import { expect } from '@skyramp/skyramp';\` — never from \`@playwright/test\`. If an existing import pulls \`expect\` from \`@playwright/test\`, move it to \`@skyramp/skyramp\` (keep \`test\` on the playwright line).
-
-### Flutter Web Check
-If the test targets a Flutter web app (detected by \`flt-semantics\`, \`flt-glass-pane\`, or \`flt-semantics-placeholder\` appearing anywhere in the test file, OR if the test file navigates to a URL that served a Flutter app during recording), you MUST add the following two blocks immediately after \`page.setDefaultTimeout(pageTimeout);\` and before the \`newSkyrampPlaywrightPage\` wrap:
-
-\`\`\`typescript
-// Flutter headless fix: patch Event.isTrusted so synthetic clicks activate Flutter semantics
-await page.context().addInitScript(() => {
-    Object.defineProperty(Event.prototype, 'isTrusted', { get: () => true, configurable: true });
-});
-\`\`\`
-
-And immediately after **every** \`page.goto()\` call in the test, add exactly these three statements — do NOT substitute a different activation approach or different \`waitForFunction\` bodies:
-
-\`\`\`typescript
-// Wait for Flutter to bootstrap (confirms Flutter engine is ready before activating)
-await page.waitForFunction(
-    () => !!document.querySelector('flt-semantics-placeholder, flt-glass-pane, flutter-view'),
-    undefined,
-    { timeout: 30000 }
-);
-// Activate Flutter accessibility semantics by clicking the hidden placeholder
-await page.evaluate(() => { const el = document.querySelector('flt-semantics-placeholder'); if (el) el.dispatchEvent(new MouseEvent('click', { isTrusted: true, bubbles: true, cancelable: true })); });
-// Wait for the semantics tree to be live: the activation placeholder is gone AND
-// at least one flt-semantics node exists. Requiring a populated tree (not just the
-// placeholder's absence) guards against a vacuous pass when the bootstrap wait
-// above resolved on flt-glass-pane/flutter-view before the placeholder ever mounted.
-await page.waitForFunction(
-    () => document.querySelector('flt-semantics-placeholder') === null
-        && document.querySelector('flt-semantics') !== null,
-    undefined,
-    { timeout: 20000 }
-);
-\`\`\`
-
-Use exactly the three statements above. Do NOT use the two-argument form \`waitForFunction(fn, { timeout })\` — the timeout must be the third argument with \`undefined\` as the second. If you see an existing body click, \`locator.click\`, or old-style \`waitForFunction\` after a goto, replace the entire block with the exact three statements above.
-
-This is required because Flutter web renders to a \`<canvas>\` element (no traditional DOM). The first \`waitForFunction\` ensures Flutter has bootstrapped before activation; the \`dispatchEvent\` activates semantics; the second \`waitForFunction\` confirms the semantics tree is live (placeholder removed **and** \`flt-semantics\` nodes present). The combined gate handles both modes — when accessibility is pre-enabled (semantics active from frame 1, no placeholder ever shown) and when activation depends on the click — without passing prematurely on a frame where neither has happened yet.
-
-**Then wait for the first element you interact with.** The gate above confirms the semantics tree *started* building, but Flutter populates it incrementally — individual widgets (a textbox, a button) can still be a beat behind when the gate passes, especially on a cold start where accessibility was not pre-enabled. The wrapped Skyramp page also enforces a short internal action timeout, so a lagging widget fails fast rather than waiting out the page default. Guard against this: immediately after the activation block (and after any later \`page.goto()\`'s block), add an explicit \`waitFor\` on the **first locator the test interacts with on that page**, before the interaction itself. Example:
-\`\`\`typescript
-// Wait for the specific target to be present before interacting (tree may still be filling in)
-await page.getByRole('textbox', { name: 'Username' }).waitFor({ state: 'visible', timeout: 20000 });
-await page.getByRole('textbox', { name: 'Username' }).fill('admin');
-\`\`\`
-Use the **same locator** that the next interaction uses — do not invent a new selector. This waits for exactly the widget the test needs, which is more reliable than any generic tree-node count (those are app-specific magic numbers); it is the per-target wait that Flutter-web automation guidance recommends over a one-size-fits-all readiness check.
-
-**Also check for brittle flt-semantic-node-* selectors:** If the test uses \`page.locator("#flt-semantic-node-N")\` for any interaction (clicks, navigations), replace it with a semantic selector (\`getByRole\`, \`getByText\`, or \`getByLabel\`) — \`flt-semantic-node-N\` IDs change between sessions and across devices, making the test brittle. Example: replace \`page.locator("#flt-semantic-node-78").click()\` with \`page.getByText("Settings").click()\` using the visible label from the same line's context.
-
-**Flutter assertion grounding rule:** For Flutter web tests, use the following priority order when adding \`expect()\` assertions:
-1. **Existing selectors in the test file** — prefer these first; they were captured from the live accessibility tree during recording.
-2. **\`browser_blueprint\` snapshot** — if a blueprint was captured, use element roles, names, and text that appear verbatim in the snapshot.
-3. **Source code / diff** — only consult source code after exhausting the above. Flutter's accessibility tree frequently omits or transforms text (e.g. CJK characters split into individual nodes, \`ExcludeSemantics\` widgets, icon-only buttons), so what appears in the Dart source may not exist in the ARIA tree at runtime. If a selector derived from source cannot be confirmed in the blueprint or recorded trace, skip the assertion rather than risk a false positive.
-
-### Idempotent Setup Check
-Apply this check when — and only when — the test body contains a create-entity sequence: a "Create X" / "New X" / "Add X" button click that opens a dialog or form, followed by filling in a name or identifier, followed by a confirm/submit action whose result subsequent steps depend on.
-
-**Why:** Multiple generated tests run sequentially against a single shared SUT instance within the same CI job. The agent's own exploration phase may also create the entity before tests execute. Whichever test runs first succeeds; all later tests collide with the already-existing entity and time out on the "Create X" button.
-
-**This is the one exception to the "do not restructure" rule.** Wrapping entity creation in an existence check does not change the test's intent — it makes it robust to pre-existing state.
-
-**How to wrap it:**
-1. Before the create sequence, check whether the entity already exists (using \`isVisible()\` on the entity's list item or link, wrapped in \`.catch(() => false)\` to avoid throwing on timeout).
-2. If it exists: navigate to it directly.
-3. If it does not exist: run the original create sequence.
-
-For the existence check, use selectors already present in the test file. If no list-item selector exists, fall back to \`getByRole('link', { name: <entityName> })\` or \`getByText(<entityName>)\` where \`<entityName>\` is the value filled into the creation form.
-
-**Example — entity located by link:**
-\`\`\`typescript
-// Before (fragile — times out if entity already exists):
-await page.getByRole('button', { name: 'Create Project' }).click();
-await page.getByPlaceholder('Project name').fill('TestProject');
-await page.getByRole('button', { name: 'Create Project' }).nth(1).click();
-
-// After (idempotent — works whether entity exists or not):
-const existingProject = page.getByRole('link', { name: 'TestProject' });
-if (await existingProject.isVisible().catch(() => false)) {
-  await existingProject.click();
-} else {
-  await page.getByRole('button', { name: 'Create Project' }).click();
-  await page.getByPlaceholder('Project name').fill('TestProject');
-  await page.getByRole('button', { name: 'Create Project' }).nth(1).click();
-}
-\`\`\`
-
-**Example — entity located by table row:**
-\`\`\`typescript
-// Before (fragile):
-await page.getByRole('button', { name: 'Add Secret' }).click();
-await page.getByLabel('Secret name').fill('API_KEY');
-await page.getByRole('button', { name: 'Save' }).click();
-
-// After (idempotent):
-const existingSecret = page.getByRole('row', { name: 'API_KEY' });
-if (await existingSecret.isVisible().catch(() => false)) {
-  await existingSecret.click();
-} else {
-  await page.getByRole('button', { name: 'Add Secret' }).click();
-  await page.getByLabel('Secret name').fill('API_KEY');
-  await page.getByRole('button', { name: 'Save' }).click();
-}
-\`\`\`
-
-### Pre-Edit Assertion Analysis
-Before editing the given test file, you must output a \`<thinking>\` block. It states the behaviour each test evaluates, then works through the rules for the items that behaviour depends on, so no rule that applies is overlooked. The JSON array should match the template below — every assertion category and every rule title under it must appear as a key, with \`[]\` where the rule does not apply.
-1. For each test in scope, name the behaviour it evaluates in one line, taken from the recommendation it came from, and name the page where that behaviour shows. Generated specs are usually named \`testUi\`, which claims nothing — use the name only when it is specific enough to add something.
-2. Selector inventory — list every selector already present in the generated test file (\`data-testid\`, role + name, text, label, etc.). New assertions may use only selectors from this list. An assertion the recorder dropped because it failed during recording may use the selector of the element named in that recording's blueprint capture. Do not invent \`data-testid\` values, role names, or aria attributes. Also note captured network responses, repeated element patterns, exact rendered text/value/attribute from trace/source, and existing \`toBeVisible()\` assertions whose exact text is knowable.
-3. Process — Replay → Identify → Fix or Add — walk through these three steps explicitly.
-   a. Replay the scenario mentally. At each state-changing action (form submit, item add/edit/delete), ask: "What is the EXPECTED outcome based on the action performed?"
-   b. Identify expectation mismatches. If the recorded trace shows a result that contradicts the action (e.g. removing 1 of 2 items but the page shows 3, submitting a form but getting a blank page, editing a field but the old value persists), that is an app bug the test should catch. List every mismatch you find.
-   c. Fix or add assertions for each mismatch.
-      - If an existing assertion uses the wrong (buggy) value, edit it to assert the correct expected value.
-      - If no assertion exists for the buggy behavior, add one immediately after the action that triggers it.
-4. Classify each in-scope action / selector / captured response by its applicable assertion category, marking each category APPLICABLE or NOT APPLICABLE.
-   - Critical UI Assertions applies when there is a collection / repeated element (\`toHaveCount\`), a pageerror handler, a captured network response, a negative-only or URL-only test needing a positive-path companion, or a tautological locator-by-text + assert-text to replace.
-   - Computed Values applies when there is a knowable exact text / value / attribute, including a definition-page displayed value or an image \`src\`.
-   - Post-edit State applies whenever EITHER (a) the test contains a state-changing action (form fill+submit, save / delete / create / toggle, checkbox click, hover / mouseout, refresh, reload, JS update, form edit), OR (b) the PR changes interactive behavior — in case (b), add the triggering action and assert the before/after transition (see "Exercise the changed interaction"). Mark NOT APPLICABLE only when the PR changes no interactive behavior and the test has no state-changing action.
-5. For each in-scope item, output one JSON object using the template below. The output is an array — repeat the object template below once per in-scope item.
-   - \`action_or_selector_or_response\`: the selector, action, or captured network response this entry covers.
-   - \`behaviour_under_test\`: the one-line behaviour from step 1 that this item is evidence for. When an item is evidence for no behaviour any test in scope claims, write \`none\` and add nothing for it.
-   - \`assertion_categories\`: an object that MUST contain every category name below as a key. The value of each category is itself an object that MUST contain every rule title under that category as a key. For each rule, the value is the assertion lines you will add for this item under that rule. \`[]\` means the rule does not apply here, which is a normal and expected answer: it is the right one whenever the rule's elements are not part of \`behaviour_under_test\`. Listing every key keeps a rule that DOES apply from being skipped; it is not a quota to fill.
-
-\`\`\`json
-[{
-  "action_or_selector_or_response": "<selector | action | response>",
-  "behaviour_under_test": "<the one-line behaviour this item is evidence for, or none>",
-  "assertion_categories": {
-${categoryTemplate}
-  }
-}]
-\`\`\`
-
-### Assertion Rules with Examples
-Most-violated patterns — whenever the behaviour under test involves one of these, this is the shape it takes. (1) repeated elements → \`toHaveCount(N)\` + per-item \`toHaveText\`/\`toHaveValue\`/\`toHaveAttribute\` (Collection / repeated UI elements). (2) post-action state → \`toHaveText\`/\`toHaveValue\`/\`toHaveAttribute\`/\`toBeChecked\`, not \`toBeVisible\` when exact value is knowable (Post-action visible state). (3) routing/URL-only tests → at least one rendered-element exact text (Positive-path companion).
-Strength order. \`toHaveCount\`/\`toHaveText\`/\`toHaveValue\`/\`toHaveAttribute\` > \`toContainText\` (only when string is genuinely dynamic) > \`toBeVisible\` (only when presence is the actual test).
-
-${renderCategories(UI_ASSERTION_CATEGORIES)}
-
-### What Not to Do
-- Do not invent selectors, values, attributes, or assertions
-- Do not use \`toBeVisible\` when exact text/value/state is knowable
-- Do not use tautological locator-by-text + assert-text
-- Do not use \`toContainText\` when the full string is known
-- Do not assert static page headings, intermediate states, or values guaranteed by the action you just took
-- Do not assert the same value with multiple selectors
-- Do not import \`expect\` from \`@playwright/test\`
-- Do not restructure, reorder, or modify existing code/imports/signatures
-- Do not add comments or docstrings
-- Do not remove or modify existing assertions
-- Do not assert buggy/error text as expected (unless the intended UX is an error state)
-
-### Verification of Assertions
-After adding the assertion lines in the given test file, re-read each test and check two things: every rule that applies to the behaviour under test has been applied correctly, and the test now fails if that behaviour breaks. Fix anything missing or weakly applied before completing. Remove any assertion you added that the behaviour does not depend on.
-
-The goal is tests that FAIL when the app has bugs, not tests that simply replay what happened.
-`;
-}

package/build/tools/runExistingTestsTool.d.ts

@@ -1,138 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { WorkspaceConfig } from "../workspace/workspace.js";
-import { ParsedExternalRun } from "../types/ExternalTestExecution.js";
-import { SUPPORTED_FRAMEWORKS } from "../workspace/frameworks.js";
-/** Test-run lifecycle resolved from a service's workspace.yml runtimeDetails. */
-export interface ResolvedRunConfig {
-    serviceName: string;
-    framework: Framework;
-    testRunCommand: string;
-    testEnv?: Record<string, string>;
-    /** Repo-relative globs this suite owns; empty/absent means it accepts any selector. */
-    pathGlobs?: string[];
-}
-type Framework = (typeof SUPPORTED_FRAMEWORKS)[number];
-/** Binds a framework to its pure parse/buildArgs pair + how its report is
- *  obtained. The generic IO shell {@link runExternalSuite} is the only place
- *  that spawns a process; adding a framework is a new ReaderSpec + registry entry. */
-interface ReaderSpec {
-    framework: Framework;
-    /** Where the machine-readable report lands: a temp file, or the process stdout. */
-    outputVia: "file" | "stdout";
-    /** Env var pointing the reporter at the temp report path (e.g. Playwright). */
-    reportEnvVar?: string;
-    buildArgs(input: {
-        selectors: string[];
-        mode: "confirm" | "verify";
-        project?: string;
-        reportPath: string;
-    }): string[];
-    parse(report: unknown, opts: {
-        truncated: boolean;
-    }): ParsedExternalRun;
-}
-/** True when a framework has an execution reader (playwright/pytest/jest/vitest/mocha). */
-export declare function frameworkHasReader(framework?: string): boolean;
-/** Extract the last complete top-level JSON object from a stdout blob that may
- *  carry interleaved non-JSON (e.g. a test's console.log before mocha's json
- *  reporter dumps its object). Scans brace depth while respecting string/escape
- *  context so braces inside strings do not miscount. Throws if none found. */
-export declare function extractLastJsonObject(s: string): string;
-export interface RunExistingTestsParams {
-    workspacePath: string;
-    service?: string;
-    testSelectors?: string[];
-    mode?: "confirm" | "verify";
-    project?: string;
-    stateFile?: string;
-    repository?: string;
-    timeoutMs?: number;
-    maxTests?: number;
-}
-export interface PlaywrightRunOpts {
-    workspacePath: string;
-    selectors: string[];
-    mode: "confirm" | "verify";
-    project?: string;
-    timeoutMs?: number;
-    truncated: boolean;
-}
-/** Injectable IO seam so the orchestration in {@link runExternalTests} is unit
- *  testable without a real workspace file or Playwright process. */
-export interface RunExistingTestsDeps {
-    readConfig: (workspacePath: string) => Promise<WorkspaceConfig>;
-    runner: (cfg: ResolvedRunConfig, opts: PlaywrightRunOpts) => Promise<ParsedExternalRun>;
-    now: () => string;
-}
-/** The routed suite list: every runnable suite to execute, plus the suites that
- *  were skipped (with a reason). A suite is runnable when its framework has a
- *  registered reader (its testRunCommand is required non-empty by the schema). */
-export interface RunConfigResolution {
-    runs: ResolvedRunConfig[];
-    skips: {
-        service: string;
-        reason: string;
-    }[];
-}
-/**
- * Resolves the runnable suites from workspace.yml (SKYR-4002). Enumerates every
- * (service, suite) via resolveSuites; a suite is runnable when its framework has
- * a registered reader (Playwright, pytest, jest, vitest, Mocha) — testRunCommand
- * is required non-empty by the schema. Suites whose framework has no reader become
- * skips-with-reason (never a throw). Every runnable suite runs. Throws only for an
- * explicitly-named unknown service.
- */
-export declare function resolveRunConfig(config: WorkspaceConfig, opts?: {
-    service?: string;
-}): RunConfigResolution;
-/** Selectors partitioned into those this suite owns and those it does not. */
-export interface SelectorRouting {
-    kept: string[];
-    dropped: string[];
-}
-/**
- * Partitions `selectors` into the ones this suite owns and the ones it does not,
- * using the suite's own `pathGlobs` from workspace.yml.
- *
- * One repo commonly hosts several runners (mocha for a core package, vitest for
- * app packages, Playwright for e2e), and handing a runner another runner's spec is
- * not a test failure — it is a loader crash that yields no report at all. Which
- * suite owns which paths is a fact about the repo, so it is recorded as config the
- * user can read and correct, rather than guessed at run time. Run 30297865488 is
- * the cautionary case: routing on a guessed framework tag sent Ghost's Playwright
- * specs away from the Playwright suite, and nothing ran.
- *
- * A suite with no globs owns everything. That is deliberate: absent globs means
- * the suite is unscoped, not that it owns nothing, and narrowing on no
- * information would silently shrink the run.
- */
-export declare function routeSelectorsToSuite(input: {
-    selectors: string[];
-    /** The suite's repo-relative globs; absent/empty means it accepts every selector. */
-    pathGlobs?: string[];
-    /** Absolute test-file paths from analyze_changes, used to canonicalize a selector. */
-    knownTestFiles?: string[];
-    workspacePath: string;
-}): SelectorRouting;
-/** Combines per-suite runs into one ParsedExternalRun for the tool's summary
- *  text: sums counts, concatenates results, ANDs environmentHealthy, joins the
- *  unhealthy details. */
-export declare function aggregateRuns(parsed: ParsedExternalRun[]): ParsedExternalRun;
-/**
- * Generic IO shell for every framework reader: append the reporter + scoped
- * selectors to the suite's `testRunCommand`, spawn it via bash (so a wrapper
- * entrypoint's `exec "$@"` receives the flags), read the machine-readable
- * report (temp file or captured stdout), and hand it to `spec.parse`. A missing
- * or unparseable report is the exit-code rung: `environmentHealthy:false` with
- * the stderr tail — never PR signal, never throws.
- */
-export declare function runExternalSuite(spec: ReaderSpec, cfg: ResolvedRunConfig, opts: PlaywrightRunOpts): Promise<ParsedExternalRun>;
-export declare function runPlaywright(cfg: ResolvedRunConfig, opts: PlaywrightRunOpts): Promise<ParsedExternalRun>;
-/**
- * Orchestrates an external test run: resolve config → apply maxTests cap → run →
- * persist a record to the state file. Pure of MCP/registration concerns and
- * fully injectable for tests.
- */
-export declare function runExternalTests(params: RunExistingTestsParams, deps?: RunExistingTestsDeps): Promise<ParsedExternalRun>;
-export declare function registerRunExistingTestsTool(server: McpServer): void;
-export {};