@skyramp/mcp 0.2.5 → 0.2.7

package/build/tools/submitReportTool.d.ts

@@ -0,0 +1,384 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { TestType, HttpMethod } from "../types/TestTypes.js";
+export declare const targetElementSchema: z.ZodObject<{
+    role: z.ZodString;
+    accessibleName: z.ZodString;
+    testId: z.ZodNullable<z.ZodString>;
+    stableId: z.ZodNullable<z.ZodString>;
+    contextText: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
+    mutability: z.ZodOptional<z.ZodEnum<["mutable", "immutable", "unknown"]>>;
+    widgetType: z.ZodOptional<z.ZodEnum<["native", "custom", "unknown"]>>;
+}, "strip", z.ZodTypeAny, {
+    role: string;
+    accessibleName: string;
+    testId: string | null;
+    stableId: string | null;
+    contextText: string[] | null;
+    mutability?: "unknown" | "mutable" | "immutable" | undefined;
+    widgetType?: "custom" | "unknown" | "native" | undefined;
+}, {
+    role: string;
+    accessibleName: string;
+    testId: string | null;
+    stableId: string | null;
+    contextText: string[] | null;
+    mutability?: "unknown" | "mutable" | "immutable" | undefined;
+    widgetType?: "custom" | "unknown" | "native" | undefined;
+}>;
+export declare const pageContextSchema: z.ZodObject<{
+    url: z.ZodString;
+    pageHash: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    pageHash?: string | undefined;
+}, {
+    url: string;
+    pageHash?: string | undefined;
+}>;
+export declare const newTestSchema: z.ZodEffects<z.ZodObject<{
+    testId: z.ZodString;
+    testType: z.ZodNativeEnum<typeof TestType>;
+    category: z.ZodEffects<z.ZodEnum<["business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"]>, "breaking_change" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud", unknown>;
+    endpoint: z.ZodString;
+    fileName: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    scenarioFile: z.ZodOptional<z.ZodString>;
+    traceFile: z.ZodOptional<z.ZodString>;
+    frontendTrace: z.ZodOptional<z.ZodString>;
+    reasoning: z.ZodString;
+    targetElements: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        role: z.ZodString;
+        accessibleName: z.ZodString;
+        testId: z.ZodNullable<z.ZodString>;
+        stableId: z.ZodNullable<z.ZodString>;
+        contextText: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
+        mutability: z.ZodOptional<z.ZodEnum<["mutable", "immutable", "unknown"]>>;
+        widgetType: z.ZodOptional<z.ZodEnum<["native", "custom", "unknown"]>>;
+    }, "strip", z.ZodTypeAny, {
+        role: string;
+        accessibleName: string;
+        testId: string | null;
+        stableId: string | null;
+        contextText: string[] | null;
+        mutability?: "unknown" | "mutable" | "immutable" | undefined;
+        widgetType?: "custom" | "unknown" | "native" | undefined;
+    }, {
+        role: string;
+        accessibleName: string;
+        testId: string | null;
+        stableId: string | null;
+        contextText: string[] | null;
+        mutability?: "unknown" | "mutable" | "immutable" | undefined;
+        widgetType?: "custom" | "unknown" | "native" | undefined;
+    }>, "many">>>;
+    pageContext: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        pageHash: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        pageHash?: string | undefined;
+    }, {
+        url: string;
+        pageHash?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    testType: TestType;
+    category: "breaking_change" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    fileName: string;
+    endpoint: string;
+    testId: string;
+    reasoning: string;
+    description?: string | undefined;
+    traceFile?: string | undefined;
+    scenarioFile?: string | undefined;
+    frontendTrace?: string | undefined;
+    targetElements?: {
+        role: string;
+        accessibleName: string;
+        testId: string | null;
+        stableId: string | null;
+        contextText: string[] | null;
+        mutability?: "unknown" | "mutable" | "immutable" | undefined;
+        widgetType?: "custom" | "unknown" | "native" | undefined;
+    }[] | null | undefined;
+    pageContext?: {
+        url: string;
+        pageHash?: string | undefined;
+    } | undefined;
+}, {
+    testType: TestType;
+    fileName: string;
+    endpoint: string;
+    testId: string;
+    reasoning: string;
+    description?: string | undefined;
+    category?: unknown;
+    traceFile?: string | undefined;
+    scenarioFile?: string | undefined;
+    frontendTrace?: string | undefined;
+    targetElements?: {
+        role: string;
+        accessibleName: string;
+        testId: string | null;
+        stableId: string | null;
+        contextText: string[] | null;
+        mutability?: "unknown" | "mutable" | "immutable" | undefined;
+        widgetType?: "custom" | "unknown" | "native" | undefined;
+    }[] | null | undefined;
+    pageContext?: {
+        url: string;
+        pageHash?: string | undefined;
+    } | undefined;
+}>, {
+    testType: TestType;
+    category: "breaking_change" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    fileName: string;
+    endpoint: string;
+    testId: string;
+    reasoning: string;
+    description?: string | undefined;
+    traceFile?: string | undefined;
+    scenarioFile?: string | undefined;
+    frontendTrace?: string | undefined;
+    targetElements?: {
+        role: string;
+        accessibleName: string;
+        testId: string | null;
+        stableId: string | null;
+        contextText: string[] | null;
+        mutability?: "unknown" | "mutable" | "immutable" | undefined;
+        widgetType?: "custom" | "unknown" | "native" | undefined;
+    }[] | null | undefined;
+    pageContext?: {
+        url: string;
+        pageHash?: string | undefined;
+    } | undefined;
+}, {
+    testType: TestType;
+    fileName: string;
+    endpoint: string;
+    testId: string;
+    reasoning: string;
+    description?: string | undefined;
+    category?: unknown;
+    traceFile?: string | undefined;
+    scenarioFile?: string | undefined;
+    frontendTrace?: string | undefined;
+    targetElements?: {
+        role: string;
+        accessibleName: string;
+        testId: string | null;
+        stableId: string | null;
+        contextText: string[] | null;
+        mutability?: "unknown" | "mutable" | "immutable" | undefined;
+        widgetType?: "custom" | "unknown" | "native" | undefined;
+    }[] | null | undefined;
+    pageContext?: {
+        url: string;
+        pageHash?: string | undefined;
+    } | undefined;
+}>;
+export declare const additionalRecommendationSchema: z.ZodEffects<z.ZodObject<{
+    testId: z.ZodString;
+    testType: z.ZodNativeEnum<typeof TestType>;
+    category: z.ZodEffects<z.ZodEnum<["business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"]>, "breaking_change" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud", unknown>;
+    primaryEndpoint: z.ZodOptional<z.ZodString>;
+    scenarioName: z.ZodOptional<z.ZodString>;
+    steps: z.ZodArray<z.ZodObject<{
+        method: z.ZodOptional<z.ZodNativeEnum<typeof HttpMethod>>;
+        path: z.ZodOptional<z.ZodString>;
+        description: z.ZodString;
+        expectedStatusCode: z.ZodOptional<z.ZodNumber>;
+        requestBody: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        responseBody: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        path?: string | undefined;
+        method?: HttpMethod | undefined;
+        requestBody?: Record<string, any> | undefined;
+        responseBody?: Record<string, any> | undefined;
+        expectedStatusCode?: number | undefined;
+    }, {
+        description: string;
+        path?: string | undefined;
+        method?: HttpMethod | undefined;
+        requestBody?: Record<string, any> | undefined;
+        responseBody?: Record<string, any> | undefined;
+        expectedStatusCode?: number | undefined;
+    }>, "many">;
+    description: z.ZodString;
+    priority: z.ZodEffects<z.ZodEnum<["high", "medium", "low"]>, "high" | "medium" | "low", unknown>;
+    openApiSpec: z.ZodOptional<z.ZodString>;
+    backendTrace: z.ZodOptional<z.ZodString>;
+    frontendTrace: z.ZodOptional<z.ZodString>;
+    reasoning: z.ZodString;
+    targetElements: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        role: z.ZodString;
+        accessibleName: z.ZodString;
+        testId: z.ZodNullable<z.ZodString>;
+        stableId: z.ZodNullable<z.ZodString>;
+        contextText: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
+        mutability: z.ZodOptional<z.ZodEnum<["mutable", "immutable", "unknown"]>>;
+        widgetType: z.ZodOptional<z.ZodEnum<["native", "custom", "unknown"]>>;
+    }, "strip", z.ZodTypeAny, {
+        role: string;
+        accessibleName: string;
+        testId: string | null;
+        stableId: string | null;
+        contextText: string[] | null;
+        mutability?: "unknown" | "mutable" | "immutable" | undefined;
+        widgetType?: "custom" | "unknown" | "native" | undefined;
+    }, {
+        role: string;
+        accessibleName: string;
+        testId: string | null;
+        stableId: string | null;
+        contextText: string[] | null;
+        mutability?: "unknown" | "mutable" | "immutable" | undefined;
+        widgetType?: "custom" | "unknown" | "native" | undefined;
+    }>, "many">>>;
+    pageContext: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        pageHash: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        pageHash?: string | undefined;
+    }, {
+        url: string;
+        pageHash?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    priority: "high" | "medium" | "low";
+    testType: TestType;
+    category: "breaking_change" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    steps: {
+        description: string;
+        path?: string | undefined;
+        method?: HttpMethod | undefined;
+        requestBody?: Record<string, any> | undefined;
+        responseBody?: Record<string, any> | undefined;
+        expectedStatusCode?: number | undefined;
+    }[];
+    testId: string;
+    reasoning: string;
+    scenarioName?: string | undefined;
+    frontendTrace?: string | undefined;
+    targetElements?: {
+        role: string;
+        accessibleName: string;
+        testId: string | null;
+        stableId: string | null;
+        contextText: string[] | null;
+        mutability?: "unknown" | "mutable" | "immutable" | undefined;
+        widgetType?: "custom" | "unknown" | "native" | undefined;
+    }[] | null | undefined;
+    pageContext?: {
+        url: string;
+        pageHash?: string | undefined;
+    } | undefined;
+    primaryEndpoint?: string | undefined;
+    openApiSpec?: string | undefined;
+    backendTrace?: string | undefined;
+}, {
+    description: string;
+    testType: TestType;
+    steps: {
+        description: string;
+        path?: string | undefined;
+        method?: HttpMethod | undefined;
+        requestBody?: Record<string, any> | undefined;
+        responseBody?: Record<string, any> | undefined;
+        expectedStatusCode?: number | undefined;
+    }[];
+    testId: string;
+    reasoning: string;
+    priority?: unknown;
+    scenarioName?: string | undefined;
+    category?: unknown;
+    frontendTrace?: string | undefined;
+    targetElements?: {
+        role: string;
+        accessibleName: string;
+        testId: string | null;
+        stableId: string | null;
+        contextText: string[] | null;
+        mutability?: "unknown" | "mutable" | "immutable" | undefined;
+        widgetType?: "custom" | "unknown" | "native" | undefined;
+    }[] | null | undefined;
+    pageContext?: {
+        url: string;
+        pageHash?: string | undefined;
+    } | undefined;
+    primaryEndpoint?: string | undefined;
+    openApiSpec?: string | undefined;
+    backendTrace?: string | undefined;
+}>, {
+    description: string;
+    priority: "high" | "medium" | "low";
+    testType: TestType;
+    category: "breaking_change" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    steps: {
+        description: string;
+        path?: string | undefined;
+        method?: HttpMethod | undefined;
+        requestBody?: Record<string, any> | undefined;
+        responseBody?: Record<string, any> | undefined;
+        expectedStatusCode?: number | undefined;
+    }[];
+    testId: string;
+    reasoning: string;
+    scenarioName?: string | undefined;
+    frontendTrace?: string | undefined;
+    targetElements?: {
+        role: string;
+        accessibleName: string;
+        testId: string | null;
+        stableId: string | null;
+        contextText: string[] | null;
+        mutability?: "unknown" | "mutable" | "immutable" | undefined;
+        widgetType?: "custom" | "unknown" | "native" | undefined;
+    }[] | null | undefined;
+    pageContext?: {
+        url: string;
+        pageHash?: string | undefined;
+    } | undefined;
+    primaryEndpoint?: string | undefined;
+    openApiSpec?: string | undefined;
+    backendTrace?: string | undefined;
+}, {
+    description: string;
+    testType: TestType;
+    steps: {
+        description: string;
+        path?: string | undefined;
+        method?: HttpMethod | undefined;
+        requestBody?: Record<string, any> | undefined;
+        responseBody?: Record<string, any> | undefined;
+        expectedStatusCode?: number | undefined;
+    }[];
+    testId: string;
+    reasoning: string;
+    priority?: unknown;
+    scenarioName?: string | undefined;
+    category?: unknown;
+    frontendTrace?: string | undefined;
+    targetElements?: {
+        role: string;
+        accessibleName: string;
+        testId: string | null;
+        stableId: string | null;
+        contextText: string[] | null;
+        mutability?: "unknown" | "mutable" | "immutable" | undefined;
+        widgetType?: "custom" | "unknown" | "native" | undefined;
+    }[] | null | undefined;
+    pageContext?: {
+        url: string;
+        pageHash?: string | undefined;
+    } | undefined;
+    primaryEndpoint?: string | undefined;
+    openApiSpec?: string | undefined;
+    backendTrace?: string | undefined;
+}>;
+export declare function registerSubmitReportTool(server: McpServer): void;

