/testing

name: testing
description: Run and troubleshoot tests for DBHub, including unit tests, integration tests with Testcontainers, and database-specific tests. Use when asked to run tests, fix test failures, debug integration tests, troubleshoot Docker/database container issues, or add new tests. Also use when verifying code changes work correctly or when CI test failures need investigation.

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](https://testcontainers.com/) 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

| Database | Image | Notes | |----------|-------|-------| | PostgreSQL | `postgres:15-alpine` | Fast startup | | MySQL | `@testcontainers/mysql` | Supports IAM auth testing | | MariaDB | `@testcontainers/mariadb` | Supports IAM auth testing | | SQL Server | `@testcontainers/mssqlserver` | Slow startup (3-5 min), needs 4GB+ RAM | | Oracle | `@testcontainers/oraclefree` (`gvenzl/oracle-free:23-slim-faststart`) | ~1.2GB pull, 1-2 min startup, needs 2GB+ RAM | | SQLite | No container needed | In-memory or file-based |

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:

d