Skip to content

Commit dde7485

Browse files
johnfjohnf
committed
feat: add tests
1 parent 56c1dc5 commit dde7485

30 files changed

+3361
-86
lines changed

‎.claude/settings.local.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"permissions": {
3-
"allow": ["Bash(pnpm run lint*)"],
3+
"allow": ["Bash(pnpm run test:*)", "Bash(pnpm run lint:*)"],
44
"deny": [],
55
"ask": []
66
}

‎.github/workflows/test.yml‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
name: Test Suite
2+
3+
on:
4+
pull_request:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
jobs:
9+
test:
10+
runs-on: ubuntu-latest
11+
timeout-minutes: 15
12+
13+
permissions:
14+
contents: read
15+
pull-requests: write
16+
17+
services:
18+
mysql:
19+
image: mysql:8
20+
env:
21+
MYSQL_ROOT_PASSWORD: password
22+
MYSQL_DATABASE: catalog_test
23+
ports:
24+
- 3307:3306
25+
options: >-
26+
--health-cmd="mysqladmin ping"
27+
--health-interval=10s
28+
--health-timeout=5s
29+
--health-retries=3
30+
31+
opensearch:
32+
image: opensearchproject/opensearch:3
33+
env:
34+
cluster.name: test-opensearch-cluster
35+
node.name: test-opensearch
36+
discovery.type: single-node
37+
bootstrap.memory_lock: true
38+
OPENSEARCH_JAVA_OPTS: -Xms256m -Xmx256m
39+
DISABLE_SECURITY_PLUGIN: true
40+
ports:
41+
- 9201:9200
42+
options: >-
43+
--health-cmd="curl -f http://localhost:9200/_cluster/health || exit 1"
44+
--health-interval=30s
45+
--health-timeout=10s
46+
--health-retries=3
47+
48+
steps:
49+
- name: Checkout code
50+
uses: actions/checkout@v4
51+
52+
- name: Setup pnpm
53+
uses: pnpm/action-setup@v4
54+
55+
- name: Setup Node.js
56+
uses: actions/setup-node@v4
57+
with:
58+
node-version: "lts/*"
59+
cache: pnpm
60+
61+
- name: Install dependencies
62+
run: pnpm install --frozen-lockfile
63+
64+
- name: Generate Prisma client
65+
run: pnpm run generate
66+
67+
- name: Run database migrations
68+
run: pnpm run db:migrate
69+
env:
70+
DATABASE_URL: mysql://root:password@localhost:3307/catalog_test
71+
72+
- name: Run linting
73+
run: |
74+
pnpm run lint:biome
75+
pnpm run lint:types
76+
77+
- name: Run unit tests
78+
run: pnpm run test
79+
env:
80+
DATABASE_URL: mysql://root:password@localhost:3307/catalog_test
81+
OPENSEARCH_URL: http://localhost:9201
82+
NODE_ENV: test
83+
84+
- name: Report Coverage
85+
if: always()
86+
uses: davelosert/vitest-coverage-report-action@v2

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,5 @@ dist
1616

1717
# prisma
1818
src/generated/prisma/
19+
20+
coverage

‎.knip.jsonc‎

