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/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:
-
Docker is installed and running: docker ps
-
Sufficient Docker memory (4GB+ recommended, especially for SQL Server)
-
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
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:
docker ps -a | grep testcontainers # Find leaked containers docker container prune # Clean up stopped containers
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.