api-to-testcase-generator

What this skill does

# API-to-Test Case Generator

Converts API definitions into production-ready test suites covering happy paths, edge cases,
error handling, and boundary conditions.

---

## Supported Input Formats

| Format | Example |
|---|---|
| OpenAPI 3.x YAML/JSON | `openapi: 3.0.0` |
| Swagger 2.0 | `swagger: "2.0"` |
| Postman Collection v2.x | JSON export from Postman |
| Raw curl commands | `curl -X POST https://...` |
| Plain English description | "POST /users creates a user with name and email" |
| HTTP request/response examples | Paste raw request + response |
| Code (route handlers / controllers) | Express.js, FastAPI, Spring, etc. |

---

## Supported Test Frameworks

| Language | Frameworks |
|---|---|
| Python | `pytest` + `requests` or `httpx` |
| JavaScript/TypeScript | `Jest`, `Mocha`/`Chai`, `Supertest` |
| Java | `JUnit 5` + `RestAssured` |
| Go | `testing` + `net/http/httptest` |
| API-level (language-agnostic) | `Newman` (Postman), `k6` (load), plain `.http` files |

If the user doesn't specify a framework, **ask** — or default to `pytest` for Python APIs, `Jest` for JS/TS APIs.

---

## Workflow

### Step 1 — Parse the API Definition

Extract from the input:
- **Endpoints**: method + path (e.g., `POST /api/v1/users`)
- **Request**: headers, query params, path params, body schema (required vs optional fields, types)
- **Response**: status codes, response body schema, headers
- **Auth**: Bearer token, API key, Basic auth, OAuth2
- **Constraints**: min/max, enum values, format (email, uuid, date-time), nullable

If input is ambiguous or incomplete, ask the user to clarify before generating.

### Step 2 — Determine Test Strategy

For each endpoint, generate tests across these categories:

#### ✅ Happy Path Tests
- Valid request with all required fields → expect `2xx`
- Valid request with all optional fields included
- Minimal valid request (required fields only)

#### ❌ Validation / Error Tests
- Missing required fields → expect `400`/`422`
- Invalid field types (string where int expected, etc.)
- Out-of-range values (below min, above max)
- Invalid enum values
- Malformed request body (invalid JSON)
- Extra/unknown fields (if strict validation expected)

#### 🔒 Auth / Authorization Tests
- No auth token → expect `401`
- Invalid/expired token → expect `401`
- Insufficient permissions → expect `403`
- Valid token → expect success

#### 🔍 Edge Cases
- Empty string / null for optional fields
- Maximum-length strings
- Boundary values (min, max, min-1, max+1)
- Special characters in string fields
- Idempotency (repeat same request — does it behave correctly?)

#### 🌐 Integration / Flow Tests (when multiple endpoints provided)
- Create → Read → Update → Delete flows
- Pagination (first page, last page, page out of range)
- Filtering and sorting combinations

### Step 3 — Generate Test Code

Follow the structure below per framework. See `reference/framework-templates.md` for detailed templates.

**General principles:**
- Each test should be atomic and independent (no shared mutable state)
- Use descriptive test names: `test_create_user_returns_201_with_valid_payload`
- Parameterize similar tests where appropriate (pytest `@pytest.mark.parametrize`, Jest `test.each`)
- Group tests by endpoint in a class or describe block
- Extract base URL, auth tokens, and reusable fixtures into a shared setup section
- Assert on: status code, response body fields, response headers (content-type), response time if relevant

### Step 4 — Output Structure

Present output as:
1. **Summary table** — endpoints covered, test count per category
2. **Test file(s)** — complete, runnable code
3. **Setup instructions** — how to install deps and run the suite
4. **Coverage gaps** — any untestable scenarios due to missing spec info

---

## Output Examples by Framework

### pytest (Python)

