Testing Skill

This skill helps you run, write, and troubleshoot tests in the DBHub project.

Test Commands

pnpm test              # Run all tests (unit + integration)
pnpm test:unit         # Unit tests only (no Docker needed)
pnpm test:watch        # Interactive watch mode
pnpm test:integration  # Integration tests only (requires Docker)

Run a specific test file:

pnpm test src/connectors/__tests__/postgres.integration.test.ts
pnpm test src/utils/__tests__/allowed-keywords.test.ts

Run tests matching a name pattern:

pnpm test -- --testNamePattern="PostgreSQL"

Verbose output for debugging:

pnpm test:integration --reporter=verbose

Test Architecture

Vitest is configured with two projects in vitest.config.ts:

• unit: All *.test.ts files excluding *integration* in the filename
• integration: Only *integration*.test.ts files

This means the naming convention matters — integration tests MUST have integration in their filename to be correctly categorized.

Test File Locations

Unit tests (~20 files, no Docker needed):

• src/utils/__tests__/ — Utility function tests (SQL parsing, DSN obfuscation, SSH config, allowed keywords, identifier quoting, parameter mapping, row limiting, safe URL, config watcher, AWS RDS signer)
• src/tools/__tests__/ — Tool handler tests (execute-sql, search-objects, custom-tool-handler)
• src/config/__tests__/ — Configuration tests (env parsing, TOML loading)
• src/connectors/__tests__/ — Connector unit tests (dsn-parser, manager)
• src/requests/__tests__/ — Request store tests

Integration tests (~11 files, Docker required):

• src/connectors/__tests__/postgres.integration.test.ts
• src/connectors/__tests__/mysql.integration.test.ts
• src/connectors/__tests__/mariadb.integration.test.ts
• src/connectors/__tests__/sqlserver.integration.test.ts
• src/connectors/__tests__/oracle.integration.test.ts
• src/connectors/__tests__/sqlite.integration.test.ts
• src/connectors/__tests__/postgres-ssh.integration.test.ts
• src/connectors/__tests__/multi-sqlite-sources.integration.test.ts
• src/__tests__/json-rpc-integration.test.ts
• src/api/__tests__/sources.integration.test.ts
• src/api/__tests__/requests.integration.test.ts
• src/config/__tests__/ssh-config-integration.test.ts

IntegrationTestBase

Database connector integration tests extend IntegrationTestBase<TContainer> from src/connectors/__tests__/shared/integration-test-base.ts. This abstract class provides:

• Lifecycle: Container start in beforeAll (120s timeout) → connect → setup test data → run tests → cleanup in afterAll
• Shared test suites: createConnectionTests(), createSchemaTests(), createTableTests(), createSQLExecutionTests(), createStoredProcedureTests(), createCommentTests(), createErrorHandlingTests()
• Standard test data: users table (id, name, email, age) + orders table (id, user_id, amount) + test_schema.products

To add a new database connector test, extend this class and implement:

• createContainer() — Start the Testcontainers instance
• createConnector() — Create the database connector
• setupTestData(connector) — Populate test tables

Test Fixtures

Located in src/__fixtures__/:

• helpers.ts — Utilities: fixtureTomlPath(), loadFixtureConfig(), setupManagerWithFixture()
• toml/multi-sqlite.toml — Three in-memory SQLite databases (database_a, database_b, database_c)
• toml/readonly-maxrows.toml — Sources with readonly/max_rows tool configurations

Usage:

import { setupManagerWithFixture, FIXTURES } from '../../__fixtures__/helpers.js';
const manager = await setupManagerWithFixture(FIXTURES.MULTI_SQLITE);
// ... test ...
await manager.disconnect();

Mocking Patterns

Unit tests use vitest mocking:

vi.mock('../../connectors/manager.js');  // Mock ConnectorManager
vi.mocked(ConnectorManager.getCurrentConnector).mockReturnValue(mockConnector);

SSH tunnel tests mock SSHTunnel.prototype.establish to avoid real SSH connections while testing config passing.

Integration Testing

Integration tests use Testcontainers to run real database instances in Docker.

Prerequisites

Before running integration tests:

1. Docker is installed and running: docker ps
2. Sufficient Docker memory (4GB+ recommended, especially for SQL Server)
3. Network access to pull Docker images

Database Images

Troubleshooting

Container Startup Failures

docker ps                    # Verify Docker is running
docker system df             # Check disk space
docker pull postgres:15-alpine  # Manually pull images

SQL Server Timeouts

SQL Server containers are the slowest to start (3-5 minutes). Run them separately and ensure Docker has 4GB+ memory:

pnpm test src/connectors/__tests__/sqlserver.integration.test.ts

Test Isolation Issues

Each integration test manages its own container lifecycle. If containers leak, clean up:

docker ps -a | grep testcontainers  # Find leaked containers
docker container prune               # Clean up stopped containers

"Hook timed out in 10000ms" in afterAll

All tests pass but the suite is marked failed at its afterAll (seen on MariaDB and postgres-ssh in CI). Teardown is container.stop(), which runs docker stop -t 0 followed by docker rm -v (removing the data volume). On a shared Docker daemon that is simultaneously pulling/extracting the Oracle or SQL Server image, that removal can exceed Vitest's 10s default hook timeout. The integration project sets hookTimeout: 60_000 in vitest.config.ts for this reason — do not pass a shorter timeout to afterAll, and if you add a suite with its own teardown, let it use the project default rather than the Vitest default.

CI Failures

The CI workflow (.github/workflows/run-tests.yml) runs unit and integration tests as separate parallel jobs on PR events. Unit tests don't need Docker; integration tests verify Docker availability first. Check the specific job that failed.

Adding New Tests

Unit test: Create src/{module}/__tests__/{name}.test.ts — will auto-run with pnpm test:unit.

Integration test: Create src/{module}/__tests__/{name}.integration.test.ts — the integration in the filename is what routes it to pnpm test:integration.

New connector test: Extend IntegrationTestBase, implement the three abstract methods, and call the shared test suite methods.