mcp-playwright

Instructions

Implementation Reference

• src/tools/browser/response.ts:42-86 (handler)

  The AssertResponseTool class implements the core logic for the 'playwright_assert_response' tool, handling response waiting, validation against expected value, and returning success/error responses.

  export class AssertResponseTool extends BrowserToolBase {
    /**
     * Execute the assert response tool
     */
    async execute(args: AssertResponseArgs, context: ToolContext): Promise<ToolResponse> {
      return this.safeExecute(context, async () => {
        if (!args.id) {
          return createErrorResponse("Missing required parameter: id must be provided");
        }
  
        const responsePromise = responsePromises.get(args.id);
        if (!responsePromise) {
          return createErrorResponse(`No response wait operation found with ID: ${args.id}`);
        }
  
        try {
          const response = await responsePromise;
          const body = await response.json();
  
          if (args.value) {
            const bodyStr = JSON.stringify(body);
            if (!bodyStr.includes(args.value)) {
              const messages = [
                `Response body does not contain expected value: ${args.value}`,
                `Actual body: ${bodyStr}`
              ];
              return createErrorResponse(messages.join('\n'));
            }
          }
  
          const messages = [
            `Response assertion for ID ${args.id} successful`,
            `URL: ${response.url()}`,
            `Status: ${response.status()}`,
            `Body: ${JSON.stringify(body, null, 2)}`
          ];
          return createSuccessResponse(messages.join('\n'));
        } catch (error) {
          return createErrorResponse(`Failed to assert response: ${(error as Error).message}`);
        } finally {
          responsePromises.delete(args.id);
        }
      });
    }
  } 

• src/tools.ts:319-330 (schema)

  MCP tool schema definition specifying the name, description, and input parameters (id required, value optional) for the tool.

  {
    name: "playwright_assert_response",
    description: "Wait for and validate a previously initiated HTTP response wait operation.",
    inputSchema: {
      type: "object",
      properties: {
        id: { type: "string", description: "Identifier of the HTTP response initially expected using `Playwright_expect_response`." },
        value: { type: "string", description: "Data to expect in the body of the HTTP response. If provided, the assertion will fail if this value is not found in the response body." }
      },
      required: ["id"],
    },
  },

• src/toolHandler.ts:511-512 (registration)

  Registration and dispatch in the main tool handler switch statement, routing tool calls to the AssertResponseTool's execute method.

  case "playwright_assert_response":
    return await assertResponseTool.execute(args, context);

• src/tools.ts:463-463 (registration)

  The tool name is registered in the BROWSER_TOOLS array, enabling conditional browser launch for this tool.

  "playwright_assert_response",

• src/tools/browser/response.ts:6-86 (helper)

  Shared Map storing response promises keyed by ID, used by both expect_response and assert_response tools.

  const responsePromises = new Map<string, Promise<Response>>();
  
  interface ExpectResponseArgs {
    id: string;
    url: string;
  }
  
  interface AssertResponseArgs {
    id: string;
    value?: string;
  }
  
  /**
   * Tool for setting up response wait operations
   */
  export class ExpectResponseTool extends BrowserToolBase {
    /**
     * Execute the expect response tool
     */
    async execute(args: ExpectResponseArgs, context: ToolContext): Promise<ToolResponse> {
      return this.safeExecute(context, async (page) => {
        if (!args.id || !args.url) {
          return createErrorResponse("Missing required parameters: id and url must be provided");
        }
  
        const responsePromise = page.waitForResponse(args.url);
        responsePromises.set(args.id, responsePromise);
  
        return createSuccessResponse(`Started waiting for response with ID ${args.id}`);
      });
    }
  }
  
  /**
   * Tool for asserting and validating responses
   */
  export class AssertResponseTool extends BrowserToolBase {
    /**
     * Execute the assert response tool
     */
    async execute(args: AssertResponseArgs, context: ToolContext): Promise<ToolResponse> {
      return this.safeExecute(context, async () => {
        if (!args.id) {
          return createErrorResponse("Missing required parameter: id must be provided");
        }
  
        const responsePromise = responsePromises.get(args.id);
        if (!responsePromise) {
          return createErrorResponse(`No response wait operation found with ID: ${args.id}`);
        }
  
        try {
          const response = await responsePromise;
          const body = await response.json();
  
          if (args.value) {
            const bodyStr = JSON.stringify(body);
            if (!bodyStr.includes(args.value)) {
              const messages = [
                `Response body does not contain expected value: ${args.value}`,
                `Actual body: ${bodyStr}`
              ];
              return createErrorResponse(messages.join('\n'));
            }
          }
  
          const messages = [
            `Response assertion for ID ${args.id} successful`,
            `URL: ${response.url()}`,
            `Status: ${response.status()}`,
            `Body: ${JSON.stringify(body, null, 2)}`
          ];
          return createSuccessResponse(messages.join('\n'));
        } catch (error) {
          return createErrorResponse(`Failed to assert response: ${(error as Error).message}`);
        } finally {
          responsePromises.delete(args.id);
        }
      });
    }
  }