Test Authenticated Routes

Purpose

Validate that protected API endpoints work end-to-end after changes, including authentication, authorization, request validation, business logic, and persistence side effects.

When to use

Use this skill when:

• •You added or changed a protected endpoint
• •You refactored controller/service/repository code for an endpoint
• •You added new permission checks
• •You suspect a regression in route wiring or middleware order

Avoid using this skill when:

• •You only need to define what to test (use an inventory/planning workflow)
• •You are looking for unit-test-only guidance without any end-to-end request execution

Inputs

• •A list of endpoints to test (method + path)
• •Expected request/response shapes (or a link to validation schemas)
• •Test identities:
  • •at least one authorized user
  • •optionally one unauthorized/insufficient-role user for negative testing
• •Expected persistence side effects for write endpoints
• •Execution constraints:
  • •environments you are allowed to hit
  • •whether destructive operations are allowed

Outputs

• •A per-endpoint smoke test record (one row/section per endpoint):
  • •sanitized request + response
  • •at least one negative case + response
  • •side-effect verification notes (for writes)
• •A lightweight implementation review:
  • •correctness/security risks
  • •maintainability concerns
  • •missing tests/validation

Steps

1) Safety and scope check (required)

• •Confirm the environment you will test against and any constraints.
• •Do not test destructive endpoints unless you have safe test data and approval.

2) Inventory endpoints to test

• •Prefer using a structured inventory (from diffs/PR notes).
• •For each endpoint, note:
  • •method
  • •full external path (including global prefixes)
  • •whether it is protected
  • •whether it writes data

3) Understand the contract

For each endpoint:

• •Required inputs (params/query/body)
• •Expected success status + response shape
• •Expected failure codes for common failures (400, 401, 403, 404)

4) Execute the happy path and record evidence

• •Call the endpoint using a real authenticated request.
• •Record (sanitized):
  • •the command or client invocation
  • •status code
  • •response body shape
  • •any returned IDs

5) Verify persistence side effects (write endpoints)

• •Verify records were created/updated/deleted as expected.
• •Verify derived effects (queues/audit logs) if applicable.

6) Execute at least one negative case per endpoint

Choose one (or more if high risk):

• •missing required field (validation)
• •invalid enum/value range (validation)
• •missing auth (expect 401)
• •insufficient permission (expect 403)

7) Lightweight implementation review

Check quickly:

• •route delegates to controller (no business logic in route)
• •controller validates inputs
• •service contains business rules
• •repository isolates persistence
• •errors map consistently to status codes and stable error shapes

Verification

• • Every listed endpoint has a completed test record
• • Happy path returns expected status code and response shape
• • Negative case(s) recorded with expected status and stable error shape
• • Permission failures return 403 (or your convention) and do not create side effects
• • Write endpoints have side-effect verification notes
• • No secrets or real tokens are logged or recorded

Boundaries

• •MUST NOT use real production credentials
• •MUST NOT run destructive writes without explicit approval and safe test data
• •MUST NOT log or record secrets/tokens
• •MUST NOT approve endpoints without understanding the implementation at a high level
• •SHOULD NOT test only happy paths (include negative cases)
• •SHOULD capture reproducible evidence so another engineer can re-run the test

Included assets

• •Templates: ./templates/endpoint-test-worksheet.md is a per-endpoint test record format.
• •Examples: ./examples/ includes a sample test record.