package/build/tools/submitReportTool.js

@@ -22,11 +22,35 @@ const testResultSchema = z.object({
     status: z.enum(["Pass", "Fail", "Skipped"]).describe("Test execution result"),
     details: z.string().describe("One sentence — no embedded newlines, no markdown. e.g. '10.8s, products_contract_test.py' or 'failed: <one-line error summary>, products_contract_test.py'"),
 });
+// Structured grounding for UI recommendations. Lifted verbatim from a
+// `browser_blueprint` element captured during this run. Source of truth for
+// codegen (prefers testId > stableId > role+name for locator selection),
+// the verifier (cross-checks each field against captured blueprints), and
+// any future tooling that wants reliable grounding data without prose
+// parsing. `reasoning` is free-form prose constrained by the Blueprint
+// Citation Invariant — every element cited must appear in `targetElements`.
+// See testbot prompt step 4 for the full populate-and-render rules.
+export const targetElementSchema = z.object({
+    role: z.string().describe("ARIA role (e.g. 'button', 'heading', 'textbox', 'link'). Lifted verbatim from the captured blueprint element's `role` field."),
+    accessibleName: z.string().describe("Computed accessible name (e.g. 'Save changes', 'Order Details'). Lifted verbatim from the captured blueprint element's `accessibleName` field. Must match the bolded name in `reasoning` character-for-character."),
+    testId: z.string().nullable().describe("data-testid attribute value (preferred locator handle), or null when the element has no data-testid. Lifted from the blueprint element's `testId`."),
+    stableId: z.string().nullable().describe("Unique HTML id attribute value (fallback locator when no testId), or null. Lifted from the blueprint element's `stableId`."),
+    contextText: z.array(z.string()).nullable().describe("Disambiguating row text for elements inside repeating sections (table rows, list items): the row's surrounding non-interactive text. Lifted from the blueprint repeatingElement's items[].contextText. null for non-repeating elements."),
+    mutability: z.enum(["mutable", "immutable", "unknown"]).optional().describe("Whether the element's content/state is expected to change between captures. 'mutable' elements are behavioral-test targets; 'immutable' are smoke-test targets. Copied from the blueprint element's `mutability`."),
+    widgetType: z.enum(["native", "custom", "unknown"]).optional().describe("'native' = HTML built-ins (button, input). 'custom' or 'unknown' = non-standard composites; fall back to snapshot-driven trial clicks for interaction. Copied from the blueprint element's `widgetType`."),
+});
+// Page metadata for a UI recommendation. Lifted from the BlueprintCapture
+// the agent used to populate `targetElements`. Codegen reads `url` to drive
+// page.goto(); the verifier uses `pageHash` to detect stale captures.
+export const pageContextSchema = z.object({
+    url: z.string().describe("URL of the page where the test runs. Lifted from BlueprintCapture.url."),
+    pageHash: z.string().optional().describe("Opaque hash of the captured page state (BlueprintCapture.pageHash). Lets the verifier confirm the recommendation was grounded in a still-current capture."),
+});
 // TODO: Unify newTestSchema and additionalRecommendationSchema into a single
 // interface that adds an `implemented: boolean` field. Both describe the same
 // concept (a test recommendation) — the only difference is whether it was
 // generated in this run or left for later. Tracked per Archit's review comment.
