Integration tests for APIs

README.md

@@ -23,6 +23,9 @@ npm run build
 # Run tests
 npm test
 
+# Run tests with coverage
+npm test -- --coverage
+
 # Start dev server (with hot reload)
 npm run dev
 
@@ -40,6 +43,49 @@ npm start
 | `npm test`      | Run Jest tests                 |
 | `npm run lint`  | Run ESLint                     |
 
+## Integration tests
+
+The backend includes a focused integration test suite covering representative API behavior for:
+
+- `GET /health`
+- `GET /api/v1/contracts`
+- `GET /api/v1/contracts/:id`
+- `POST /api/v1/contracts`
+
+The tests verify:
+
+- success paths
+- malformed JSON handling
+- validation failures
+- duplicate creation conflicts
+- not found and unsupported route behavior
+- internal error sanitization
+- server bootstrap/start-stop behavior
+
+### Test architecture
+
+To keep tests deterministic and reviewer-friendly:
+
+- `src/app.ts` creates the Express app without listening
+- `src/index.ts` only starts the HTTP server
+- `ContractService` uses per-app in-memory state for tests
+- no external services or production systems are contacted
+
+### Security and threat assumptions validated
+
+- malformed input is rejected early
+- invalid identifiers do not proceed to resource lookup
+- duplicate resource creation is blocked
+- self-dealing contract creation is denied
+- internal errors are sanitized and do not leak stack traces
+- integration tests do not depend on live external systems
+
+### Documentation
+
+Detailed backend test notes live in:
+
+- `docs/backend/integration-testing.md`
+
 ## Contributing
 
 1. Fork the repo and create a branch from `main`.

docs/backend/integration-testing.md

@@ -0,0 +1,67 @@
+# Backend Integration Testing
+
+## Overview
+
+The backend now includes a focused integration test suite for the API surface. The suite verifies representative success and failure behavior without relying on external services or mutable shared state.
+
+## Test architecture
+
+The production server bootstrap was split into two small pieces:
+
+- `src/app.ts` creates an importable Express app
+- `src/index.ts` starts the HTTP server
+
+This keeps production behavior intact while allowing tests to instantiate the app directly without binding to a port.
+
+## Isolation strategy
+
+- Tests use an in-memory `ContractService`
+- Each app instance gets its own service state
+- No external database or network dependency is required
+- No production services are called
+
+## Covered API flows
+
+- `GET /health`
+- `GET /api/v1/contracts`
+- `GET /api/v1/contracts/:id`
+- `POST /api/v1/contracts`
+
+## Covered failure paths
+
+- malformed JSON
+- missing required request fields
+- invalid path identifiers
+- duplicate resource creation
+- unauthorized role/ownership style misuse via self-dealing protection
+- unknown contract lookup
+- unknown route
+- unsupported method under current router behavior
+- unexpected internal error sanitization
+
+## Security assumptions validated
+
+- malformed input is rejected
+- invalid identifiers are rejected before lookup
+- internal errors do not leak implementation details
+- duplicate creation conflicts are handled consistently
+- self-dealing contract creation is denied
+- tests do not contact external systems
+
+## How to run
+
+```bash
+npm test
+npm run build
+```
+
+To inspect coverage:
+
+```bash
+npm test -- --coverage
+```
+
+## Limitations
+
+- The backend currently has a small API surface and no persistent database integration yet, so tests focus on the present app behavior and in-memory service layer.
+- Auth middleware does not exist in the current repo, so authentication-specific integration cases are not added beyond the present business-rule enforcement.