How to Test REST APIs¶

Test HTTP/REST APIs without browser automation. Import OpenAPI specs or write test specs manually, then let AI generate and heal Playwright-based API tests.

Overview¶

The API testing framework provides:

• OpenAPI/Swagger import -- parse specs into structured API test definitions
• AI-powered test generation -- generates Playwright API test code from specs
• Self-healing -- automatically fixes failing tests without browser tools
• Background execution -- run tests as background jobs with status tracking
• Run history -- database-backed results with detailed logs

Unlike UI testing, API tests use Playwright's HTTP request capabilities (not a browser). No Playwright MCP server or browser instance is needed.

Prerequisites¶

• Quorvex AI installed and running (make dev or make prod-dev)
• An API endpoint to test (or an OpenAPI/Swagger spec file)
• AI credentials configured in .env

Step-by-Step Usage¶

1. Import an OpenAPI Spec¶

If you have an OpenAPI/Swagger specification:

1. Navigate to API Testing in the web dashboard (/api-testing)
2. Click Import OpenAPI
3. Upload your openapi.json or openapi.yaml file
4. The system parses endpoints, request/response schemas, and authentication requirements
5. API test specs are generated and stored in specs/api/

Via the API:

curl -X POST http://localhost:8001/api-testing/import-openapi \
  -H "Content-Type: multipart/form-data" \
  -F "file=@openapi.json" \
  -F "project_id=your-project-id"

2. Write an API Test Spec Manually¶

Create a markdown file describing the API tests:

# API Test: User Management

## Base URL
https://api.example.com/v1

## Authentication
Bearer token via Authorization header.
Use environment variable {{API_TOKEN}}.

## Tests

### GET /users
- Send GET request to /users
- Verify response status is 200
- Verify response contains an array of user objects
- Each user should have id, email, and name fields

### POST /users
- Send POST request to /users with body:
  - name: "Test User"
  - email: "test@example.com"
- Verify response status is 201
- Verify response contains the created user with an id

### GET /users/{id}
- Send GET request to /users/1
- Verify response status is 200
- Verify response contains user details

### DELETE /users/{id}
- Send DELETE request to /users/1
- Verify response status is 204

Save this via the dashboard or the API:

curl -X POST http://localhost:8001/api-testing/specs \
  -H "Content-Type: application/json" \
  -d '{
    "name": "user-management",
    "content": "# API Test: User Management\n...",
    "project_id": "your-project-id"
  }'

3. Run the API Test¶

From the dashboard, click the Run button on any API spec. The system:

1. AI reads the spec and generates Playwright API test code (native_api_generator.py)
2. Tests execute via Playwright (HTTP requests, no browser)
3. If tests fail, native_api_healer.py analyzes failures and fixes the code
4. Results are stored in the database

Via the API:

curl -X POST http://localhost:8001/api-testing/specs/user-management/run \
  -H "Content-Type: application/json" \
  -d '{"project_id": "your-project-id"}'

4. View Results¶

Check run history in the dashboard or via API:

# List all runs
curl http://localhost:8001/api-testing/runs?project_id=your-project-id

# Get specific run details
curl http://localhost:8001/api-testing/runs/RUN_ID

Configuration¶

Store API credentials in .env and reference them in specs:

# .env
API_TOKEN=your-bearer-token
API_KEY=your-api-key

Reference in spec: Use environment variable {{API_TOKEN}}

API Endpoints Reference¶

Key Differences from UI Testing¶

Key Files¶

Troubleshooting¶

Verification¶

Confirm API testing works end-to-end:

1. The spec is visible in the dashboard API Testing page or via GET /api-testing/specs
2. A run completes with status passed or failed (not error)
3. Run details include generated test code and execution logs
4. Running the generated test directly passes:

   npx playwright test tests/generated/api-*.spec.ts
   

Related Guides¶

• Writing Specs -- general spec format
• Load Testing -- performance test your APIs
• Security Testing -- scan API endpoints for vulnerabilities
• Credential Management -- manage API tokens securely