Three lines of code. No config files.
One config entry. Every test guarded.
@@ -452,13 +452,13 @@
Catch N+1 queries before they hit production
01
Install
npm install qguard
-
No plugins to register. No setup files to create. No environment variables to set.
+
No plugin package, generated setup file, or environment variable required.
02
-
Wrap your test
-
await assertNoNPlusOne(() => handler(req, res))
-
Import from queryguard/vitest or queryguard/jest. One function call wraps your handler.
+
Enable the suite
+
setupFiles: [qguardSetup]
+
Import qguardSetup from qguard/vitest. Every test is guarded automatically.
03
diff --git a/docs/plans/2026-08-31-vitest-auto-setup.md b/docs/plans/2026-08-31-vitest-auto-setup.md
new file mode 100644
index 0000000..0fa8c22
--- /dev/null
+++ b/docs/plans/2026-08-31-vitest-auto-setup.md
@@ -0,0 +1,37 @@
+# Vitest automatic setup
+
+Date: 2026-08-31
+Issue: [#9](https://github.com/oniani1/queryguard/issues/9)
+
+## Goal
+
+Allow a Vitest suite to enforce qguard for every test from one configuration entry:
+
+```ts
+import { qguardSetup } from 'qguard/vitest'
+
+export default defineConfig({
+ test: {
+ setupFiles: [qguardSetup],
+ },
+})
+```
+
+The existing `qguard/vitest` assertion helpers remain explicit and side-effect free. Importing
+`qguardSetup` loads the `qguard/vitest/setup` entry point, which installs the database hooks once,
+opens an isolated tracking context for each test, dispatches configured notifications, and fails
+the affected test with `QueryGuardError` when the context contains an N+1 detection.
+
+## Plan
+
+- [x] Add a runner-level failing test proving setup-file enforcement and clean-test behavior.
+- [x] Implement the Vitest lifecycle adapter with per-test `AsyncLocalStorage` isolation.
+- [x] Publish the `qguard/vitest/setup` package export and verify the packed artifact.
+- [x] Document automatic setup, configuration, opt-out, and interaction with explicit assertions.
+- [x] Run formatting, type checking, linting, unit tests, build, and relevant integration tests.
+
+## Non-goals
+
+- Baseline or acknowledgement files.
+- Jest, Mocha, or other runner adapters.
+- Changes to the N+1 detection algorithm.
diff --git a/package.json b/package.json
index f4dd12c..e787055 100644
--- a/package.json
+++ b/package.json
@@ -29,7 +29,9 @@
"typescript"
],
"types": "./dist/index.d.ts",
- "sideEffects": false,
+ "sideEffects": [
+ "./dist/integrations/vitest-setup.js"
+ ],
"exports": {
".": {
"import": "./dist/index.js",
@@ -41,6 +43,11 @@
"require": "./dist/integrations/vitest.js",
"types": "./dist/integrations/vitest.d.ts"
},
+ "./vitest/setup": {
+ "import": "./dist/integrations/vitest-setup.js",
+ "require": "./dist/integrations/vitest-setup.js",
+ "types": "./dist/integrations/vitest-setup.d.ts"
+ },
"./jest": {
"import": "./dist/integrations/jest.js",
"require": "./dist/integrations/jest.js",
diff --git a/site/index.html b/site/index.html
index ee61c91..e12fa02 100644
--- a/site/index.html
+++ b/site/index.html
@@ -444,7 +444,7 @@
Catch N+1 queries before they hit production
How it works
-
Three lines of code. No config files.
+
One config entry. Every test guarded.
QueryGuard intercepts pg.Client and pg.Pool queries at the driver level. Every query is fingerprinted and tracked per async context. If the same query repeats above a threshold, your test fails.
@@ -452,13 +452,13 @@
Catch N+1 queries before they hit production
01
Install
npm install qguard
-
No plugins to register. No setup files to create. No environment variables to set.
+
No plugin package, generated setup file, or environment variable required.
02
-
Wrap your test
-
await assertNoNPlusOne(() => handler(req, res))
-
Import from queryguard/vitest or queryguard/jest. One function call wraps your handler.
+
Enable the suite
+
setupFiles: [qguardSetup]
+
Import qguardSetup from qguard/vitest. Every test is guarded automatically.
03
diff --git a/src/integrations/vitest-setup.ts b/src/integrations/vitest-setup.ts
new file mode 100644
index 0000000..5f68906
--- /dev/null
+++ b/src/integrations/vitest-setup.ts
@@ -0,0 +1,38 @@
+import { afterEach, beforeEach } from 'vitest'
+import { detect } from '../core/detector.js'
+import { dispatchNotifications } from '../core/notify.js'
+import { createContext, trackingAls } from '../core/tracker.js'
+import type { TrackingContext } from '../core/tracker.js'
+import { install } from '../drivers/install.js'
+import { QueryGuardError } from './shared.js'
+
+const contexts = new WeakMap
()
+
+await install()
+
+// Keep this hook synchronous: entering ALS after an await does not propagate the store back to
+// Vitest's runner, so queries from the test would escape the context.
+beforeEach((testContext) => {
+ const context = createContext()
+ contexts.set(testContext, context)
+ trackingAls.enterWith(context)
+})
+
+afterEach(async (testContext) => {
+ const context = contexts.get(testContext)
+ contexts.delete(testContext)
+ if (!context) return
+
+ const report = detect(context)
+ if (report.detections.length === 0) return
+
+ await dispatchNotifications({
+ report,
+ environment: 'test',
+ test: {
+ name: testContext.task.name,
+ file: testContext.task.file.filepath,
+ },
+ })
+ throw new QueryGuardError(report)
+})
diff --git a/src/integrations/vitest.ts b/src/integrations/vitest.ts
index 090791e..63cfdc3 100644
--- a/src/integrations/vitest.ts
+++ b/src/integrations/vitest.ts
@@ -1,3 +1,5 @@
+import { fileURLToPath } from 'node:url'
+
export type {
AssertOptions,
AssertScalingOptions,
@@ -8,3 +10,6 @@ export { QueryGuardError, ScalingError } from './shared.js'
export { runAssertNoNPlusOne as assertNoNPlusOne } from './shared.js'
export { runQueryBudget as queryBudget } from './shared.js'
export { runAssertScaling as assertScaling } from './shared.js'
+
+/** Absolute path for Vitest's `test.setupFiles` configuration. */
+export const qguardSetup = fileURLToPath(new URL('./vitest-setup.js', import.meta.url))
diff --git a/test/fixtures/vitest-auto-setup/concurrency.fixture.ts b/test/fixtures/vitest-auto-setup/concurrency.fixture.ts
new file mode 100644
index 0000000..2c64206
--- /dev/null
+++ b/test/fixtures/vitest-auto-setup/concurrency.fixture.ts
@@ -0,0 +1,17 @@
+import { expect, test } from 'vitest'
+import { recordQuery } from '../../../src/core/tracker.js'
+
+async function recordOneQuery(): Promise {
+ await new Promise((resolve) => setTimeout(resolve, 5))
+ recordQuery('SELECT * FROM users WHERE id = 1', 1)
+}
+
+test.concurrent('isolates the first concurrent test', async () => {
+ await recordOneQuery()
+ expect(true).toBe(true)
+})
+
+test.concurrent('isolates the second concurrent test', async () => {
+ await recordOneQuery()
+ expect(true).toBe(true)
+})
diff --git a/test/fixtures/vitest-auto-setup/detection.fixture.ts b/test/fixtures/vitest-auto-setup/detection.fixture.ts
new file mode 100644
index 0000000..5f92582
--- /dev/null
+++ b/test/fixtures/vitest-auto-setup/detection.fixture.ts
@@ -0,0 +1,23 @@
+import { expect, test } from 'vitest'
+import { configure } from '../../../src/core/config.js'
+import { recordQuery } from '../../../src/core/tracker.js'
+
+configure({
+ onDetection: [
+ ({ test: metadata }) => {
+ console.log(`[qguard notification] ${metadata?.name} @ ${metadata?.file}`)
+ },
+ ],
+})
+
+test('passes a clean test without an explicit qguard assertion', () => {
+ recordQuery('SELECT * FROM users WHERE id = 1', 1)
+ expect(true).toBe(true)
+})
+
+test('fails an N+1 without an explicit qguard assertion', async () => {
+ recordQuery('SELECT * FROM users WHERE id = 1', 1)
+ await new Promise((resolve) => queueMicrotask(resolve))
+ recordQuery('SELECT * FROM users WHERE id = 2', 1)
+ expect(true).toBe(true)
+})
diff --git a/test/fixtures/vitest-auto-setup/hooks.fixture.ts b/test/fixtures/vitest-auto-setup/hooks.fixture.ts
new file mode 100644
index 0000000..61e51a4
--- /dev/null
+++ b/test/fixtures/vitest-auto-setup/hooks.fixture.ts
@@ -0,0 +1,16 @@
+import { afterEach, beforeEach, expect, test } from 'vitest'
+import { recordQuery } from '../../../src/core/tracker.js'
+
+beforeEach(() => {
+ recordQuery('SELECT * FROM users WHERE id = 1', 1)
+})
+
+afterEach(() => {
+ recordQuery('SELECT * FROM users WHERE id = 3', 1)
+})
+
+test('tracks queries across the complete per-test lifecycle', async () => {
+ await new Promise((resolve) => queueMicrotask(resolve))
+ recordQuery('SELECT * FROM users WHERE id = 2', 1)
+ expect(true).toBe(true)
+})
diff --git a/test/fixtures/vitest-auto-setup/vitest.config.ts b/test/fixtures/vitest-auto-setup/vitest.config.ts
new file mode 100644
index 0000000..62faae0
--- /dev/null
+++ b/test/fixtures/vitest-auto-setup/vitest.config.ts
@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config'
+import { qguardSetup } from '../../../src/integrations/vitest.js'
+
+export default defineConfig({
+ test: {
+ include: ['test/fixtures/vitest-auto-setup/*.fixture.ts'],
+ setupFiles: [qguardSetup],
+ },
+})
diff --git a/test/unit/vitest-setup.test.ts b/test/unit/vitest-setup.test.ts
new file mode 100644
index 0000000..ca1f046
--- /dev/null
+++ b/test/unit/vitest-setup.test.ts
@@ -0,0 +1,57 @@
+import { spawnSync } from 'node:child_process'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { qguardSetup } from '../../src/integrations/vitest.js'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
+const vitestCli = path.join(root, 'node_modules/vitest/vitest.mjs')
+const config = path.join(root, 'test/fixtures/vitest-auto-setup/vitest.config.ts')
+
+function runFixture(filename: string) {
+ const result = spawnSync(process.execPath, [vitestCli, 'run', '--config', config, filename], {
+ cwd: root,
+ encoding: 'utf8',
+ env: { ...process.env, FORCE_COLOR: '0' },
+ })
+
+ return {
+ status: result.status,
+ output: `${result.stdout}${result.stderr}`,
+ }
+}
+
+describe('qguard/vitest/setup', () => {
+ it('exports the built setup-file path for Vitest configuration', () => {
+ expect(path.isAbsolute(qguardSetup)).toBe(true)
+ expect(qguardSetup).toMatch(/[/\\]integrations[/\\]vitest-setup\.js$/)
+ })
+
+ it('fails only the test that produces an N+1 query pattern', () => {
+ const result = runFixture('detection.fixture.ts')
+
+ expect(result.status).toBe(1)
+ expect(result.output).toContain('1 failed | 1 passed')
+ expect(result.output).toContain('QueryGuardError: N+1 query detected')
+ expect(result.output).toContain('fails an N+1 without an explicit qguard assertion')
+ expect(result.output).toContain(
+ '[qguard notification] fails an N+1 without an explicit qguard assertion',
+ )
+ expect(result.output).toContain('detection.fixture.ts')
+ })
+
+ it('isolates concurrent tests from one another', () => {
+ const result = runFixture('concurrency.fixture.ts')
+
+ expect(result.status).toBe(0)
+ expect(result.output).toContain('2 passed')
+ })
+
+ it('tracks queries from user beforeEach and afterEach hooks', () => {
+ const result = runFixture('hooks.fixture.ts')
+
+ expect(result.status).toBe(1)
+ expect(result.output).toContain('QueryGuardError: N+1 query detected')
+ expect(result.output).toContain('Repeated query executed 3 times')
+ })
+})