-const newTestSchema = z.object({
+export const newTestSchema = z.object({
     testId: z.string().describe("Human-readable kebab-case identifier, e.g. 'contract-get-products' or 'integration-users-orders-workflow'. Format: '<testType>-<method>-<resource>' for single-endpoint tests or '<testType>-<scenario-slug>' for multi-step tests. Must be unique within the report."),
     testType: z.nativeEnum(TestType).describe("Type of test created. Do not include priority or other metadata in this field."),
     category: z.preprocess((val) => externalCategory(val), z.enum(TEST_CATEGORIES)).describe("Test category — critical categories (security_boundary, business_rule, data_integrity, breaking_change) get generation priority over workflow"),
@@ -37,6 +61,71 @@ const newTestSchema = z.object({
     traceFile: z.string().optional().describe("Path to the backend trace file if used or created"),
     frontendTrace: z.string().optional().describe("Path to the Playwright/UI trace file if used or created"),
     reasoning: z.string().describe("Why this test was created: what production risk it mitigates, what code pattern it targets, or what coverage gap it fills"),
+    targetElements: z.array(targetElementSchema).min(1).nullable().optional().describe("UI tests only: structured grounding for one or more elements the test targets. Most tests target a single element (array length 1); render-state and multi-step UI tests target several (array length 2+). Each entry must be lifted verbatim from a captured blueprint element. Set to null when blueprint capture failed (also requires '[no-blueprint-data]' marker in BOTH description and reasoning). See Blueprint Citation Invariant in testbot prompt."),
+    pageContext: pageContextSchema.optional().describe("UI tests only: page metadata for the test. Lifted from the BlueprintCapture used during grounding."),
+}).superRefine((rec, ctx) => {
+    // targetElements / pageContext are UI-only.
+    if (rec.testType !== TestType.UI) {
+        for (const field of ["targetElements", "pageContext"]) {
+            if (rec[field] !== undefined) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [field],
+                    message: `${field} is only valid for testType: 'ui'`,
+                });
+            }
+        }
+    }
+    else {
+        // description is required for UI tests (walkthrough of steps/assertions).
+        if (!rec.description) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["description"],
+                message: "description is required for testType: 'ui'.",
+            });
+        }
+        // targetElements must be present (array or null — not omitted entirely).
+        if (rec.targetElements === undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["targetElements"],
+                message: "targetElements is required for testType: 'ui'. Use null when blueprint capture failed (and add '[no-blueprint-data]' to both description and reasoning).",
+            });
+        }
+        // pageContext is required when targetElements is an array (grounded), forbidden when null.
+        if (Array.isArray(rec.targetElements) && rec.pageContext === undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["pageContext"],
+                message: "pageContext is required for testType: 'ui' when targetElements is an array.",
+            });
+        }
+        if (rec.targetElements === null && rec.pageContext !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["pageContext"],
+                message: "pageContext must be omitted when targetElements is null (no blueprint data).",
+            });
+        }
+        // When targetElements is null, both description and reasoning must carry the '[no-blueprint-data]' marker.
+        if (rec.targetElements === null) {
+            if (!rec.reasoning.includes("[no-blueprint-data]")) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["reasoning"],
+                    message: "reasoning must contain '[no-blueprint-data]' when targetElements is null.",
+                });
+            }
+            if (rec.description && !rec.description.includes("[no-blueprint-data]")) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["description"],
+                    message: "description must contain '[no-blueprint-data]' when targetElements is null.",
+                });
+            }
+        }
+    }
 });
 const descriptionSchema = z.object({
     description: z.string().describe("One-line description. Do NOT prefix with the severity level — severity is a separate field. Include code logic bugs from the diff, test generation/execution failures, and environment misconfiguration."),
@@ -63,12 +152,14 @@ export const additionalRecommendationSchema = z.object({
     scenarioName: z.string().optional().describe("Proposed scenario name for future generation, e.g. 'products-orders-workflow'. No file exists yet — this is a suggestion only. Omit if not applicable."),
     // TODO: replace text with max(3) and check for regression
     steps: z.array(scenarioStepSchema).describe("Ordered sequence of API/UI steps in this test scenario (at most 3). Each step must include method and path so the endpoints are explicit. Omit requestBody and responseBody from steps."),
-    description: z.string().describe("What this test does and why it is valuable. For multi-step scenarios, list the endpoints involved (e.g. 'POST /api/v1/products → POST /api/v1/orders → PATCH /api/v1/orders/{id}') so the recommendation is actionable without primaryEndpoint."),
+    description: z.string().describe("Walkthrough of what the test does — the steps and assertions. For multi-step scenarios, list the endpoints involved. The 'why it is valuable' belongs in reasoning."),
     priority: z.preprocess((val) => (typeof val === "string" ? val.toLowerCase() : val), z.enum(["high", "medium", "low"])).describe("Priority level: high, medium, or low. First check diff relevance — does the test target an endpoint changed in this PR? HIGH: diff-relevant security/auth/error tests, cross-resource isolation for diff endpoints, CRUD lifecycle for NEW endpoints in the diff. MEDIUM: diff-relevant business-rule happy paths, multi-resource workflows involving diff endpoints, security/error tests for NON-diff endpoints. LOW: tests targeting only unchanged endpoints, trivially discoverable happy paths duplicating generated tests."),
     openApiSpec: z.string().optional().describe("Path to OpenAPI/Swagger spec file if available, e.g. 'openapi.yaml'"),
     backendTrace: z.string().optional().describe("Path to backend trace file if available, e.g. 'tests/skyramp-traces.json'. Used by integration and E2E tests."),
     frontendTrace: z.string().optional().describe("Path to Playwright/UI trace file if available, e.g. 'tests/skyramp-playwright.zip'. UI tests need this; E2E tests need both frontend and backend traces."),
     reasoning: z.string().describe("Why this test is recommended: the specific production risk, business rule, or security boundary it would validate"),
+    targetElements: z.array(targetElementSchema).min(1).nullable().optional().describe("UI tests only: structured grounding for one or more elements the test targets. Most tests target a single element (array length 1); render-state and multi-step UI tests target several (array length 2+). Each entry must be lifted verbatim from a captured blueprint element. Set to null when blueprint capture failed (also requires '[no-blueprint-data]' marker in BOTH description and reasoning). See Blueprint Citation Invariant in testbot prompt."),
+    pageContext: pageContextSchema.optional().describe("UI tests only: page metadata for the test. Lifted from the BlueprintCapture used during grounding."),
 }).superRefine((rec, ctx) => {
     if (rec.testType === TestType.CONTRACT && !rec.primaryEndpoint) {
         ctx.addIssue({
@@ -77,6 +168,57 @@ export const additionalRecommendationSchema = z.object({
             message: "primaryEndpoint is required for contract tests — provide the HTTP verb and path, e.g. 'PATCH /api/v1/orders/{order_id}'.",
         });
     }
+    // targetElements / pageContext are UI-only.
+    if (rec.testType !== TestType.UI) {
+        for (const field of ["targetElements", "pageContext"]) {
+            if (rec[field] !== undefined) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [field],
+                    message: `${field} is only valid for testType: 'ui'`,
+                });
+            }
+        }
+    }
+    else {
+        if (rec.targetElements === undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["targetElements"],
+                message: "targetElements is required for testType: 'ui'. Use null when blueprint capture failed (and add '[no-blueprint-data]' to both description and reasoning).",
+            });
+        }
+        if (Array.isArray(rec.targetElements) && rec.pageContext === undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["pageContext"],
+                message: "pageContext is required for testType: 'ui' when targetElements is an array.",
+            });
+        }
+        if (rec.targetElements === null && rec.pageContext !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["pageContext"],
+                message: "pageContext must be omitted when targetElements is null (no blueprint data).",
+            });
+        }
+        if (rec.targetElements === null) {
+            if (!rec.reasoning.includes("[no-blueprint-data]")) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["reasoning"],
+                    message: "reasoning must contain '[no-blueprint-data]' when targetElements is null.",
+                });
+            }
+            if (!rec.description.includes("[no-blueprint-data]")) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["description"],
+                    message: "description must contain '[no-blueprint-data]' when targetElements is null.",
+                });
+            }
+        }
+    }
 });
 const testMaintenanceSchema = z.object({
     testType: z.nativeEnum(TestType).describe("Type of test."),

package/build/tools/submitReportTool.test.d.ts

@@ -0,0 +1 @@
+export {};