Skip to content

TESTING.md

Latest commit

 

History

History
343 lines (235 loc) · 8.64 KB

TESTING.md

File metadata and controls

343 lines (235 loc) · 8.64 KB
Raw

Testing Strategy & Guidelines

Wiki reference (diagrams): Development

This document outlines the testing strategy, practices, and guidelines for ShadowCheckStatic.

Quick Test Run

npm test
npm run test:integration

Requires database connectivity and secrets available via AWS Secrets Manager (or explicit local overrides).

Test Framework

The project uses Jest as the primary testing framework.

# Run all tests
npm test

# Run with coverage
npm run test:cov

# Lint and format check
npm run lint
npm run format:check

Test Structure

tests/
├── setup.ts                 # Test setup and configuration
├── sql-injection-fixes.test.ts
├── wigle-import-auth.test.js
├── api/
│   └── dashboard.test.ts   # API endpoint tests
├── helpers/
│   └── integrationEnv.ts    # Integration test helpers
├── integration/
│   ├── README.md           # Integration test documentation
│   ├── explorer-v2.test.ts
│   ├── like-escaping.test.ts
│   ├── networks-data-integrity.test.ts
│   ├── observability.test.ts
│   ├── route-refactoring-verification.test.ts
│   └── sql-injection-fixes.test.ts
└── unit/
    ├── escapeSQL.test.ts
    ├── filterQueryBuilder.test.ts
    ├── filters-systematic.test.ts
    ├── health.test.ts
    ├── observationCountMin-investigation.test.ts
    └── requestId.test.ts

Test Types

1. Unit Tests (tests/unit/)

Unit tests verify individual functions and modules in isolation.

Location: tests/unit/

Naming Convention: *.test.ts

Examples:

Best Practices:

  • Mock external dependencies (database, file system, network calls)
  • Test edge cases and error conditions
  • Keep tests fast (< 100ms each)
  • Use descriptive test names

2. Integration Tests (tests/integration/)

Integration tests verify the interaction between multiple components or API endpoints.

Location: tests/integration/

Naming Convention: *.test.ts

Examples:

See also: integration/README.md

3. API Tests (tests/api/)

API tests verify REST endpoint behavior.

Location: tests/api/

Examples:

4. Helper Files (tests/helpers/)

Utilities for test setup and configuration.

Examples:

Test Configuration

Jest Configuration

See jest.config.js for Jest configuration.

module.exports = {
  testEnvironment: 'node',
  roots: ['<rootDir>/tests'],
  testMatch: ['**/*.test.ts', '**/*.test.js'],
  collectCoverageFrom: ['server/**/*.ts', '!server/**/*.d.ts'],
  coverageDirectory: 'coverage',
  // ... more config
};

Test Setup

The tests/setup.ts file contains:

  • Mock setups- Global test configuration
  • Environment variable defaults
  • Database connection handling

Writing Tests

Unit Test Example

import { escapeSQL } from '../server/src/utils/escapeSQL';

describe('escapeSQL', () => {
  it('should escape single quotes', () => {
    const input = "O'Reilly";
    const result = escapeSQL(input);
    expect(result).toBe("O''Reilly");
  });

  it('should escape percent and underscore for LIKE', () => {
    const input = '100%_match';
    const result = escapeSQL(input, true);
    expect(result).toBe('100\\%\\_match');
  });
});

Integration Test Example

import request from 'supertest';
import { createApp } from '../server/src/utils/appInit';

describe('Explorer API', () => {
  let app: Express.Application;

  beforeAll(async () => {
    app = await createApp();
  });

  it('should return networks with 200', async () => {
    const response = await request(app).get('/api/v1/explorer/networks').expect(200);

    expect(response.body).toHaveProperty('data');
    expect(Array.isArray(response.body.data)).toBe(true);
  });
});

Coverage Requirements

Note: The global minimums are enforced in jest.config.js and were recently raised after a major test enhancement drive (April 2026).

Type Minimum (Enforced) Target
Statements 60% 80%
Branches 60% 70%
Functions 60% 80%
Lines 60% 80%

Run npm run test:cov to generate coverage reports.

Client-Side Tests

Client-side tests are located in:

Example:

Security Testing

SQL Injection Testing

Special attention is given to SQL injection prevention:

All user inputs must be properly escaped. See server/src/utils/escapeSQL.ts.

API Security Tests

Test cases include:

  • Authentication bypass attempts
  • Authorization failures
  • Input validation failures
  • Rate limiting behavior

Running Tests

Commands

# Run all tests
npm test

# Run specific test file
npm test -- tests/unit/filterQueryBuilder.test.ts

# Run with coverage
npm run test:cov

# Watch mode
npm test -- --watch

# Run integration tests only (requires live DB at DB_NAME=shadowcheck_test)
RUN_INTEGRATION_TESTS=true DB_NAME=shadowcheck_test npm test

# Focused sibling integration tests
RUN_INTEGRATION_TESTS=true DB_NAME=shadowcheck_test npx jest --testPathPattern="siblingRuleQuality|siblingCoverage" --no-coverage

# Focused sibling unit tests
DB_NAME=shadowcheck_test npx jest tests/unit/siblingDetectionQueries.test.ts tests/unit/adminSiblingService.test.ts --no-coverage

CI/CD Integration

Tests run automatically on:

Test Data Management

Fixtures

Test fixtures are managed in:

  • tests/fixtures/ (if exists)
  • Inline in test files
  • Database seeding scripts

Mock Data

Use mocking for:

  • Database queries
  • External API calls
  • File system operations
  • Network requests

Best Practices

DO

  • ✅ Write tests before fixing bugs (TDD recommended)
  • ✅ Use descriptive test names
  • ✅ Test edge cases and error conditions
  • ✅ Keep tests independent and isolated
  • ✅ Use setup/teardown functions appropriately
  • ✅ Aim for high coverage on critical paths

DON'T

  • ❌ Commit tests that fail
  • ❌ Skip tests without a good reason
  • ❌ Test implementation details (test behavior)
  • ❌ Make tests dependent on execution order
  • ❌ Use hardcoded environment values

Debugging Tests

Common Issues

  1. Timeout errors: Increase timeout for slow operations

    it('should handle slow query', async () => {
  jest.setTimeout(30000);
  // ...
}, 30000);

  2. Database connection errors: Ensure test database is running

    # Check database connection
npm run docker:up

  3. Memory issues: Run tests sequentially

    npm test -- --runInBand

Continuous Integration

See the CI configuration:

Related Documentation