@skyramp/mcp 0.4.1 → 0.4.2-rc.2

package/build/tools/execution-video-state.js

@@ -33,7 +33,7 @@ export async function recordExecutionVideo(result, explicitStateFile) {
             return;
         // Last write wins: a retried execution leaves a video directory per attempt,
         // and the report must reference the attempt whose status it reports.
-        await manager.writeData({
+        await manager.appendData({
             ...data,
             executionVideos: {
                 ...data.executionVideos,

package/build/tools/fixErrorTool.js

@@ -2,7 +2,6 @@ import { z } from "zod";
 import { logger } from "../utils/logger.js";
 import { getFixErrorsPrompt } from "../prompts/fix-error-prompt.js";
 import { languageSchema } from "../types/TestTypes.js";
-import { getLanguageSteps } from "../utils/language-helper.js";
 import { normalizeSkyrampImportsInFile } from "../utils/normalizeSkyrampImports.js";
 import { AnalyticsService } from "../services/AnalyticsService.js";
 const fixErrorSchema = z.object({
@@ -18,7 +17,7 @@ const fixErrorSchema = z.object({
 const TOOL_NAME = "skyramp_fix_errors";
 export function registerFixErrorTool(server) {
     server.registerTool(TOOL_NAME, {
-        description: `Review the provided code for errors, inconsistencies, or missing pieces. If any are found, return corrected code. Otherwise, return the code unchanged.`,
+        description: "Return guidance for repairing test reference, syntax, import, and missing-dependency errors while preserving the scenario, expected behavior, and assertion strength.",
         inputSchema: fixErrorSchema.shape,
         _meta: {
             keywords: [
@@ -40,9 +39,7 @@ export function registerFixErrorTool(server) {
                 content: [
                     {
                         type: "text",
-                        text: `
-            ${getFixErrorsPrompt()}
-            ${getLanguageSteps(params)}`,
+                        text: getFixErrorsPrompt(params),
                     },
                 ],
             };
@@ -64,7 +61,9 @@ export function registerFixErrorTool(server) {
             AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {
                 prompt: params.prompt,
                 testFile: params.testFile,
-            }).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
+            }).catch((err) => {
+                logger.warning("Analytics event failed", { error: String(err) });
+            });
         }
     });
 }

package/build/tools/generate-tests/batchMockGenerationTool.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { SkyrampClient } from "@skyramp/skyramp";
-import { MockProtocol, RuntimeEnvironment, runtimeEnvironmentInputSchema } from "../../types/TestTypes.js";
+import { MockProtocol, RuntimeEnvironment, runtimeEnvironmentInputSchema, } from "../../types/TestTypes.js";
 export { MockProtocol } from "../../types/TestTypes.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { logger } from "../../utils/logger.js";

package/build/tools/generate-tests/generateBatchScenarioRestTool.js

@@ -1,12 +1,12 @@
 import { TOOL_BATCH_SCENARIO_TEST_GENERATION } from "../../toolNames.js";
 import { z } from "zod";
 import path from "path";
-import { ScenarioGenerationService } from "../../services/ScenarioGenerationService.js";
+import { ScenarioGenerationService, } from "../../services/ScenarioGenerationService.js";
 import fs from "fs";
-import { baseSchema, AUTH_PLACEHOLDER_TOKEN, HttpMethod } from "../../types/TestTypes.js";
+import { baseSchema, AUTH_PLACEHOLDER_TOKEN, HttpMethod, } from "../../types/TestTypes.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
-import { resolveAuthFromWorkspace, getWorkspaceScopedQueryParams, mergeQueryParamsJson } from "../../utils/workspaceAuth.js";
-import { resolveQueryParamsForPath, ensureLeadingSlash, contributesNothing } from "../../workspace/queryParamResolution.js";
+import { resolveAuthFromWorkspace, getWorkspaceScopedQueryParams, mergeQueryParamsJson, } from "../../utils/workspaceAuth.js";
+import { resolveQueryParamsForPath, ensureLeadingSlash, contributesNothing, } from "../../workspace/queryParamResolution.js";
 import { deriveBasePath } from "../../utils/urlPath.js";
 import yaml from "js-yaml";
 import { logger } from "../../utils/logger.js";
@@ -49,25 +49,30 @@ function isJsonObject(v) {
         return false;
     }
 }
-export const stepSchema = z.object({
-    method: z
-        .nativeEnum(HttpMethod)
-        .describe("HTTP method for this step."),
+export const stepSchema = z
+    .object({
+    method: z.nativeEnum(HttpMethod).describe("HTTP method for this step."),
     path: z
         .string()
-        .startsWith("/", { message: "path must begin with '/' (e.g. '/api/v1/products/123')" })
+        .startsWith("/", {
+        message: "path must begin with '/' (e.g. '/api/v1/products/123')",
+    })
         .describe("API path for this step, must start with '/'. For steps that reference an ID from a prior step, use the same concrete value in the path (e.g. '/api/v1/orders/1') that appears in the prior step's response body (e.g. {\"id\": 1}). The backend auto-detects chaining by matching these values across steps."),
     requestBody: z
         .string()
         .optional()
-        .refine(isJsonValue, { message: "requestBody must be valid JSON (e.g. '{\"name\":\"product\"}')." })
-        .describe("JSON string of the request body parsed by AI from the scenario. "
-        + "IMPORTANT: For GET and DELETE requests, do NOT put query/filter/search parameters here — use queryParams instead. "
-        + "requestBody should only contain data sent in the HTTP body (typically for POST, PUT, PATCH)."),
+        .refine(isJsonValue, {
+        message: 'requestBody must be valid JSON (e.g. \'{"name":"product"}\').',
+    })
+        .describe("JSON string of the request body parsed by AI from the scenario. " +
+        "IMPORTANT: For GET and DELETE requests, do NOT put query/filter/search parameters here — use queryParams instead. " +
+        "requestBody should only contain data sent in the HTTP body (typically for POST, PUT, PATCH)."),
     queryParams: z
         .string()
         .optional()
-        .refine(isJsonObject, { message: "queryParams must be a JSON object string (e.g. '{\"limit\":\"10\"}')." })
+        .refine(isJsonObject, {
+        message: 'queryParams must be a JSON object string (e.g. \'{"limit":"10"}\').',
+    })
         .describe(`JSON string of URL query parameters. Provide a FLAT object where each key is the exact URL parameter name and each value is a string or number (single value per key).
 
 <examples>
@@ -89,7 +94,9 @@ Workspace-configured api.defaultQueryParams (if set) are merged into every step
     responseBody: z
         .string()
         .optional()
-        .refine(isJsonValue, { message: "responseBody must be valid JSON (e.g. '{\"id\": 1}'). The backend extracts chaining identifiers by parsing it — a malformed body silently disables chaining for every later step." })
+        .refine(isJsonValue, {
+        message: "responseBody must be valid JSON (e.g. '{\"id\": 1}'). The backend extracts chaining identifiers by parsing it — a malformed body silently disables chaining for every later step.",
+    })
         .describe("JSON string of the expected response body. For steps that produce an id used by later steps, include that id field with a realistic UUID generated fresh for this scenario — the backend chains by value-matching any subsequent step path or requestBody that contains the same UUID."),
     statusCode: z
         .number()
@@ -101,13 +108,16 @@ Workspace-configured api.defaultQueryParams (if set) are merged into every step
         .describe("Response headers as a JSON object. Defaults to Content-Type: application/json."),
     uniqueFields: z
         .array(z.string().min(1, { message: "uniqueFields paths must be non-empty" }))
-        .min(1, { message: "uniqueFields, when provided, must list at least one field path" })
+        .min(1, {
+        message: "uniqueFields, when provided, must list at least one field path",
+    })
         .optional()
-        .describe("For POST/PUT create steps: request-body field paths (gjson notation, e.g. \"name\", \"slug\", \"nested.id\") "
-        + "that carry a UNIQUE constraint in the target's data model. The generated test injects a run-unique value "
-        + "for each so re-runs don't fail with HTTP 409 'already exists'. Identify these from the source schema "
-        + "(e.g. Django unique=True, SQL UNIQUE, Pydantic/DTO). Omit for GET/DELETE steps and non-unique fields."),
-}).superRefine((step, ctx) => {
+        .describe('For POST/PUT create steps: request-body field paths (gjson notation, e.g. "name", "slug", "nested.id") ' +
+        "that carry a UNIQUE constraint in the target's data model. The generated test injects a run-unique value " +
+        "for each so re-runs don't fail with HTTP 409 'already exists'. Identify these from the source schema " +
+        "(e.g. Django unique=True, SQL UNIQUE, Pydantic/DTO). Omit for GET/DELETE steps and non-unique fields."),
+})
+    .superRefine((step, ctx) => {
     const isBodyMethod = ["POST", "PUT", "PATCH"].includes(step.method);
     // Parse once for every body-shape check below; malformed JSON is already
     // rejected by the isJsonValue refine, so an unparseable body just skips them.
@@ -126,16 +136,16 @@ Workspace-configured api.defaultQueryParams (if set) are merged into every step
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 path: ["uniqueFields"],
-                message: `uniqueFields is only valid on POST/PUT/PATCH steps (got ${step.method} ${step.path}). `
-                    + `Omit it for GET/DELETE steps.`,
+                message: `uniqueFields is only valid on POST/PUT/PATCH steps (got ${step.method} ${step.path}). ` +
+                    `Omit it for GET/DELETE steps.`,
             });
         }
         else if (!step.requestBody) {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 path: ["uniqueFields"],
-                message: `uniqueFields is set for ${step.method} ${step.path} but there is no requestBody `
-                    + `containing those fields.`,
+                message: `uniqueFields is set for ${step.method} ${step.path} but there is no requestBody ` +
+                    `containing those fields.`,
             });
         }
         else if (parsedBody !== undefined) {
@@ -144,23 +154,26 @@ Workspace-configured api.defaultQueryParams (if set) are merged into every step
                     ctx.addIssue({
                         code: z.ZodIssueCode.custom,
                         path: ["uniqueFields"],
-                        message: `uniqueFields path "${fieldPath}" does not resolve in the requestBody of `
-                            + `${step.method} ${step.path}. The generator silently skips unresolvable paths, `
-                            + `disabling the run-unique protection — fix the path (gjson dot notation, e.g. `
-                            + `"name", "nested.id", "items.0.sku") to match an existing body field.`,
+                        message: `uniqueFields path "${fieldPath}" does not resolve in the requestBody of ` +
+                            `${step.method} ${step.path}. The generator silently skips unresolvable paths, ` +
+                            `disabling the run-unique protection — fix the path (gjson dot notation, e.g. ` +
+                            `"name", "nested.id", "items.0.sku") to match an existing body field.`,
                     });
                 }
             }
         }
     }
-    if (isBodyMethod && parsedBody !== null && typeof parsedBody === "object"
-        && !Array.isArray(parsedBody) && Object.keys(parsedBody).length === 0) {
+    if (isBodyMethod &&
+        parsedBody !== null &&
+        typeof parsedBody === "object" &&
+        !Array.isArray(parsedBody) &&
+        Object.keys(parsedBody).length === 0) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
             path: ["requestBody"],
-            message: `requestBody for ${step.method} ${step.path} is an empty object {}. `
-                + `Provide actual field values from the source code schema (Pydantic model, Zod type, DTO) — `
-                + `do not send an empty body for ${step.method} requests.`,
+            message: `requestBody for ${step.method} ${step.path} is an empty object {}. ` +
+                `Provide actual field values from the source code schema (Pydantic model, Zod type, DTO) — ` +
+                `do not send an empty body for ${step.method} requests.`,
         });
     }
 });
@@ -195,17 +208,17 @@ const batchScenarioSchema = {
     authScheme: z
         .string()
         .optional()
-        .describe("Only when authHeader is 'Authorization'. The prefix before the token "
-        + "(e.g., 'Bearer' produces 'Authorization: Bearer <token>'). "
-        + "Common values: 'Bearer', 'Basic', 'Token'. "
-        + "Leave empty if the API uses raw tokens with no prefix. "
-        + "Ignored for non-Authorization headers like X-Api-Key or Cookie."),
+        .describe("Only when authHeader is 'Authorization'. The prefix before the token " +
+        "(e.g., 'Bearer' produces 'Authorization: Bearer <token>'). " +
+        "Common values: 'Bearer', 'Basic', 'Token'. " +
+        "Leave empty if the API uses raw tokens with no prefix. " +
+        "Ignored for non-Authorization headers like X-Api-Key or Cookie."),
     authToken: z
         .string()
         .optional()
-        .describe("Optional explicit auth token value. Leave empty — the service auto-generates "
-        + `${AUTH_PLACEHOLDER_TOKEN} for all auth headers (Authorization, X-API-Key, Cookie, etc.). `
-        + `Only provide this when you need a custom value (e.g., 'session=${AUTH_PLACEHOLDER_TOKEN}' for Cookie).`),
+        .describe("Optional explicit auth token value. Leave empty — the service auto-generates " +
+        `${AUTH_PLACEHOLDER_TOKEN} for all auth headers (Authorization, X-API-Key, Cookie, etc.). ` +
+        `Only provide this when you need a custom value (e.g., 'session=${AUTH_PLACEHOLDER_TOKEN}' for Cookie).`),
 };
 const TOOL_NAME = TOOL_BATCH_SCENARIO_TEST_GENERATION;
 export function registerBatchScenarioTestTool(server) {
@@ -238,7 +251,10 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
             testType: "integration",
         });
         if (guardMessage) {
-            return { content: [{ type: "text", text: guardMessage }], isError: true };
+            return {
+                content: [{ type: "text", text: guardMessage }],
+                isError: true,
+            };
         }
         if (params.authHeader === undefined) {
             try {
@@ -315,7 +331,8 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
                     // limitation for now; the user can always pass apiSchema explicitly.
                     const rawSchemaPath = wsRaw?.services?.[0]?.api?.schemaPath;
                     if (rawSchemaPath && typeof rawSchemaPath === "string") {
-                        const isUrl = rawSchemaPath.startsWith("http://") || rawSchemaPath.startsWith("https://");
+                        const isUrl = rawSchemaPath.startsWith("http://") ||
+                            rawSchemaPath.startsWith("https://");
                         // searchDir is the directory where workspace.yml was found — use it as
                         // the resolution base so relative paths like "../openapi.yml" resolve
                         // correctly regardless of outputDir depth.
@@ -323,7 +340,9 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
                             ? rawSchemaPath
                             : path.resolve(searchDir, rawSchemaPath);
                         params = { ...params, apiSchema: schemaPath };
-                        logger.info("Auto-populated apiSchema from workspace config", { schemaPath });
+                        logger.info("Auto-populated apiSchema from workspace config", {
+                            schemaPath,
+                        });
                     }
                 }
             }
@@ -343,11 +362,15 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
             if (graphqlSteps.length > 0) {
                 return {
                     isError: true,
-                    content: [{ type: "text", text: `GraphQL endpoints are not supported by Skyramp's test generation.\n` +
+                    content: [
+                        {
+                            type: "text",
+                            text: `GraphQL endpoints are not supported by Skyramp's test generation.\n` +
                                 `Affected steps: ${graphqlSteps.map((s) => `${s.method} ${s.path}`).join(", ")}\n\n` +
                                 `Skyramp supports REST API testing only. Remove GraphQL steps and use ` +
                                 `the REST endpoints for the same resource instead.`,
-                        }],
+                        },
+                    ],
                 };
             }
         }
@@ -358,10 +381,13 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
         let specValidationWarning = "";
         if (params.apiSchema) {
             try {
-                const isUrl = params.apiSchema.startsWith("http://") || params.apiSchema.startsWith("https://");
+                const isUrl = params.apiSchema.startsWith("http://") ||
+                    params.apiSchema.startsWith("https://");
                 let specText;
                 if (isUrl) {
-                    const specRes = await fetch(params.apiSchema, { signal: AbortSignal.timeout(10_000) });
+                    const specRes = await fetch(params.apiSchema, {
+                        signal: AbortSignal.timeout(10_000),
+                    });
                     if (!specRes.ok) {
                         throw new Error(`HTTP ${specRes.status} ${specRes.statusText} fetching spec at ${params.apiSchema}`);
                     }
@@ -374,7 +400,9 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
                 }
                 // js-yaml handles both JSON and YAML specs
                 const specLoaded = yaml.load(specText);
-                const specPaths = new Set(Object.keys((specLoaded && typeof specLoaded === "object" ? specLoaded.paths : null) ?? {}));
+                const specPaths = new Set(Object.keys((specLoaded && typeof specLoaded === "object"
+                    ? specLoaded.paths
+                    : null) ?? {}));
                 if (specPaths.size === 0) {
                     logger.warning("Spec loaded but contains no paths — skipping path check", {
                         apiSchema: params.apiSchema,
@@ -391,7 +419,9 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
                         specValidationWarning =
                             `\n\n⚠️ **Spec warning** — the following paths were not found in \`${params.apiSchema}\` ` +
                                 `(spec may be stale or incomplete — verify paths against source before running tests):\n` +
-                                unverifiedSteps.map((s) => `  ${s.method} ${s.path}`).join("\n") +
+                                unverifiedSteps
+                                    .map((s) => `  ${s.method} ${s.path}`)
+                                    .join("\n") +
                                 `\n\nKnown spec paths (first 20): ${[...specPaths].slice(0, 20).join(", ")}`;
                         logger.warning("Step paths not found in spec — proceeding (spec may lag code)", {
                             unverifiedPaths: unverifiedSteps.map((s) => s.path),
@@ -412,11 +442,17 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
         const fileName = scenarioFileNameFor(params.scenarioName);
         const filePath = path.join(params.outputDir, fileName);
         const resolvedOut = path.resolve(params.outputDir);
-        if (!path.resolve(filePath).startsWith(resolvedOut + path.sep) && path.resolve(filePath) !== resolvedOut) {
+        if (!path.resolve(filePath).startsWith(resolvedOut + path.sep) &&
+            path.resolve(filePath) !== resolvedOut) {
             return {
-                content: [{ type: "text", text: `Validation Error: scenarioName '${params.scenarioName}' produced a file path outside outputDir.\n`
-                            + `Expected: File path within '${params.outputDir}'.\n`
-                            + `Fix: Use a simpler scenarioName without path separators or special characters.` }],
+                content: [
+                    {
+                        type: "text",
+                        text: `Validation Error: scenarioName '${params.scenarioName}' produced a file path outside outputDir.\n` +
+                            `Expected: File path within '${params.outputDir}'.\n` +
+                            `Fix: Use a simpler scenarioName without path separators or special characters.`,
+                    },
+                ],
                 isError: true,
             };
         }
@@ -449,11 +485,11 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
                     content: [
                         {
                             type: "text",
-                            text: `**Batch Scenario Generation Failed at Step ${i + 1}/${steps.length}**\n\n`
-                                + `${i}/${steps.length} steps succeeded before failure.\n\n`
-                                + `**Failed step:** ${step.method} ${step.path}\n`
-                                + `**Error:** Could not generate a trace request from the provided parameters.\n\n`
-                                + `Fix the failing step and retry with the full batch.`,
+                            text: `**Batch Scenario Generation Failed at Step ${i + 1}/${steps.length}**\n\n` +
+                                `${i}/${steps.length} steps succeeded before failure.\n\n` +
+                                `**Failed step:** ${step.method} ${step.path}\n` +
+                                `**Error:** Could not generate a trace request from the provided parameters.\n\n` +
+                                `Fix the failing step and retry with the full batch.`,
                         },
                     ],
                     isError: true,
@@ -482,13 +518,13 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
             responseBody: t.ResponseBody,
         })));
         if (chainLint.errors.length > 0) {
-            return toolError(`**Scenario chaining errors**\n\n`
-                + chainLint.errors.map((e) => `- ${e}`).join("\n")
-                + `\n\nApply the remedy each error names and resubmit the full batch.`);
+            return toolError(`**Scenario chaining errors**\n\n` +
+                chainLint.errors.map((e) => `- ${e}`).join("\n") +
+                `\n\nApply the remedy each error names and resubmit the full batch.`);
         }
         const chainLintWarning = chainLint.warnings.length > 0
-            ? `\n\n⚠️ **Chaining warnings** — the generated test may hardcode these instead of chaining:\n`
-                + chainLint.warnings.map((w) => `  - ${w}`).join("\n")
+            ? `\n\n⚠️ **Chaining warnings** — the generated test may hardcode these instead of chaining:\n` +
+                chainLint.warnings.map((w) => `  - ${w}`).join("\n")
             : "";
         try {
             // The contract and integration generators create the test directory through
@@ -502,7 +538,12 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
             return {
-                content: [{ type: "text", text: `Error writing scenario file: ${errorMessage}` }],
+                content: [
+                    {
+                        type: "text",
+                        text: `Error writing scenario file: ${errorMessage}`,
+                    },
+                ],
                 isError: true,
             };
         }
@@ -511,13 +552,13 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
             content: [
                 {
                     type: "text",
-                    text: `**Batch Scenario Generated — ${stepCount} steps**\n\n`
-                        + `**Scenario:** ${params.scenarioName}\n`
-                        + `**Steps:**\n${steps.map((s, i) => `  ${i + 1}. ${s.method} ${s.path} → ${s.statusCode ?? "default"}`).join("\n")}\n\n`
-                        + `**File:** ${filePath}\n\n`
-                        + `**Next:** Call \`skyramp_integration_test_generation\` with \`scenarioFile: "${filePath}"\``
-                        + specValidationWarning
-                        + chainLintWarning,
+                    text: `**Batch Scenario Generated — ${stepCount} steps**\n\n` +
+                        `**Scenario:** ${params.scenarioName}\n` +
+                        `**Steps:**\n${steps.map((s, i) => `  ${i + 1}. ${s.method} ${s.path} → ${s.statusCode ?? "default"}`).join("\n")}\n\n` +
+                        `**File:** ${filePath}\n\n` +
+                        `**Next:** Call \`skyramp_integration_test_generation\` with \`scenarioFile: "${filePath}"\`` +
+                        specValidationWarning +
+                        chainLintWarning,
                 },
             ],
             isError: false,

package/build/tools/generate-tests/generateContractRestTool.js

@@ -5,9 +5,10 @@ import { baseTestSchema, TestType } from "../../types/TestTypes.js";
 import { TestGenerationService, } from "../../services/TestGenerationService.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { getPersonaPrefix } from "../../prompts/personas.js";
-import { isContractConsumerModeEnabled, isTestbotEnabled } from "../../utils/featureFlags.js";
+import { isContractConsumerModeEnabled, isTestbotEnabled, } from "../../utils/featureFlags.js";
 import { guardScenarioApproved, pathFromEndpointURL } from "./planGuard.js";
 import { toolError } from "../../utils/utils.js";
+import { enhanceAssertionsStep } from "../../skills/enhanceAssertionsSkill.js";
 // SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE gates BOTH:
 //   1. Consumer-side contract test generation (`consumerMode` /
 //      `consumerOutput` schema fields, validation, post-gen instructions,
@@ -72,10 +73,13 @@ const baseContractTestSchema = {
             return true;
         const validExtensions = [".py", ".ts", ".js", ".java"];
         return validExtensions.some((ext) => val.endsWith(ext));
-    }, { message: "Output file must have one of these extensions: .py, .ts, .js, .java" })
+    }, {
+        message: "Output file must have one of these extensions: .py, .ts, .js, .java",
+    })
         .describe("Output file for the generated provider contract test. " +
-        "For Playwright framework, the file must match *.spec.ts so Playwright can discover it " +
-        "(e.g. contract_provider_orders.spec.ts). " +
+        "For Playwright, name the file the way the repository names its tests: read the " +
+        "test files already in outputDir and match their spelling. Use *.test.ts where " +
+        "they use it, *.spec.ts otherwise (e.g. contract_provider_orders.spec.ts). " +
         "For other frameworks (pytest, junit), standard extensions are fine (.py, .java). " +
         "Optional — when omitted, Skyramp generates a default name."),
     parentRequestData: z
@@ -85,8 +89,8 @@ const baseContractTestSchema = {
         "IMPORTANT: Each key MUST be the exact path parameter variable name as it appears inside the curly braces in the URL path — NOT an operation ID, endpoint name, or any other identifier. " +
         "For example, for endpoint '/products/{product_id}/reviews', the key is 'product_id' (not 'create_product', not '/products', not any operation name). " +
         "The value is the sample request body JSON string used to create that parent resource. " +
-        "For example: {\"product_id\": \"{\\\"name\\\": \\\"sample product\\\", \\\"price\\\": 10}\"}. " +
-        "For nested parents like '/a/{a_id}/b/{b_id}/c', provide an entry for each: {\"a_id\": \"{...}\", \"b_id\": \"{...}\"}. " +
+        'For example: {"product_id": "{\\"name\\": \\"sample product\\", \\"price\\": 10}"}. ' +
+        'For nested parents like \'/a/{a_id}/b/{b_id}/c\', provide an entry for each: {"a_id": "{...}", "b_id": "{...}"}. ' +
         "Path parameters without an entry here should be supplied via pathParams instead. " +
         PARENT_FIELD_NOT_ALLOWED_NOTE),
     parentStatusCode: z
@@ -96,7 +100,7 @@ const baseContractTestSchema = {
         "IMPORTANT: Each key MUST be the exact path parameter variable name as it appears inside the curly braces in the URL path — the same keys used in parentRequestData. " +
         "For example, for endpoint '/products/{product_id}/reviews', the key is 'product_id' (not an operation name or endpoint path). " +
         "The value is the expected HTTP status code string for the provisioning call that creates that parent resource. " +
-        "For example: {\"product_id\": \"201\"}. " +
+        'For example: {"product_id": "201"}. ' +
         PARENT_FIELD_NOT_ALLOWED_NOTE),
     parentFormParams: z
         .record(z.string(), z.string())
@@ -123,10 +127,13 @@ const consumerModeSchemaFields = {
             return true;
         const validExtensions = [".py", ".ts", ".js", ".java"];
         return validExtensions.some((ext) => val.endsWith(ext));
-    }, { message: "Output file must have one of these extensions: .py, .ts, .js, .java" })
+    }, {
+        message: "Output file must have one of these extensions: .py, .ts, .js, .java",
+    })
         .describe("Output file for the generated consumer contract test. " +
-        "For Playwright framework, the file must match *.spec.ts so Playwright can discover it " +
-        "(e.g. contract_consumer_orders.spec.ts). " +
+        "For Playwright, name the file the way the repository names its tests: read the " +
+        "test files already in outputDir and match their spelling. Use *.test.ts where " +
+        "they use it, *.spec.ts otherwise (e.g. contract_consumer_orders.spec.ts). " +
         "For other frameworks (pytest, junit), standard extensions are fine (.py, .java). " +
         "Optional — when omitted, Skyramp generates a default name."),
 };
@@ -244,7 +251,7 @@ ${this.buildPlaceholderReplacementBlock(params)}
         const nextStepNote = enhanceAssertions ? "continue to Step 2" : undefined;
         steps.push(`### Step ${steps.length + 1} — Replace placeholder values [REQUIRED]\n\n${this.buildPlaceholderReplacementBlock(params, nextStepNote)}`);
         if (enhanceAssertions) {
-            steps.push(`### Step ${steps.length + 1} — Enhance response body assertions [REQUIRED]\nCall \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated provider contract test file, \`testType: "contract"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file.`);
+            steps.push(`### Step ${steps.length + 1} — Enhance response body assertions [REQUIRED]\n${enhanceAssertionsStep("contract", "generated provider contract test file")}`);
         }
         const heading = enhanceAssertions
             ? "Replace placeholder data and enhance assertions"
@@ -283,7 +290,9 @@ The generated consumer contract test contains a stub test function that uses Sky
         if (errList.isError)
             return errList;
         const errors = [];
-        if ((params.parentRequestData || params.parentStatusCode || params.parentFormParams) &&
+        if ((params.parentRequestData ||
+            params.parentStatusCode ||
+            params.parentFormParams) &&
             !params.apiSchema) {
             errors.push("parentRequestData, parentStatusCode, and parentFormParams are only allowed when apiSchema is provided.");
         }
@@ -294,7 +303,10 @@ The generated consumer contract test contains a stub test function that uses Sky
             if (params.consumerOutput && !params.consumerMode) {
                 errors.push("consumerOutput is only valid when consumerMode is enabled.");
             }
-            if (params.consumerMode && (params.parentRequestData || params.parentStatusCode || params.parentFormParams)) {
+            if (params.consumerMode &&
+                (params.parentRequestData ||
+                    params.parentStatusCode ||
+                    params.parentFormParams)) {
                 errors.push("parentRequestData, parentStatusCode, and parentFormParams are not allowed when consumerMode is enabled.");
             }
         }
@@ -314,8 +326,12 @@ The generated consumer contract test contains a stub test function that uses Sky
                         const suggested = /\.[tj]s$/.test(parsed.ext)
                             ? value.replace(/\.[tj]s$/, ".spec.ts")
                             : value + ".spec.ts";
-                        errors.push(`Error: Playwright requires test files to match *.{spec}.{ts,js} (got "${value}" for ${field}). ` +
-                            `Rename to e.g. ${suggested} so Playwright can discover it.`);
+                        // Both spellings are named: a repository that declares
+                        // `testMatch: ["**/*.test.ts"]` collects no *.spec.ts (SKYR-4489).
+                        const alternative = suggested.replace(/\.spec\.ts$/, ".test.ts");
+                        errors.push(`Error: Playwright requires test files to match *.{spec,test}.{ts,js} (got "${value}" for ${field}). ` +
+                            `Rename to ${suggested}, or to ${alternative} if the tests already in ` +
+                            `${params.outputDir} use that spelling.`);
                     }
                 }
             }
@@ -324,7 +340,9 @@ The generated consumer contract test contains a stub test function that uses Sky
             if (!params.providerMode) {
                 errors.push("skipProvisionParents requires providerMode to be enabled.");
             }
-            if (params.parentRequestData || params.parentStatusCode || params.parentFormParams) {
+            if (params.parentRequestData ||
+                params.parentStatusCode ||
+                params.parentFormParams) {
                 errors.push("parentRequestData, parentStatusCode, and parentFormParams are not allowed when skipProvisionParents is enabled.");
             }
         }

package/build/tools/generate-tests/generateE2ERestTool.d.ts

@@ -7,6 +7,7 @@ export declare class E2ETestService extends TestGenerationService {
     protected buildGenerationOptions(params: BaseTestParams & {
         responseData?: string;
         playwrightInput?: string;
+        testName?: string;
     }): any;
     protected handleApiAnalysis(_params: BaseTestParams): Promise<CallToolResult | null>;
 }

package/build/tools/generate-tests/generateE2ERestTool.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { baseSchema, baseTraceSchema, TestType, codeRefactoringSchema, } from "../../types/TestTypes.js";
+import { baseSchema, baseTraceSchema, TestType, codeRefactoringSchema, testNameField, } from "../../types/TestTypes.js";
 import { TestGenerationService, } from "../../services/TestGenerationService.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { toolError } from "../../utils/utils.js";
@@ -16,6 +16,7 @@ const e2eTestSchema = {
         "from a Playwright zip that already produced one is rejected — one recording covers one scenario, and reusing " +
         "it manufactures identical tests under names the recording never covered. Set true only when the same " +
         "recording genuinely covers the new scenario end-to-end."),
+    testName: testNameField("testE2e"),
     ...codeRefactoringSchema.shape,
     ...baseSchema.shape,
 };
@@ -28,6 +29,11 @@ export class E2ETestService extends TestGenerationService {
             ...super.buildBaseGenerationOptions(params),
             responseData: params.responseData,
             playwrightInput: params.playwrightInput,
+            // SKYR-4468: free-form title for the generated test, so the spec names the
+            // behaviour it verifies instead of the generic `testE2e`. The option is
+            // inert until the pinned @skyramp/skyramp release carries it — the client
+            // ignores options it does not know, so passing it early is safe.
+            testName: params.testName,
         };
     }
     async handleApiAnalysis(_params) {
@@ -44,6 +50,8 @@ End-to-End tests validate complete user journeys by testing the entire applicati
 TRACE & UI INTEGRATION:
 E2E tests require both trace files (capturing backend API interactions) and Playwright recordings (capturing UI interactions captured using start_trace_collection tool) to generate comprehensive tests that validate the complete user experience.
 
+**Test title:** Pass \`testName\` with the behaviour this recording verifies (e.g. "Add to cart from search results"), taken from the recommendation the recording came from. Omit it and the spec is titled \`testE2e\`, which claims nothing.
+
 **CRITICAL - When using trace parameter:**
 If \`trace\` parameter is provided (path to a trace file), DO NOT pass \`apiSchema\` or \`endpointURL\` parameters. The trace file already contains all necessary endpoint and schema information. Passing both will cause test generation to fail.`,
         inputSchema: e2eTestSchema,