Lines changed: 1 addition & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,6 @@
11
{
22
"$schema": "https://unpkg.com/knip@5/schema-jsonc.json",
3-
"entry": [
4-
"src/index.ts"
5-
// // CDK
6-
// "bin/paragest.ts",
7-
// "lib/paragest-stack.ts",
8-
// "reset.d.ts",
9-
//
10-
// // Our scripts
11-
// "bin/list-failures.mts",
12-
// "bin/replay-s3-event.mts",
13-
//
14-
// // Lambdas
15-
// "src/tsconfig.json",
16-
// "src/*.ts",
17-
// "src/common/*.ts",
18-
// "src/cron/*.ts",
19-
// "src/audio/*.ts",
20-
// "src/image/*.ts",
21-
// "src/video/*.ts",
22-
// "src/other/*.ts",
23-
// "src/tsconfig.json"
24-
],
25-
"ignore": ["example/src/index.express.ts", "example/src/index.fastify.ts"],
3+
"ignore": ["example/src/index.express.ts", "example/src/index.fastify.ts", "scripts/loadEntities.ts"],
264
"ignoreDependencies": [
275
// Used in prisma.schema, not directly in code
286
"prisma-json-types-generator",

‎CLAUDE.md‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
# AROCAPI Project Guidelines
2+
3+
This document provides guidance for working with the AROCAPI project using Claude Code.
4+
5+
## Project Overview
6+
7+
AROCAPI is a TypeScript/Fastify API for RO-Crate data management with:
8+
9+
- **Framework**: Fastify with TypeScript
10+
- **Database**: MySQL with Prisma ORM
11+
- **Search**: OpenSearch integration
12+
- **Testing**: Vitest with 95% coverage requirement
13+
14+
## Code Style
15+
16+
### General
17+
18+
- Use 2 spaces for indentation
19+
- Prefer single quotes for strings, double quotes for HTML attributes
20+
- Prefer US spelling (e.g., color, organize)
21+
- Use ES modules (import/export)
22+
23+
### TypeScript
24+
25+
- Use strict TypeScript configuration
26+
- Prefer arrow functions for component definitions
27+
- Use Fastify's type providers for route typing
28+
- Prefer forEach/map/filter/reduce over for loops
29+
- Add newlines before return and process.exit
30+
31+
### Dependencies
32+
33+
- Use `pnpm` for package management
34+
- Never edit package.json scripts directly, use pnpm commands
35+
- Use zod v4 for validation
36+
- Follow Fastify conventions for plugins and routes
37+
38+
## Testing Guidelines
39+
40+
### Testing Strategy
41+
42+
The project uses a comprehensive testing approach with:
43+
44+
- **Unit tests**: Fast, isolated tests with mocked dependencies
45+
- **Integration tests**: Full API tests with real database/OpenSearch
46+
- **OpenAPI validation**: Ensures API contract compliance
47+
- **95% coverage requirement**: Enforced in CI pipeline
48+
49+
### Test Commands
50+
51+
```bash
52+
pnpm run test # Run all tests
53+
pnpm run test:watch # Run in watch mode
54+
pnpm run test:ui # Interactive UI
55+
pnpm run test:coverage # With coverage report
56+
```
57+
58+
### Test Environment
59+
60+
- **Database**: localhost:3307 (catalog_test)
61+
- **OpenSearch**: localhost:9201
62+
- **Services**: Use docker-compose.test.yml
63+
- **Setup**: Automated via src/test/integration.setup.ts
64+
65+
### Writing Tests
66+
67+
1. **Unit tests**: Place in `src/**/*.test.ts` alongside source
68+
2. **Integration tests**: Use `src/test/integration.test.ts`
69+
3. **Mock external dependencies** in unit tests
70+
4. **Use real services** in integration tests with cleanup
71+
5. **Test both success and error paths**
72+
6. **Use snapshots** for complex response validation
73+
74+
### Coverage Requirements
75+
76+
- Minimum 95% for lines, functions, branches, statements
77+
- Excluded: generated code, dist, example, config files
78+
- CI pipeline fails if coverage drops below threshold
79+
- View reports: `open coverage/index.html`
80+
81+
## Development Workflow
82+
83+
### Local Development
84+
85+
1. Install dependencies: `pnpm install`
86+
2. Start services: `docker compose up -d`
87+
3. Generate Prisma client: `pnpm run generate`
88+
4. Start development: `pnpm run dev`
89+
90+
### Before Committing
91+
92+
1. Run linting: `pnpm run lint:biome && pnpm run lint:types`
93+
2. Run tests: `pnpm run test`
94+
3. Check coverage: `pnpm run test:coverage`
95+
4. Ensure all checks pass
96+
97+
### CI/CD Pipeline
98+
99+
- **Triggers**: Pull requests to main branch
100+
- **Services**: MySQL and OpenSearch via GitHub Actions
101+
- **Checks**: Linting, type checking, tests, coverage
102+
- **Requirements**: All checks must pass, 95% coverage minimum
103+
104+
## Project Structure
105+
106+
```
107+
src/
108+
├── app.ts # Main Fastify application
109+
├── routes/ # API route handlers
110+
│ ├── entity.ts # Single entity operations
111+
│ ├── entities.ts # Entity listing/filtering
112+
│ └── search.ts # OpenSearch operations
113+
├── utils/ # Utility functions
114+
│ └── errors.ts # Error handling helpers
115+
├── generated/ # Prisma generated files (excluded from tests)
116+
└── test/ # Integration test setup
117+
├── integration.setup.ts
118+
├── integration.test.ts
119+
└── openapi.test.ts
120+
```
121+
122+
## Key Dependencies
123+
124+
### Runtime
125+
126+
- **fastify**: Web framework
127+
- **@prisma/client**: Database ORM
128+
- **@opensearch-project/opensearch**: Search client
129+
- **zod**: Schema validation (v4)
130+
- **fastify-type-provider-zod**: Fastify Zod integration
131+
132+
### Development
133+
134+
- **vitest**: Testing framework
135+
- **@vitest/coverage-v8**: Coverage reporting
136+
- **typescript**: Type checking
137+
- **@biomejs/biome**: Linting and formatting
138+
- **openapi-backend**: OpenAPI validation
139+
- **prisma**: Database toolkit
140+
141+
## API Design
142+
143+
### Route Structure
144+
145+
- `GET /entity/:id` - Retrieve single entity
146+
- `GET /entities` - List/filter entities with pagination
147+
- `POST /search` - OpenSearch queries with faceting
148+
149+
### Error Handling
150+
151+
- Use consistent error response format
152+
- Implement proper HTTP status codes
153+
- Log errors appropriately
154+
- Use utility functions from `src/utils/errors.ts`
155+
156+
### Validation
157+
158+
- Use Zod schemas for request/response validation
159+
- Leverage Fastify's type providers
160+
- Validate against OpenAPI specification
161+
- Handle validation errors gracefully
162+
163+
## Database Management
164+
165+
### Prisma Operations
166+
167+
```bash
168+
pnpm run generate # Generate client
169+
pnpm run db:migrate # Run migrations
170+
pnpm run dbconsole # Access database console
171+
```
172+
173+
### Test Database
174+
175+
- Separate instance on port 3307
176+
- Automated setup/cleanup in tests
177+
- Uses test-specific environment variables
178+
179+
## OpenSearch Integration
180+
181+
### Development
182+
183+
- Service runs on localhost:9200
184+
- Test instance on localhost:9201
185+
- Index management handled in application
186+
187+
### Search Features
188+
189+
- Basic and advanced query modes
190+
- Faceted search with aggregations
191+
- Geospatial search capabilities
192+
- Highlighting and scoring
193+
194+
## Troubleshooting
195+
196+
### Common Issues
197+
198+
1. **Test timeouts**: Check service health, increase timeouts
199+
2. **Database errors**: Verify connections, run migrations
200+
3. **Coverage failures**: Check excluded files, add tests
201+
4. **OpenSearch errors**: Verify service status, check mappings
202+
203+
## Best Practices
204+
205+
### Code Quality
206+
207+
1. Follow TypeScript strict mode
208+
2. Use proper error handling
209+
3. Implement comprehensive logging
210+
4. Write self-documenting code
211+
5. Follow established patterns
212+
213+
### Testing
214+
215+
1. Maintain high test coverage (95%+)
216+
2. Test both happy and error paths
217+
3. Use appropriate test types (unit vs integration)
218+
4. Keep tests fast and reliable
219+
5. Clean up test data properly
220+
221+
### Performance
222+
223+
1. Use appropriate database queries
224+
2. Implement proper caching strategies
225+
3. Monitor OpenSearch performance
226+
4. Optimize for common use cases
227+
5. Profile and measure improvements
228+
229+
### Security
230+
231+
1. Validate all inputs
232+
2. Use parameterized queries
233+
3. Implement proper authentication/authorization
234+
4. Log security events
235+
5. Keep dependencies updated
236+
237+
---
238+
239+
This document should be updated as the project evolves and new patterns emerge.
240+

0 commit comments

Comments
 (0)