--- title: "Integration Tests" description: "Integration tests in this ecosystem serve as the primary validation layer for query builder correctness, type inference, and cross-dialect behavior. By exercising the Drizzle ORM against real-world..." last_updated: "2026-07-02T09:35:19.025577+00:00" canonical_url: "https://www.doc0.app/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/utilities-testing/integration-tests" ---
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-orm/type-tests/mysql/select.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/type-tests/mysql/select.ts) - [drizzle-orm/type-tests/geldb/select.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/type-tests/geldb/select.ts) - [drizzle-orm/type-tests/singlestore/select.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/type-tests/singlestore/select.ts) - [drizzle-orm/type-tests/pg/select.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/type-tests/pg/select.ts) - [drizzle-orm/type-tests/sqlite/select.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/type-tests/sqlite/select.ts) - [integration-tests/vitest.config.ts](https://github.com/blade47/drizzle-orm/blob/main/integration-tests/vitest.config.ts) - [drizzle-orm/type-tests/common/aliased-table.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/type-tests/common/aliased-table.ts) - [integration-tests/package.json](https://github.com/blade47/drizzle-orm/blob/main/integration-tests/package.json) - [drizzle-orm/type-tests/sqlite/set-operators.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/type-tests/sqlite/set-operators.ts) - [drizzle-orm/type-tests/kysely/index.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/type-tests/kysely/index.ts)
Integration tests in this ecosystem serve as the primary validation layer for query builder correctness, type inference, and cross-dialect behavior. By exercising the Drizzle ORM against real-world query patterns, these tests ensure that the TypeScript type definitions align with the generated SQL. The test suite is built on `vitest` and operates in a multi-dialect environment. It addresses the fundamental problem of ensuring that complex query compositions result in the correct TypeScript interface shapes, aligning with the underlying database engine's specifications. At a mechanistic level, these tests use assertion utilities to perform static type checks against query results. This ensures that the Drizzle type engine correctly infers types across various query clauses. The integration suite is highly configurable, allowing for conditional execution of external database tests depending on the presence of environment configuration, which is controlled centrally by the `vitest.config.ts` file. ## Test Environment Configuration The integration test suite is orchestrated by a central `vitest.config.ts` file. This configuration manages the discovery, inclusion, and exclusion of test files across multiple database providers. It specifically implements a "skip-list" mechanism to filter out tests that require external network access or specific database instances when the environment variable `SKIP_EXTERNAL_DB_TESTS` is set. The `defineConfig` utility is used to set global timeout limits for both hooks (`hookTimeout`) and test execution (`testTimeout`), and it explicitly forces sequential execution (`singleThread: true`) to avoid cross-pollination of state between tests that modify the same shared database schema. Sources: [integration-tests/vitest.config.ts:1-85](https://github.com/blade47/drizzle-orm/blob/main/integration-tests/vitest.config.ts#L1-L85) ## Type Verification Mechanism The core of the type-testing subsystem relies on static assertion utilities. This approach verifies that the TypeScript compiler's inferred type for a query result matches a manually defined, expected interface. When a query builder statement is executed, the resulting type is compared against the expected shape. If the SQL query construction changes in a way that alters the resulting type, the assertion check fails at compile-time, providing immediate feedback. > [!TIP] > Use static type assertions for every complex operation to ensure that nullability flags (e.g., `| null`) are propagated correctly. Sources: [drizzle-orm/type-tests/mysql/select.ts:47-55](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/type-tests/mysql/select.ts#L47-L55), [drizzle-orm/type-tests/pg/select.ts:52-60](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/type-tests/pg/select.ts#L52-L60) ## Dynamic Query Builder Lifecycle The tests define and validate the usage of dynamic query builders. These functions take a query builder instance as an argument and apply transformations. The key mechanism here is the `$dynamic()` method, which allows for type-safe chaining even when the builder is passed through various helper functions. The tests ensure that after calling these helpers, the resultant promise resolves to the correctly mapped TypeScript type based on the initial query structure. | Design Choice | Benefit | Cost | | :--- | :--- | :--- | | Static Type Assertions | Prevents runtime errors | Longer compile times | | Dialect-specific Tests | Ensures driver compatibility | Complex organization | | Conditional Skip List | Faster local development | Potential for missed coverage | Sources: [drizzle-orm/type-tests/mysql/select.ts:611-637](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/type-tests/mysql/select.ts#L611-L637) ## Related - [Type Safety Testing](https://www.doc0.app/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/utilities-testing/type-safety-testing) ## Sitemap See the full [sitemap](https://www.doc0.app/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/llms.txt) for all pages in this wiki.