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).