psf-bch-api/dev-docs/test-plan-for-rest2nostr.plan.md

# Test Plan for REST2NOSTR Application

## Overview

Create unit and integration tests for the REST2NOSTR Express.js application following patterns from `tests/testing-example-code/`. Tests will use mocha, chai, and sinon, and cover all code paths exercised by the examples in `/app/examples/`.

## Test Structure

Create test directory structure:

- `app/test/unit/` - Unit tests with mocked dependencies
- `app/test/integration/` - Integration tests with real dependencies
- `app/test/unit/mocks/` - Mock data for unit tests

## Unit Tests

### 1. Entity Tests (`test/unit/entities/`)

- **event-unit.js**: Test Event entity validation and serialization
- Test `isValid()` with valid events
- Test `isValid()` with invalid events (missing fields, wrong types, wrong lengths)
- Test `toJSON()` serialization
- Use mock event data from `mocks/event-mocks.js`

### 2. Use Case Tests (`test/unit/use-cases/`)

- **publish-event-unit.js**: Test PublishEventUseCase
- Mock NostrRelayAdapter.sendEvent()
- Test successful event publishing
- Test invalid event rejection
- Test adapter error handling
- Use mocks from `mocks/nostr-relay-mocks.js`

- **query-events-unit.js**: Test QueryEventsUseCase
- Mock NostrRelayAdapter.sendReq() and sendClose()
- Test successful query with events returned
- Test query timeout handling
- Test CLOSED message handling
- Test EOSE handling

- **manage-subscription-unit.js**: Test ManageSubscriptionUseCase
- Mock NostrRelayAdapter.sendReq() and sendClose()
- Test subscription creation
- Test subscription closure
- Test duplicate subscription prevention
- Test handler callbacks (onEvent, onEose, onClosed)

### 3. Controller Tests (`test/unit/controllers/`)

- **event-controller-unit.js**: Test EventRESTControllerLib
- Mock UseCases.publishEvent.execute()
- Test POST /event with valid event data
- Test POST /event with missing event data
- Test error handling
- Use Express request/response mocks

- **req-controller-unit.js**: Test ReqRESTControllerLib
- Mock UseCases.queryEvents.execute() and manageSubscription methods
- Test GET /req/:subId with filters (JSON string and parsed)
- Test GET /req/:subId with individual query params
- Test POST /req/:subId for SSE subscription
- Test DELETE /req/:subId for closing subscription
- Test error handling for invalid filters
- Test missing subscription ID validation

### 4. Adapter Tests (`test/unit/adapters/`)

- **nostr-relay-unit.js**: Test NostrRelayAdapter
- Mock WebSocket connections
- Test connection establishment
- Test sendEvent() and OK response handling
- Test sendReq() and EVENT/EOSE/CLOSED message handling
- Test sendClose()
- Test message queuing when disconnected
- Test reconnection logic
- Test error handling

### 5. Server Tests (`test/unit/bin/`)

- **server-unit.js**: Test Server class
- Mock Express app, Controllers, and adapters
- Test server initialization
- Test middleware attachment
- Test route attachment
- Test error handling
- Test health check endpoint

## Integration Tests

### 1. API Endpoint Tests (`test/integration/api/`)

- **event-integration.js**: Test POST /event endpoint
- Create a test server instance
- Test publishing kind 0 event (profile metadata) - covers example 01
- Test publishing kind 1 event (text post) - covers example 03
- Test publishing kind 3 event (follow list) - covers example 06
- Test publishing kind 7 event (reaction/like) - covers example 07
- Test invalid event rejection
- Use real Nostr relay connection (may need test relay or mock relay)

- **req-integration.js**: Test GET /req/:subId endpoint
- Create a test server instance
- Test querying kind 1 events (posts) - covers examples 02, 04
- Test querying kind 3 events (follow list) - covers example 05
- Test with various filter combinations
- Test with filters as JSON string query param
- Test with individual query params
- Test error handling

- **subscription-integration.js**: Test POST /req/:subId SSE subscription
- Create a test server instance
- Test SSE subscription creation
- Test event streaming
- Test EOSE handling
- Test subscription closure
- Test DELETE /req/:subId endpoint

### 2. Use Case Integration Tests (`test/integration/use-cases/`)

- **publish-event-integration.js**: Test PublishEventUseCase with real adapter
- **query-events-integration.js**: Test QueryEventsUseCase with real adapter
- **manage-subscription-integration.js**: Test ManageSubscriptionUseCase with real adapter

## Mock Data Files

Create mock data files in `test/unit/mocks/`:

- **event-mocks.js**: Mock event data for various event kinds (0, 1, 3, 7)
- **nostr-relay-mocks.js**: Mock responses from Nostr relay (OK, EVENT, EOSE, CLOSED)
- **controller-mocks.js**: Mock Express request/response objects

## Key Considerations

1. **ES Modules**: The app uses ES modules (import/export) while the example uses CommonJS. Tests should use ES modules with `.js` extension and proper import syntax.

2. **Test Environment**: Integration tests will need a running Nostr relay. Consider:

- Using a test relay URL from config
- Or creating a mock WebSocket server for integration tests
- Or documenting that tests require a relay URL in environment

3. **Test Coverage**: Ensure tests cover:

- All endpoints used by examples (POST /event, GET /req/:subId)
- All event kinds (0, 1, 3, 7)
- Error paths and edge cases
- Validation logic

4. **Test Data**: Use the same test keys and data patterns from examples where applicable (e.g., Alice's private key, Bob's public key)

5. **Async Handling**: Properly handle async/await in tests, especially for WebSocket operations and SSE streams

6. **Cleanup**: Ensure proper cleanup of WebSocket connections and subscriptions in tests

## Test Execution

Tests will run using existing npm scripts:

- `npm test` - Runs unit tests with linting and coverage
- `npm run test:integration` - Runs integration tests with extended timeout
- `npm run coverage` - Generates coverage report