@democratize-quality/mcp-server 1.0.0

package/docs/api_tools_usage.md

@@ -0,0 +1,477 @@
+---
+
+## Playwright MCP API Tool Usage in 
+
+This guide shows how to use the API testing tool you added to the Playwright MCP server from , with real-world API endpoints and prompt examples for all HTTP methods and advanced validation.
+
+---
+
+## 1. Tool Overview
+- **Tool Name:** `api_request`
+- **Description:** Perform an HTTP API request (GET, POST, PUT, PATCH, DELETE, etc.) and validate the response.
+- **Config Requirement:** `"api_request"` must be present in your MCP config `capabilities`.
+
+---
+
+## 2. General Prompt Pattern
+
+> **Prompt:**
+> "Call the `api_request` tool to make a [METHOD] request to `[URL]` with [optional headers/data]."
+
+You can specify method, headers, data, and expected status/content-type/body.
+
+---
+
+## 3. Basic Example Prompts and Payloads
+
+### A. GET Request (Public API)
+**Prompt:**
+```
+Call the `api_request` tool to make a GET request to `https://jsonplaceholder.typicode.com/posts/1`.
+```
+**Payload:**
+```json
+{
+  "method": "GET",
+  "url": "https://jsonplaceholder.typicode.com/posts/1"
+}
+```
+
+### B. POST Request (JSON)
+**Prompt:**
+```
+Call the `api_request` tool to make a POST request to `https://jsonplaceholder.typicode.com/posts` with JSON body `{ "title": "foo", "body": "bar", "userId": 1 }`.
+```
+**Payload:**
+```json
+{
+  "method": "POST",
+  "url": "https://jsonplaceholder.typicode.com/posts",
+  "headers": { "Content-Type": "application/json" },
+  "data": { "title": "foo", "body": "bar", "userId": 1 }
+}
+```
+
+### C. PUT Request
+**Prompt:**
+```
+Call the `api_request` tool to make a PUT request to `https://jsonplaceholder.typicode.com/posts/1` with JSON body `{ "id": 1, "title": "updated", "body": "baz", "userId": 1 }`.
+```
+**Payload:**
+```json
+{
+  "method": "PUT",
+  "url": "https://jsonplaceholder.typicode.com/posts/1",
+  "headers": { "Content-Type": "application/json" },
+  "data": { "id": 1, "title": "updated", "body": "baz", "userId": 1 }
+}
+```
+
+### D. PATCH Request
+**Prompt:**
+```
+Call the `api_request` tool to make a PATCH request to `https://jsonplaceholder.typicode.com/posts/1` with JSON `{ "title": "patched" }`.
+```
+**Payload:**
+```json
+{
+  "method": "PATCH",
+  "url": "https://jsonplaceholder.typicode.com/posts/1",
+  "headers": { "Content-Type": "application/json" },
+  "data": { "title": "patched" }
+}
+```
+
+### E. DELETE Request
+**Prompt:**
+```
+Call the `api_request` tool to make a DELETE request to `https://jsonplaceholder.typicode.com/posts/1`.
+```
+**Payload:**
+```json
+{
+  "method": "DELETE",
+  "url": "https://jsonplaceholder.typicode.com/posts/1"
+}
+```
+
+---
+
+## 4. Advanced: Adding Expectations
+You can add `expect` for status, content-type, and advanced body validation:
+```json
+{
+  "method": "GET",
+  "url": "https://jsonplaceholder.typicode.com/posts/1",
+  "expect": {
+    "status": 200,
+    "contentType": "application/json"
+  }
+}
+```
+
+---
+
+## 5. Response Body Validation: Example Scenarios
+
+### A. Partial/Exact JSON Body Match
+**Prompt:**
+```
+Call the `api_request` tool to make a GET request to `https://jsonplaceholder.typicode.com/posts/1` and validate that the response contains `"userId": 1` and `"id": 1`.
+```
+**Payload:**
+```json
+{
+  "method": "GET",
+  "url": "https://jsonplaceholder.typicode.com/posts/1",
+  "expect": {
+    "body": { "userId": 1, "id": 1 }
+  }
+}
+```
+
+### B. Regex Body Match
+**Prompt:**
+```
+Call the `api_request` tool to make a GET request to `https://jsonplaceholder.typicode.com/posts/1` and check if the response contains the word `"sunt"`.
+```
+**Payload:**
+```json
+{
+  "method": "GET",
+  "url": "https://jsonplaceholder.typicode.com/posts/1",
+  "expect": {
+    "bodyRegex": "sunt"
+  }
+}
+```
+
+### C. Failing Case Example
+**Prompt:**
+```
+Call the `api_request` tool to make a GET request to `https://jsonplaceholder.typicode.com/posts/1` and validate that the response contains `"userId": 999`.
+```
+**Payload:**
+```json
+{
+  "method": "GET",
+  "url": "https://jsonplaceholder.typicode.com/posts/1",
+  "expect": {
+    "body": { "userId": 999 }
+  }
+}
+```
+**Expected:**
+- The validation should fail, and the output will include a `bodyValidation` object with `matched: false` and a reason.
+
+---
+
+## 6. Real-World API Examples: Custom Headers & Authentication
+
+### Example 1: Using Custom Headers
+**Scenario:** Send a GET request to the [httpbin.org/headers](https://httpbin.org/headers) endpoint with a custom header.
+
+**Prompt:**
+```
+Call the `api_request` tool to make a GET request to `https://httpbin.org/headers` with custom header `X-Custom-Header: Test`.
+```
+**Payload:**
+```json
+{
+  "method": "GET",
+  "url": "https://httpbin.org/headers",
+  "headers": {
+    "X-Custom-Header": "Test"
+  }
+}
+```
+- **What to expect:** The response will echo your custom header in the response body.
+
+---
+
+### Example 2: Authentication (Bearer Token)
+**Scenario:** Access a protected endpoint using Bearer token authentication. We'll use [reqres.in](https://reqres.in/) which simulates a real login and protected resource.
+
+**Step 1: Obtain a Token**
+
+**Prompt:**
+```
+Call the `api_request` tool to make a POST request to `https://reqres.in/api/login` with JSON `{ "email": "eve.holt@reqres.in", "password": "cityslicka" }`.
+```
+**Payload:**
+```json
+{
+  "method": "POST",
+  "url": "https://reqres.in/api/login",
+  "headers": { "Content-Type": "application/json" },
+  "data": {
+    "email": "eve.holt@reqres.in",
+    "password": "cityslicka"
+  }
+}
+```
+- **The response will include a `token`.**
+
+**Step 2: Use the Token in an Authenticated Request**
+
+**Prompt:**
+```
+Call the `api_request` tool to make a GET request to `https://reqres.in/api/users/2` with Bearer token authentication.
+```
+**Payload:**
+```
+{
+  "method": "GET",
+  "url": "https://reqres.in/api/users/2",
+  "headers": {
+    "Authorization": "Bearer YOUR_TOKEN_HERE"
+  }
+}
+```
+- **Replace `YOUR_TOKEN_HERE` with the token received from the login step.**
+
+---
+
+These examples can be copied directly into  prompts or used as templates for your own API testing scenarios.
+
+---
+
+## 7. Using sessionId for API Test Sessions
+
+You can explicitly set a session ID for your API test workflow, or let the tool auto-generate one. This helps you group related API calls for reporting and debugging.
+
+### Example 1: Provide a Custom sessionId
+
+** Prompt Example:**
+```
+Call the `api_request` tool to make a POST request to `https://jsonplaceholder.typicode.com/posts` with session ID `demo-session-1`.
+```
+**Payload:**
+```json
+{
+  "sessionId": "demo-session-1",
+  "method": "POST",
+  "url": "https://jsonplaceholder.typicode.com/posts",
+  "headers": { "Content-Type": "application/json" },
+  "data": { "title": "foo", "body": "bar", "userId": 1 }
+}
+```
+
+### Example 2: Use sessionId in Chaining
+
+** Prompt Example:**
+```
+Call the `api_request` tool to chain a login and authenticated GET using session ID `login-chain-demo`.
+```
+**Payload:**
+```json
+{
+  "sessionId": "login-chain-demo",
+  "chain": [
+    {
+      "name": "login",
+      "method": "POST",
+      "url": "https://reqres.in/api/login",
+      "headers": { "Content-Type": "application/json" },
+      "data": { "email": "eve.holt@reqres.in", "password": "cityslicka" },
+      "extract": { "token": "token" }
+    },
+    {
+      "name": "getUser",
+      "method": "GET",
+      "url": "https://reqres.in/api/users/2",
+      "headers": { "Authorization": "Bearer {{login.token}}" }
+    }
+  ]
+}
+```
+
+### Example 3: Omit sessionId for Auto-Generated Sessions
+
+** Prompt Example:**
+```
+Call the `api_request` tool to make a GET request to `https://jsonplaceholder.typicode.com/posts/1` and let the tool auto-generate the session ID.
+```
+**Payload:**
+```json
+{
+  "method": "GET",
+  "url": "https://jsonplaceholder.typicode.com/posts/1"
+}
+```
+
+The tool result will always include the sessionId used, so you can reference it for later queries or reporting.
+
+---
+
+## 8. Querying API Session Status
+
+You can retrieve the status, logs, and results for any API test session using the `api_session_status` tool and a sessionId.
+
+### Example 1: Query a Known Session
+
+** Prompt Example:**
+```
+Call the `api_session_status` tool to show the logs and results for session ID `login-chain-demo`.
+```
+**Payload:**
+```json
+{
+  "sessionId": "login-chain-demo"
+}
+```
+
+### Example 2: Query an Auto-Generated Session
+
+If you did not provide a sessionId, copy the sessionId from the previous API tool result and use it here.
+
+** Prompt Example:**
+```
+Call the `api_session_status` tool to show the results for session ID `session-abc123xyz`.
+```
+**Payload:**
+```json
+{
+  "sessionId": "session-abc123xyz"
+}
+```
+
+The output will include all requests, responses, validation results, and timestamps for the session.
+
+---
+
+## 9. Generating an HTML Report for a Session
+
+You can generate and retrieve a detailed HTML report for any API test session using the `api_session_report` tool and a sessionId.
+
+### Example 1: Generate a Report for a Known Session
+
+** Prompt Example:**
+```
+Call the `api_session_report` tool to generate an HTML report for session ID `login-chain-demo`.
+```
+**Payload:**
+```json
+{
+  "sessionId": "login-chain-demo"
+}
+```
+
+### Example 2: Generate a Report for an Auto-Generated Session
+
+If you did not provide a sessionId, copy the sessionId from the previous API tool result and use it here.
+
+** Prompt Example:**
+```
+Call the `api_session_report` tool to generate an HTML report for session ID `session-abc123xyz`.
+```
+**Payload:**
+```json
+{
+  "sessionId": "session-abc123xyz"
+}
+```
+
+The output will show the file path to the generated HTML report (e.g., `reports/session-login-chain-demo.html`). Open this file in your browser to view the full report.
+
+---
+
+## 10. API Chaining: Multi-Step Requests & Variable Passing
+
+You can execute a sequence of API requests where outputs from one step can be used in subsequent steps. This enables scenarios like login and token usage, resource creation and retrieval, etc.
+
+### Input Schema for Chaining
+
+** Prompt Example:**
+```
+Call the `api_request` tool to execute a chain of two API requests. First, POST to `https://api.example.com/login` with username and password, extract the token, then GET `https://api.example.com/data` using `Bearer {{step1.token}}` in the Authorization header.
+```
+```json
+{
+  "chain": [
+    {
+      "name": "step1",
+      "method": "POST",
+      "url": "https://api.example.com/login",
+      "headers": { "Content-Type": "application/json" },
+      "data": { "username": "user", "password": "pass" },
+      "extract": { "token": "token" }
+    },
+    {
+      "name": "step2",
+      "method": "GET",
+      "url": "https://api.example.com/data",
+      "headers": { "Authorization": "Bearer {{step1.token}}" }
+    }
+  ]
+}
+```
+- Each step must have a unique `name`.
+- Use `extract` to pull fields from the response JSON (dot notation supported).
+- Use `{{stepName.field}}` in later steps to reference extracted values.
+
+---
+
+### Real-World Example: Login and Authenticated Request (reqres.in)
+
+** Prompt Example:**
+```
+Call the `api_request` tool to chain a login to `https://reqres.in/api/login` (extract the token) and then GET `https://reqres.in/api/users/2` with Bearer token from the login step.
+```
+**Payload:**
+```json
+{
+  "chain": [
+    {
+      "name": "login",
+      "method": "POST",
+      "url": "https://reqres.in/api/login",
+      "headers": { "Content-Type": "application/json" },
+      "data": { "email": "eve.holt@reqres.in", "password": "cityslicka" },
+      "extract": { "token": "token" }
+    },
+    {
+      "name": "getUser",
+      "method": "GET",
+      "url": "https://reqres.in/api/users/2",
+      "headers": { "Authorization": "Bearer {{login.token}}" }
+    }
+  ]
+}
+```
+- The first step logs in and extracts the `token`.
+- The second step uses `{{login.token}}` in the Authorization header.
+- The tool output will include results for both steps, including extracted variables and validation.
+
+---
+
+### Chaining with Validation
+
+** Prompt Example:**
+```
+Call the `api_request` tool to chain a login to `https://reqres.in/api/login` (extract the token, expect status 200) and then GET `https://reqres.in/api/users/2` with Bearer token from the login step, expecting status 200 and user id 2 in the body.
+```
+```json
+{
+  "chain": [
+    {
+      "name": "login",
+      "method": "POST",
+      "url": "https://reqres.in/api/login",
+      "headers": { "Content-Type": "application/json" },
+      "data": { "email": "eve.holt@reqres.in", "password": "cityslicka" },
+      "extract": { "token": "token" },
+      "expect": { "status": 200 }
+    },
+    {
+      "name": "getUser",
+      "method": "GET",
+      "url": "https://reqres.in/api/users/2",
+      "headers": { "Authorization": "Bearer {{login.token}}" },
+      "expect": { "status": 200, "body": { "data": { "id": 2 } } }
+    }
+  ]
+}
+```
+
+---