@skyramp/mcp 0.2.8 → 0.2.150-rc.local.de

package/build/tools/enrichTestWithMocksTool.test.js

@@ -0,0 +1,397 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { buildMockImportBlock, injectMockImports, } from "./enrichTestWithMocksTool.js";
+import { ProgrammingLanguage } from "../types/TestTypes.js";
+describe("enrichTestWithMocksTool", () => {
+    function withTempTestFile(content, callback) {
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-enrich-"));
+        try {
+            const testDir = path.join(tempDir, "tests", "skyramp");
+            const mocksDir = path.join(testDir, "mocks");
+            fs.mkdirSync(mocksDir, { recursive: true });
+            const testFile = path.join(testDir, "partner_happy_path_integration_test.py");
+            fs.writeFileSync(testFile, content);
+            callback(testFile, mocksDir);
+        }
+        finally {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+    }
+    it("builds an apply_all_mocks helper that reuses the integration test client", () => {
+        withTempTestFile("import skyramp\n", (testFile, mocksDir) => {
+            const mockFiles = [
+                path.join(mocksDir, "ams_validate_POST_mock.py"),
+                path.join(mocksDir, "billing_preferences_PUT_mock.py"),
+            ];
+            const block = buildMockImportBlock(testFile, "partner-happy-path", mockFiles);
+            expect(block).toContain("def apply_all_mocks(client):");
+            expect(block).toContain("client.remove_all_mocks()");
+            expect(block).toContain("all_mocks = []");
+            expect(block).toContain("all_mocks.extend(mocks)");
+            expect(block).toContain("client.apply_mock(all_mocks)");
+            // MOCK_TARGET_URLS always emitted (empty when no mock files have parseable URLs)
+            expect(block).toContain("MOCK_TARGET_URLS = {");
+            expect(block).toContain("target_url = MOCK_TARGET_URLS.get(service_name)");
+            // No globals() hack — MOCK_TARGET_URLS is always defined
+            expect(block).not.toContain("globals()");
+            // No Kafka mocks — normalization helper omitted
+            expect(block).not.toContain("_normalize_kafka_mocks");
+            expect(block).not.toContain("from collections import defaultdict");
+            expect(block).not.toContain("by_url[mock.url].append(mock)");
+            expect(block).not.toContain('for protocol in ("rest", "grpc", "kafka"):');
+            expect(block).not.toContain('runtime="docker"');
+        });
+    });
+    it("supports explicit Python language", () => {
+        withTempTestFile("import skyramp\n", (testFile, mocksDir) => {
+            const block = buildMockImportBlock(testFile, "partner-happy-path", [path.join(mocksDir, "billing_preferences_PUT_mock.py")], undefined, ProgrammingLanguage.PYTHON);
+            expect(block).toContain("def apply_all_mocks(client):");
+            expect(block).toContain("import importlib.util");
+        });
+    });
+    it("rejects explicit non-Python languages", () => {
+        withTempTestFile("import skyramp\n", (testFile, mocksDir) => {
+            expect(() => buildMockImportBlock(testFile, "partner-happy-path", [path.join(mocksDir, "billing_preferences_PUT_mock.py")], undefined, ProgrammingLanguage.TYPESCRIPT)).toThrow('Mock enrichment is currently supported only for Python tests; received language "typescript"');
+        });
+    });
+    it("rejects inferred non-Python test files", () => {
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-enrich-ts-"));
+        try {
+            const testDir = path.join(tempDir, "tests", "skyramp");
+            const mocksDir = path.join(testDir, "mocks");
+            fs.mkdirSync(mocksDir, { recursive: true });
+            const testFile = path.join(testDir, "partner_happy_path_integration_test.ts");
+            expect(() => injectMockImports("import skyramp from '@skyramp/skyramp';\n", testFile, "partner-happy-path", [path.join(mocksDir, "billing_preferences_PUT_mock.py")])).toThrow('Mock enrichment is currently supported only for Python tests; received language "typescript"');
+        }
+        finally {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+    });
+    it("does not duplicate an existing mock block on retry", () => {
+        const original = [
+            "import skyramp",
+            "",
+            "# ─── Mock Scenario: existing ──────────────────────────────────────",
+            'SCENARIO_NAME = "existing"',
+            "",
+            "from mocks.billing_preferences_PUT_mock import get_all_mocks as get_billing_preferences_PUT_mock_mocks",
+            "",
+            "MOCK_SERVICES = {",
+            '    "billing-preferences-PUT": get_billing_preferences_PUT_mock_mocks,',
+            "}",
+            "",
+            "def apply_all_mocks(client):",
+            '    """Apply all mocks collectively in one atomic operation."""',
+            "    client.remove_all_mocks()",
+            "",
+            "def test_integration():",
+            "    client = skyramp.Client(",
+            '        runtime="local"',
+            "    )",
+            "    response = client.send_request(",
+            '        url="http://localhost:3000",',
+            '        path="/api/v1/accounts",',
+            '        method="POST"',
+            "    )",
+            "    assert response.status_code == 201",
+            "",
+        ].join("\n");
+        withTempTestFile(original, (testFile, mocksDir) => {
+            const enriched = injectMockImports(original, testFile, "existing", [
+                path.join(mocksDir, "billing_preferences_PUT_mock.py"),
+            ]);
+            expect(enriched.match(/MOCK_SERVICES = \{/g)).toHaveLength(1);
+            expect(enriched.match(/def apply_all_mocks\(client\):/g)).toHaveLength(1);
+            expect(enriched).toContain("apply_all_mocks(client)");
+            expect(enriched).toContain('"billing-preferences-PUT": {"factory": _load_mock_factory("mocks/billing_preferences_PUT_mock.py", "billing_preferences_PUT_mock"), "protocol": "rest"}');
+        });
+    });
+    it("normalizes generated localhost mock URLs back to original service origins", () => {
+        withTempTestFile("import skyramp\n", (testFile, mocksDir) => {
+            const mockFile = path.join(mocksDir, "customer_configurations_GET_mock.py");
+            fs.writeFileSync(mockFile, [
+                "# Generated by Skyramp",
+                "# Command: skyramp generate mock rest http://partner-accounts:50052/api/v1/applications/app_customer_config_test/customer_configurations \\",
+                'URL = skyramp.get_base_url("SKYRAMP_TEST_BASE_URL", "http://localhost:8080")',
+            ].join("\n"));
+            const block = buildMockImportBlock(testFile, "partner-happy-path", [
+                mockFile,
+            ]);
+            expect(block).toContain("MOCK_TARGET_URLS = {");
+            expect(block).toContain('"customer-configurations-GET": "http://partner-accounts:50052"');
+            expect(block).toContain("target_url = MOCK_TARGET_URLS.get(service_name)");
+            expect(block).toContain("mock.url = target_url");
+            // No globals() hack
+            expect(block).not.toContain("globals()");
+        });
+    });
+    it("normalizes multiple REST mock command targets to service origins and ignores generated URL defaults", () => {
+        withTempTestFile("import skyramp\n", (testFile, mocksDir) => {
+            const amsMock = path.join(mocksDir, "validate_POST_mock.py");
+            const billingMock = path.join(mocksDir, "billing_preferences_PUT_mock.py");
+            fs.writeFileSync(amsMock, [
+                "# Generated by Skyramp",
+                "# Command: skyramp generate mock rest http://ams:4000/api/internal/v1/users/validate?trace=abc",
+                'URL = skyramp.get_base_url("SKYRAMP_TEST_BASE_URL", "http://localhost:8080")',
+            ].join("\n"));
+            fs.writeFileSync(billingMock, [
+                "# Generated by Skyramp",
+                "# Command: skyramp generate mock rest http://billing:5001/accounts/:id/billing_preferences",
+                'URL = skyramp.get_base_url("SKYRAMP_TEST_BASE_URL", "http://localhost:8080")',
+            ].join("\n"));
+            const block = buildMockImportBlock(testFile, "rest-routing", [
+                amsMock,
+                billingMock,
+            ]);
+            expect(block).toContain('"validate-POST": "http://ams:4000"');
+            expect(block).toContain('"billing-preferences-PUT": "http://billing:5001"');
+            expect(block).toContain("mock.url = target_url");
+            expect(block).not.toContain('"http://localhost:8080"');
+            expect(block).not.toContain('"http://ams:4000/api/internal/v1/users/validate?trace=abc"');
+        });
+    });
+    it("normalizes generated gRPC mock host:port targets back to original service origins", () => {
+        withTempTestFile("import skyramp\n", (testFile, mocksDir) => {
+            const mockFile = path.join(mocksDir, "partner_accounts_GET_mock.py");
+            fs.writeFileSync(mockFile, [
+                "# Generated by Skyramp",
+                "# Command: skyramp generate mock grpc partner-accounts:50051 \\",
+                "# \\t\\t--proto-path app/proto/partner_accounts.proto \\",
+                "# \\t\\t--service PartnerAccountsService",
+                'URL = skyramp.get_base_url("SKYRAMP_TEST_BASE_URL", "http://localhost:8080")',
+            ].join("\n"));
+            const block = buildMockImportBlock(testFile, "partner-happy-path", [
+                mockFile,
+            ]);
+            expect(block).toContain('"partner-accounts-GET": "partner-accounts:50051"');
+            expect(block).toContain("mock.url = target_url");
+        });
+    });
+    it("normalizes generated Kafka mock host:port targets back to original broker origins", () => {
+        withTempTestFile("import skyramp\n", (testFile, mocksDir) => {
+            const mockFile = path.join(mocksDir, "kafka_events_account_created_mock.py");
+            fs.writeFileSync(mockFile, [
+                "# Generated by Skyramp",
+                "# Command: skyramp generate mock kafka redpanda:9092",
+                "# \t\t--topic events",
+                'URL = skyramp.get_base_url("SKYRAMP_TEST_BASE_URL", "http://localhost:8080")',
+            ].join("\n"));
+            const block = buildMockImportBlock(testFile, "partner-happy-path", [
+                mockFile,
+            ]);
+            expect(block).toContain('"kafka-events-account-created": "redpanda:9092"');
+            expect(block).toContain('"kafka-events-account-created": {"factory": _load_mock_factory("mocks/kafka_events_account_created_mock.py", "kafka_events_account_created_mock"), "protocol": "kafka"}');
+            expect(block).toContain("mock.url = target_url");
+            expect(block).not.toContain('if mock_config.get("protocol") == "kafka":');
+            expect(block).not.toContain("            continue");
+            expect(block).toContain("client.apply_mock(all_mocks)");
+        });
+    });
+    it("injects apply_all_mocks after the generated skyramp client is constructed", () => {
+        const original = [
+            "import skyramp",
+            "",
+            "def test_integration():",
+            "    # Invocation of Skyramp Client",
+            "    client = skyramp.Client(",
+            '        runtime="local"',
+            "    )",
+            "",
+            "    response = client.send_request(",
+            '        url="http://localhost:3000",',
+            '        path="/api/v1/accounts",',
+            '        method="POST"',
+            "    )",
+            "    assert response.status_code == 201",
+            "",
+        ].join("\n");
+        withTempTestFile(original, (testFile, mocksDir) => {
+            const enriched = injectMockImports(original, testFile, "partner-happy-path", [path.join(mocksDir, "billing_preferences_PUT_mock.py")]);
+            const applyCallIndex = enriched.lastIndexOf("apply_all_mocks(client)");
+            expect(applyCallIndex).toBeGreaterThan(-1);
+            expect(enriched.indexOf('runtime="local"')).toBeLessThan(applyCallIndex);
+            expect(applyCallIndex).toBeLessThan(enriched.indexOf("client.send_request"));
+            expect(enriched).not.toContain("SKYRAMP_WORKER_IMAGE");
+            expect(enriched).not.toContain("client.worker_image");
+            expect(enriched).not.toContain("client.local_image");
+        });
+    });
+    it("replaces an existing generated mock block on retry", () => {
+        const original = [
+            "import skyramp",
+            "",
+            "# ─── Mock Scenario: stale ──────────────────────────────────────",
+            'SCENARIO_NAME = "stale"',
+            "",
+            "from mocks.old_mock import get_all_mocks as get_old_mock_mocks",
+            "",
+            "MOCK_SERVICES = {",
+            '    "old": get_old_mock_mocks,',
+            "}",
+            "",
+            "def apply_all_mocks(client):",
+            '    """Apply all mocks collectively in one atomic operation."""',
+            "    client.remove_all_mocks()",
+            "    client.apply_mock([])",
+            "",
+            "def test_integration():",
+            "    client = skyramp.Client(",
+            '        runtime="local"',
+            "    )",
+            "    apply_all_mocks(client)",
+            "    assert True",
+            "",
+        ].join("\n");
+        withTempTestFile(original, (testFile, mocksDir) => {
+            const enriched = injectMockImports(original, testFile, "fresh", [
+                path.join(mocksDir, "billing_preferences_PUT_mock.py"),
+            ]);
+            expect(enriched.match(/MOCK_SERVICES = \{/g)).toHaveLength(1);
+            expect(enriched.match(/def apply_all_mocks\(client\):/g)).toHaveLength(1);
+            expect(enriched).toContain('SCENARIO_NAME = "fresh"');
+            expect(enriched).toContain("billing_preferences_PUT_mock");
+            expect(enriched).not.toContain("SKYRAMP_WORKER_IMAGE");
+            expect(enriched).not.toContain("client.worker_image");
+            expect(enriched).not.toContain("client.local_image");
+            expect(enriched).not.toContain("old_mock");
+            expect(enriched).not.toContain('"old": get_old_mock_mocks');
+        });
+    });
+    it("sanitizes dotted mock filename aliases", () => {
+        withTempTestFile("import skyramp\n", (testFile, mocksDir) => {
+            const mockFile = path.join(mocksDir, "idl.partner_accounts.customerconfigurationsservice_mock.py");
+            fs.writeFileSync(mockFile, [
+                "# Generated by Skyramp",
+                "# Command: skyramp generate mock grpc partner-accounts:50051 \\",
+                "# \t\t--service CustomerConfigurationsService",
+            ].join("\n"));
+            const block = buildMockImportBlock(testFile, "partner-happy-path", [
+                mockFile,
+            ]);
+            expect(block).toContain("import importlib.util");
+            expect(block).toContain('"idl.partner-accounts.customerconfigurationsservice": {"factory": _load_mock_factory("mocks/idl.partner_accounts.customerconfigurationsservice_mock.py", "idl_partner_accounts_customerconfigurationsservice_mock"), "protocol": "grpc"}');
+        });
+    });
+    it("normalizes generated Python Kafka mocks before applying all protocols together", () => {
+        withTempTestFile("import skyramp\n", (testFile, mocksDir) => {
+            const restMock = path.join(mocksDir, "billing_preferences_PUT_mock.py");
+            const grpcMock = path.join(mocksDir, "partner_accounts_mock.py");
+            const kafkaMock = path.join(mocksDir, "kafka_events_mock.py");
+            fs.writeFileSync(restMock, "# Command: skyramp generate mock rest http://billing:5001/accounts/:id/billing_preferences");
+            fs.writeFileSync(grpcMock, "# Command: skyramp generate mock grpc partner-accounts:50051");
+            fs.writeFileSync(kafkaMock, "# Command: skyramp generate mock kafka redpanda:9092");
+            const block = buildMockImportBlock(testFile, "mixed", [
+                restMock,
+                grpcMock,
+                kafkaMock,
+            ]);
+            expect(block).toContain('"billing-preferences-PUT": {"factory": _load_mock_factory("mocks/billing_preferences_PUT_mock.py", "billing_preferences_PUT_mock"), "protocol": "rest"}');
+            expect(block).toContain('"partner-accounts": {"factory": _load_mock_factory("mocks/partner_accounts_mock.py", "partner_accounts_mock"), "protocol": "grpc"}');
+            expect(block).toContain('"kafka-events": {"factory": _load_mock_factory("mocks/kafka_events_mock.py", "kafka_events_mock"), "protocol": "kafka"}');
+            expect(block).not.toContain("def _normalize_kafka_mocks(service_name, mocks):");
+            expect(block).toContain('"kafka-events": "redpanda:9092"');
+            expect(block).not.toContain('if mock_config.get("protocol") == "kafka":');
+            expect(block).not.toContain("            continue");
+            expect(block).toContain("all_mocks.extend(mocks)");
+            expect(block.match(/client\.apply_mock\(all_mocks\)/g)).toHaveLength(1);
+        });
+    });
+    it("omits _normalize_kafka_mocks when no Kafka mocks are present (billing-rejects scenario)", () => {
+        withTempTestFile("import skyramp\n", (testFile, mocksDir) => {
+            // Mirrors the Checkr billing_rejects_rollback scenario: REST + gRPC only, no Kafka
+            const validateMock = path.join(mocksDir, "validate_POST_mock.py");
+            const partnerAppsMock = path.join(mocksDir, "partnerapplicationsservice_mock.py");
+            const customerConfigsMock = path.join(mocksDir, "customerconfigurationsservice_mock.py");
+            const billingMock = path.join(mocksDir, "billing_preferences_PUT_mock.py");
+            fs.writeFileSync(validateMock, "# Command: skyramp generate mock rest http://ams:4000/api/internal/v1/users/validate");
+            fs.writeFileSync(partnerAppsMock, "# Command: skyramp generate mock grpc partner-accounts:50051");
+            fs.writeFileSync(customerConfigsMock, "# Command: skyramp generate mock grpc partner-accounts:50051");
+            fs.writeFileSync(billingMock, "# Command: skyramp generate mock rest http://billing:5001/accounts/:id/billing_preferences");
+            const block = buildMockImportBlock(testFile, "billing-rejects-rollback", [
+                validateMock, partnerAppsMock, customerConfigsMock, billingMock,
+            ]);
+            expect(block).toContain('SCENARIO_NAME = "billing-rejects-rollback"');
+            expect(block).toContain("MOCK_TARGET_URLS = {");
+            expect(block).toContain('"validate-POST": "http://ams:4000"');
+            expect(block).toContain('"billing-preferences-PUT": "http://billing:5001"');
+            expect(block).toContain('"partnerapplicationsservice": "partner-accounts:50051"');
+            // No Kafka → normalization helper must be absent
+            expect(block).not.toContain("_normalize_kafka_mocks");
+            expect(block).not.toContain("globals()");
+            // apply_all_mocks still present and complete
+            expect(block).toContain("def apply_all_mocks(client):");
+            expect(block).toContain("target_url = MOCK_TARGET_URLS.get(service_name)");
+        });
+    });
+    it("emits _normalize_kafka_mocks for Checkr partner-account-with-customer-configs (REST + gRPC + Kafka)", () => {
+        withTempTestFile("import skyramp\n", (testFile, mocksDir) => {
+            // Mirrors the real partner_account_with_customer_configs test in checkr-demo
+            const validateMock = path.join(mocksDir, "validate_POST_mock.py");
+            const usersMock = path.join(mocksDir, "users_POST_mock.py");
+            const billingMock = path.join(mocksDir, "billing_preferences_PUT_success_mock.py");
+            const partnerAppsMock = path.join(mocksDir, "partnerapplicationsservice_mock.py");
+            const customerConfigsMock = path.join(mocksDir, "customerconfigurationsservice_mock.py");
+            const recacheMock = path.join(mocksDir, "recachepartnermetricsservice_mock.py");
+            const kafkaEventsMock = path.join(mocksDir, "kafka_events_mock.py");
+            const kafkaConsentMock = path.join(mocksDir, "kafka_consent_customer_mock.py");
+            fs.writeFileSync(validateMock, "# Command: skyramp generate mock rest http://ams:4000/api/internal/v1/users/validate");
+            fs.writeFileSync(usersMock, "# Command: skyramp generate mock rest http://ams:4000/api/internal/v1/users");
+            fs.writeFileSync(billingMock, "# Command: skyramp generate mock rest http://billing:5001/accounts/:id/billing_preferences");
+            fs.writeFileSync(partnerAppsMock, "# Command: skyramp generate mock grpc partner-accounts:50051");
+            fs.writeFileSync(customerConfigsMock, "# Command: skyramp generate mock grpc partner-accounts:50051");
+            fs.writeFileSync(recacheMock, "# Command: skyramp generate mock grpc partner-accounts:50051");
+            fs.writeFileSync(kafkaEventsMock, "# Command: skyramp generate mock kafka redpanda:9092");
+            fs.writeFileSync(kafkaConsentMock, "# Command: skyramp generate mock kafka redpanda:9092");
+            const block = buildMockImportBlock(testFile, "partner-account-with-customer-configs", [
+                validateMock, usersMock, billingMock,
+                partnerAppsMock, customerConfigsMock, recacheMock,
+                kafkaEventsMock, kafkaConsentMock,
+            ]);
+            expect(block).toContain('SCENARIO_NAME = "partner-account-with-customer-configs"');
+            expect(block).not.toContain("def _normalize_kafka_mocks(service_name, mocks):");
+            expect(block).not.toContain('if mock_config.get("protocol") == "kafka":');
+            expect(block).not.toContain("            continue");
+            // REST, gRPC, and Kafka targets are all represented in MOCK_TARGET_URLS.
+            expect(block).toContain('"validate-POST": "http://ams:4000"');
+            expect(block).toContain('"billing-preferences-PUT-success": "http://billing:5001"');
+            expect(block).toContain('"partnerapplicationsservice": "partner-accounts:50051"');
+            expect(block).toContain('"kafka-events": "redpanda:9092"');
+            expect(block).toContain('"kafka-consent-customer": "redpanda:9092"');
+            // No globals() hack
+            expect(block).not.toContain("globals()");
+            expect(block).toContain("target_url = MOCK_TARGET_URLS.get(service_name)");
+        });
+    });
+    it("preserves helper code after a generated block on retry", () => {
+        const original = [
+            "import skyramp",
+            "",
+            "# ─── Mock Scenario: stale ──────────────────────────────────────",
+            'SCENARIO_NAME = "stale"',
+            "",
+            "MOCK_SERVICES = {",
+            "}",
+            "",
+            "def apply_all_mocks(client):",
+            "    client.remove_all_mocks()",
+            "",
+            "def make_payload():",
+            '    return {"ok": True}',
+            "",
+            "def test_integration():",
+            "    client = skyramp.Client()",
+            "    apply_all_mocks(client)",
+            '    assert make_payload()["ok"]',
+            "",
+        ].join("\n");
+        withTempTestFile(original, (testFile, mocksDir) => {
+            const enriched = injectMockImports(original, testFile, "fresh", [
+                path.join(mocksDir, "billing_preferences_PUT_mock.py"),
+            ]);
+            expect(enriched).toContain("\ndef make_payload():");
+            expect(enriched).toContain('return {"ok": True}');
+            expect(enriched).toContain('SCENARIO_NAME = "fresh"');
+        });
+    });
+});

package/build/tools/executeSkyrampTestTool.d.ts

@@ -1,2 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 export declare function registerExecuteSkyrampTestTool(server: McpServer): void;
+export declare function testFileHasDeployableMockTargets(testFile: string): boolean;
+export declare function validateMockIsolationConfirmation(testFile: string, mockIsolationConfirmed?: boolean): CallToolResult | undefined;

package/build/tools/executeSkyrampTestTool.js

@@ -1,11 +1,12 @@
 import { z } from "zod";
 import { stripVTControlCharacters } from "util";
+import * as fs from "fs";
 import { TestExecutionService } from "../services/TestExecutionService.js";
 import { AnalyticsService } from "../services/AnalyticsService.js";
 import { TestExecutionStatus } from "../types/TestExecution.js";
 import { getWorkspaceBaseUrl } from "../utils/workspaceAuth.js";
 import { ProgrammingLanguage, TestType } from "../types/TestTypes.js";
-import { StateManager } from "../utils/AnalysisStateManager.js";
+import { StateManager, } from "../utils/AnalysisStateManager.js";
 import { logger } from "../utils/logger.js";
 const TOOL_NAME = "skyramp_execute_test";
 export function registerExecuteSkyrampTestTool(server) {
@@ -28,6 +29,7 @@ REQUIRED PARAMETERS:
 
 OPTIONAL PARAMETERS:
 - stateFile: Path to state file from skyramp_analyze_changes. When provided, execution results (passed/failed, errors, duration) will be written back to enrich test health analysis.
+- mockIsolationConfirmed: Required for enriched integration tests with MOCK_SERVICES. Set true only after confirming every real service selected for mocking is stopped and will not be started during execution.
 
 AUTHENTICATION:
 Pass an empty string as the token parameter — the server automatically injects SKYRAMP_TEST_TOKEN from the environment. The executor applies it with the correct header defined in workspace.yml:
@@ -53,7 +55,7 @@ For detailed documentation visit: https://www.skyramp.dev/docs/quickstart`,
                 .describe("Programming language of the test file to execute (e.g., python, javascript, typescript, java)"),
             testType: z
                 .nativeEnum(TestType)
-                .describe("Type of the test to execute."),
+                .describe("Type of the test to execute. Note: 'mock' is NOT a valid test type — mock files are deployed via their apply_mock() function, not executed as tests."),
             testFile: z
                 .string()
                 .describe("ALWAYS USE ABSOLUTE PATH to the test file to execute"),
@@ -76,28 +78,42 @@ For detailed documentation visit: https://www.skyramp.dev/docs/quickstart`,
                 .string()
                 .optional()
                 .describe("The owner/repo whose analysis section to write execution results into (e.g. 'letsramp/api-insight'). In a multi-repo run, ALWAYS set it — the primary's owner/repo for a primary-repo test, or a related repo's owner/repo for that repo's section of the run-scoped stateFile. Omit only for a single-repo run."),
+            mockIsolationConfirmed: z
+                .boolean()
+                .optional()
+                .describe("For enriched integration tests with MOCK_SERVICES, set true only after verifying every real downstream service selected for mocking is stopped and only the Skyramp worker will own those service aliases during execution."),
         },
         _meta: {
             keywords: ["run test", "execute test"],
         },
     }, async (params, extra) => {
-        let errorResult;
-        // Helper to send progress notifications to the MCP client
+        // Helper to send progress notifications to the MCP client.
+        // Wrapped in try-catch so a broken/disconnected transport never crashes
+        // the tool handler or causes an unhandled rejection.
         const sendProgress = async (progress, total, message) => {
             const progressToken = extra._meta?.progressToken;
             if (progressToken !== undefined) {
-                const notification = {
-                    method: "notifications/progress",
-                    params: {
-                        progressToken,
-                        progress,
-                        total,
-                        message,
-                    },
-                };
-                await extra.sendNotification(notification);
+                try {
+                    const notification = {
+                        method: "notifications/progress",
+                        params: {
+                            progressToken,
+                            progress,
+                            total,
+                            message,
+                        },
+                    };
+                    await extra.sendNotification(notification);
+                }
+                catch {
+                    // Progress notifications are best-effort — swallow failures so
+                    // a flaky or disconnected transport doesn't kill the execution.
+                }
             }
         };
+        // Send immediate acknowledgment
+        await sendProgress(0, 100, "Starting execution...");
+        let errorResult;
         // Progress callback adapter for TestExecutionService
         const onExecutionProgress = async (progress) => {
             await sendProgress(progress.percent, 100, progress.message);
@@ -107,20 +123,27 @@ For detailed documentation visit: https://www.skyramp.dev/docs/quickstart`,
         let useHostNetwork = false;
         try {
             // Send initial progress
-            await sendProgress(0, 100, "Starting test execution...");
+            await sendProgress(5, 100, "Starting test execution...");
+            const mockIsolationError = validateMockIsolationConfirmation(params.testFile, params.mockIsolationConfirmed);
+            if (mockIsolationError) {
+                errorResult = mockIsolationError;
+                return mockIsolationError;
+            }
             // Always resolve workspace config for dockerNetwork (host networking)
             // and optionally inject SKYRAMP_TEST_BASE_URL if not already set.
             if (params.workspacePath) {
                 const { baseUrl, dockerNetwork, candidates } = await getWorkspaceBaseUrl(params.workspacePath, params.testFile, params.language);
                 useHostNetwork = !!dockerNetwork;
-                if (!process.env.SKYRAMP_TEST_BASE_URL) {
+                const shouldInjectBaseUrl = params.testType !== TestType.CONTRACT;
+                if (shouldInjectBaseUrl && !process.env.SKYRAMP_TEST_BASE_URL) {
                     if (baseUrl) {
                         process.env.SKYRAMP_TEST_BASE_URL = baseUrl;
                         didSetSkyrampBaseUrl = true;
                     }
                     else if (candidates.length > 0) {
                         return {
-                            content: [{
+                            content: [
+                                {
                                     type: "text",
                                     text: [
                                         `Cannot determine SKYRAMP_TEST_BASE_URL — test file matches multiple services:`,
@@ -128,7 +151,8 @@ For detailed documentation visit: https://www.skyramp.dev/docs/quickstart`,
                                         ``,
                                         `Re-invoke with SKYRAMP_TEST_BASE_URL set to the correct service URL, or make each service's testDirectory unique in .skyramp/workspace.yml.`,
                                     ].join("\n"),
-                                }],
+                                },
+                            ],
                             isError: true,
                         };
                     }
@@ -235,3 +259,34 @@ For detailed documentation visit: https://www.skyramp.dev/docs/quickstart`,
         }
     });
 }
+export function testFileHasDeployableMockTargets(testFile) {
+    if (!fs.existsSync(testFile))
+        return false;
+    const source = fs.readFileSync(testFile, "utf-8");
+    return (/MOCK_TARGET_URLS\s*=\s*{\s*["']/s.test(source) ||
+        /"protocol"\s*:\s*"(?:rest|grpc|kafka)"/s.test(source));
+}
+export function validateMockIsolationConfirmation(testFile, mockIsolationConfirmed) {
+    if (!testFileHasDeployableMockTargets(testFile) || mockIsolationConfirmed) {
+        return undefined;
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: [
+                    "**Blocked: mock isolation confirmation is required before execution.**",
+                    "",
+                    "This test contains deployable REST/gRPC/Kafka mock targets, so selected downstream services or brokers will be mocked by Skyramp. Before running it, stop every real service container selected for mocking and ensure the SUT will connect after mocks are applied.",
+                    "",
+                    "Required checklist:",
+                    "1. Identify the services in `MOCK_SERVICES` / `MOCK_TARGET_URLS`.",
+                    "2. Stop the matching real docker-compose services, e.g. `docker compose stop <mocked-service>`.",
+                    "3. Start or restart only the SUT and real dependencies; do not start mocked downstream services.",
+                    "4. Re-run `skyramp_execute_test` with `mockIsolationConfirmed: true`.",
+                ].join("\n"),
+            },
+        ],
+        isError: true,
+    };
+}

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

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