testing

# Testing Skill This skill helps you run, write, and troubleshoot tests in the DBHub project. ## Test Commands ```bash 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: ```bash pnpm test src/connectors/__tests__/postgres.integration.test.ts pnpm test src/utils/__tests__/allowed-keywords.test.ts ``` Run tests matching a name pattern: ```bash pnpm test -- --testNamePattern="PostgreSQL" ``` Verbose output for debugging: ```bash 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: ```typescript 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: ```typescript 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 ```bash 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: ```bash 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: ```bash 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.