Playwright MCP Server

Instructions

Implementation Reference

• src/tools/browser/response.ts:49-102 (handler)

  The AssertResponseTool class that implements the execute method for handling the playwright_assert_response tool logic, including waiting for the response promise, parsing JSON body, asserting optional value presence, and cleaning up the promise map.

  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:294-305 (schema)

  Tool schema definition including name, description, and input schema with required 'id' and optional 'value' parameters.

  {
    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:486-490 (registration)

  Switch case in the main tool handler that registers and dispatches 'playwright_assert_response' calls to the AssertResponseTool instance.

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

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

  Inclusion in BROWSER_TOOLS array which triggers browser context setup for this tool.

  "playwright_assert_response",

• src/tools/codegen/generator.ts:77-139 (helper)

  Code generation case for including assert_response logic in generated Playwright tests.

      case 'playwright_assert_response':
        return this.generateAssertResponseStep(parameters);
      case 'playwright_hover':
        return this.generateHoverStep(parameters);
      case 'playwright_select':
        return this.generateSelectStep(parameters);
      case 'playwright_custom_user_agent':
        return this.generateCustomUserAgentStep(parameters);
      default:
        console.warn(`Unsupported tool: ${toolName}`);
        return null;
    }
  }
  
  private generateNavigateStep(parameters: Record<string, unknown>): string {
    const { url, waitUntil } = parameters;
    const options = waitUntil ? `, { waitUntil: '${waitUntil}' }` : '';
    return `
    // Navigate to URL
    await page.goto('${url}'${options});`;
  }
  
  private generateFillStep(parameters: Record<string, unknown>): string {
    const { selector, value } = parameters;
    return `
    // Fill input field
    await page.fill('${selector}', '${value}');`;
  }
  
  private generateClickStep(parameters: Record<string, unknown>): string {
    const { selector } = parameters;
    return `
    // Click element
    await page.click('${selector}');`;
  }
  
  private generateScreenshotStep(parameters: Record<string, unknown>): string {
    const { name, fullPage = false, path } = parameters;
    const options = [];
    if (fullPage) options.push('fullPage: true');
    if (path) options.push(`path: '${path}'`);
    
    const optionsStr = options.length > 0 ? `, { ${options.join(', ')} }` : '';
    return `
    // Take screenshot
    await page.screenshot({ path: '${name}.png'${optionsStr} });`;
  }
  
  private generateExpectResponseStep(parameters: Record<string, unknown>): string {
    const { url, id } = parameters;
    return `
    // Wait for response
    const ${id}Response = page.waitForResponse('${url}');`;
  }
  
  private generateAssertResponseStep(parameters: Record<string, unknown>): string {
    const { id, value } = parameters;
    const assertion = value 
      ? `\n    const responseText = await ${id}Response.text();\n    expect(responseText).toContain('${value}');`
      : `\n    expect(${id}Response.ok()).toBeTruthy();`;
    return `
    // Assert response${assertion}`;
  }