```python
import pytest
import requests

BASE_URL = "https://api.example.com"
HEADERS = {"Authorization": "Bearer YOUR_TOKEN", "Content-Type": "application/json"}

class TestCreateUser:
    def test_valid_payload_returns_201(self):
        payload = {"name": "Alice", "email": "[email protected]"}
        response = requests.post(f"{BASE_URL}/users", json=payload, headers=HEADERS)
        assert response.status_code == 201
        data = response.json()
        assert "id" in data
        assert data["email"] == payload["email"]

    @pytest.mark.parametrize("missing_field", ["name", "email"])
    def test_missing_required_field_returns_422(self, missing_field):
        payload = {"name": "Alice", "email": "[email protected]"}
        del payload[missing_field]
        response = requests.post(f"{BASE_URL}/users", json=payload, headers=HEADERS)
        assert response.status_code == 422

    def test_no_auth_returns_401(self):
        payload = {"name": "Alice", "email": "[email protected]"}
        response = requests.post(f"{BASE_URL}/users", json=payload)
        assert response.status_code == 401
```

### Jest (JavaScript/TypeScript)

```javascript
const axios = require('axios');

const BASE_URL = 'https://api.example.com';
const headers = { Authorization: 'Bearer YOUR_TOKEN' };

describe('POST /users', () => {
  test('valid payload returns 201', async () => {
    const res = await axios.post(`${BASE_URL}/users`, { name: 'Alice', email: '[email protected]' }, { headers });
    expect(res.status).toBe(201);
    expect(res.data).toHaveProperty('id');
  });

  test.each(['name', 'email'])('missing %s returns 422', async (field) => {
    const payload = { name: 'Alice', email: '[email protected]' };
    delete payload[field];
    await expect(axios.post(`${BASE_URL}/users`, payload, { headers })).rejects.toMatchObject({
      response: { status: 422 },
    });
  });
});
```

For full templates (JUnit, RestAssured, Mocha, Newman, k6), see `reference/framework-templates.md`.

---

## Handling Incomplete Specs

If the API definition is missing critical information, ask the user:

1. **Auth method** — "Does this endpoint require authentication? If so, what type (Bearer, API Key, Basic)?"
2. **Error schema** — "What does the error response body look like for validation failures?"
3. **Environment** — "What's the base URL? Is there a sandbox/staging environment for tests?"
4. **Side effects** — "Does this endpoint mutate state? Should we clean up test data after runs?"
5. **Framework preference** — "Which test framework/language would you like the output in?"

---

## Special Modes

### `--mock` mode
If the user wants tests that run without a live server, generate tests using:
- `responses` (Python) or `nock` / `msw` (JS) to mock HTTP calls
- Useful for unit testing business logic in isolation

### `--load` mode
If the user wants performance/load tests, output **k6** scripts:
```javascript
import http from 'k6/http';
import { check } from 'k6';
export const options = { vus: 50, duration: '30s' };
export default function () {
  const res = http.post('https://api.example.com/users', JSON.stringify({ name: 'test', email: '[email protected]' }), {
    headers: { 'Content-Type': 'application/json' },
  });
  check(res, { 'status is 201': (r) => r.status === 201 });
}
```

### `--contract` mode
If the user wants contract tests (consumer-driven), generate **Pact** (JS/Python/Java) test stubs.

---

## Quality Checklist

Before delivering output, verify:
- [ ] Every documented status code has at least one test
- [ ] All required fields have a "missing field" test
- [ ] Auth-protected endpoints have an unauthenticated test
- [ ] Parametrized tests used where inputs vary but assertion logic is identical
- [ ] Test names are descriptive and follow `verb_condition_expectation` pattern
- [ ] Fixtures/setup code is DRY and reusable
- [ ] Instructions to run the suite are included

---

## Reference Files

- `reference/framework-templates.md` — Full boilerplate for each supported framework
- `reference/openapi-parsing-guide.md` — How to extract test data from OpenAPI schemas

Read these when generating tests for a l