smoke-test-authenticated-api-routes

# Smoke Test Authenticated API Routes

## Purpose
Provide a repeatable approach to quickly validate that protected API endpoints work end-to-end: authentication, request handling, and persistence side effects.

## When to use
Use this skill when you are:
- Testing a newly added endpoint
- Verifying endpoint behavior after refactors
- Debugging auth-related failures (`401`, `403`)
- Confirming that POST/PUT/PATCH/DELETE endpoints create or update the right records


Avoid using this skill when:
- You need a full end-to-end test execution record across many endpoints, or you need to produce evidence for a release gate.
- You primarily need a code/implementation review rather than a smoke test plan and quick validation run.

## Inputs
- Endpoint(s): method + URL path
- Authentication method:
  - cookie-based session
  - bearer token
  - API key
  - mock/dev bypass (development only)
- Required request body/query/params
- Expected response shape and status code
- Expected persistence side effects (tables/collections/records)

## Outputs
- A minimal smoke test plan per endpoint:
  - valid request
  - invalid request (one representative)
  - expected status codes and response shapes
- Verification notes for persistence side effects
- A short debug report if a test fails (observations + likely causes)

## Core rules
- Smoke tests SHOULD prioritize the happy path and core behavior.
- Tests MUST NOT use real production credentials.
- Any "mock auth" bypass MUST be limited to non-production environments.
- Persisted side effects MUST be verified for write endpoints.

## Steps
1. **Locate the endpoint contract**
   - method + path
   - request fields (required/optional)
   - response shape

2. **Prepare authentication**
   - Obtain a valid session/token for a test user, or use a non-production auth bypass if available.
   - Record the user/role used for the test.

3. **Run a valid request**
   - Use an HTTP client (curl, Postman, a test harness, or automated integration test).
   - Record status code and response body.

4. **Verify side effects (write endpoints)**
   - Query the database or inspect logs to confirm expected changes.
   - Verify idempotency expectations if the endpoint is retried.

5. **Run one invalid request**
   - Example: missing required field, invalid enum, or invalid identifier.
   - Verify validation status code and error shape.

6. **If the request fails, triage by class**
   - `401` unauthorized: missing/invalid auth
   - `403` forbidden: user lacks permission
   - `404` not found: wrong URL/prefix/route registration
   - `5xx` server error: unhandled exception or downstream dependency

## Verification

- [ ] Status codes match the contract
- [ ] Success response contains required fields
- [ ] Validation errors return stable error codes and details
- [ ] Persistence side effects match expectations
- [ ] No secrets or tokens were logged or committed to docs
- [ ] At least one valid and one invalid request were tested

## Boundaries

- MUST NOT use real production credentials in tests
- MUST NOT enable mock auth bypasses in production environments
- MUST NOT skip persistence verification for write endpoints
- MUST NOT log or commit secrets/tokens to documentation
- SHOULD NOT test only happy paths (include at least one negative case)
- SHOULD NOT assume auth context without verifying it is attached

## Included assets
- Templates: `./templates/` includes a route test matrix and a JSON test spec schema.
- Examples: `./examples/` includes curl patterns for cookie and bearer auth (placeholders only).