52 lines
2.9 KiB
Markdown
52 lines
2.9 KiB
Markdown
# apps/desktop/contracts/
|
|
|
|
## Responsibility
|
|
|
|
Public API boundary contract tests for the OpenPets desktop application. These contracts validate that critical external-facing interfaces (catalog data, IPC protocol) conform to expected schemas and behavior. Contract tests are compiled to `.test-dist/contracts/` and executed during `pnpm test`.
|
|
|
|
## Design Patterns
|
|
|
|
- **Schema Validation Contracts**: Test catalog and plugin manifest validation logic against valid fixtures plus targeted invalid cases
|
|
- **Protocol Contracts**: Verify IPC request/response parsing, token validation, and message constraints
|
|
- **Fixture-Based Testing**: Uses real fixture data (`catalog.v2.fixture.json`) to ensure validation matches production data
|
|
- **Negative Testing**: Includes invalid cases to ensure proper rejection of malformed data
|
|
- **Standalone Execution**: Each contract file is executable Node.js code that runs independently
|
|
|
|
## Data & Control Flow
|
|
|
|
**Catalog Fixture Contract** (`catalog-fixture.contract.ts`):
|
|
```
|
|
Load catalog.v2.fixture.json → validateCatalogV2() → Assert valid
|
|
→ Test invalid cases (bad IDs, duplicates, HTTP URLs, wrong hosts, reserved IDs)
|
|
→ Assert each invalid case is properly rejected
|
|
```
|
|
|
|
**Local IPC Protocol Contract** (`local-ipc-protocol.contract.ts`):
|
|
```
|
|
Test parseIpcRequest() with valid/invalid tokens, versions, methods
|
|
→ Test validateReaction() with valid/invalid reaction types
|
|
→ Test validateSayMessage() with valid/invalid messages (length, newlines, code blocks, URLs, paths, secrets)
|
|
→ Test maxIpcMessageBytes boundary
|
|
→ Test errorResponse() structure
|
|
```
|
|
|
|
**Plugin Manifest Contract** (`plugin-manifest.contract.ts`):
|
|
```
|
|
Assert openpets.plugin.json filename constant
|
|
→ Validate a declarative timer manifest with permissions, config schema, and pet actions
|
|
→ Test config references, unknown fields, runtime/permission constraints, deferred config types/features, defaults, options, timer intervals, and required permissions
|
|
→ Assert each invalid manifest reports the expected error code
|
|
```
|
|
|
|
## Integration Points
|
|
|
|
- **Source modules**: Imports from `../src/catalog-validation.js`, `../src/local-ipc-protocol.js`, `../src/plugin-manifest.js`
|
|
- **Fixture data**: `catalog.v2.fixture.json` in parent directory
|
|
- **Test runner**: Executed by `scripts/run-tests.mjs` in the contract tests phase
|
|
- **Build output**: Compiled to `.test-dist/contracts/*.contract.js` via `tsconfig.tests.json`
|
|
|
|
## Key Contracts
|
|
|
|
- `catalog-fixture.contract.ts`: Validates catalog V2 schema against fixture and invalid cases (duplicate IDs, bad URL schemes, wrong hosts, reserved "builtin" ID)
|
|
- `local-ipc-protocol.contract.ts`: Validates IPC protocol parsing, token auth, reaction types, message constraints, and error response formatting
|
|
- `plugin-manifest.contract.ts`: Validates plugin manifest filename, declarative timer manifest schema, permission requirements, config references, action constraints, and expected validation error codes
|