02/03: add exercise texts

kettanaito · kettanaito · commit 819a19b1c81f · 2025-04-24T14:52:09.000+02:00
diff --git a/exercises/02.context/03.problem.global-context/README.mdx b/exercises/02.context/03.problem.global-context/README.mdx
@@ -0,0 +1,23 @@
+# Global context
+
+Let's follow up on the previous `createMockDatabase()` fixture and make it better.
+
+By default, when you extend your test context via `test.extend()`, you get a _new `test()` function back_ that you should now explicitly use in tests:
+
+```ts nonumber highlight=1
+import { test } from '../test-extend'
+
+test('...', ({ yourFixture }) => {}) // ✅
+```
+
+Although this explicitness is nice, consistency would be even better. Forgetting to swap the default `test()` with your own can lead to unexpected behaviors, and if you're exposing `test()` globally via `globals: true`, TypeScript won't catch such mistakes either.
+
+But there's another way.
+
+You can apply your custom `test()` _globally_. This will save you one extra line of import in each test file and also guarantee consistent test context everywhere across the board.
+
+## Your task
+
+👨‍💼 That is precisely what you're going to do in this exercise. Follow the instructions in <InlineFile file="text-extend.ts" /> and <InlineFile file="vitest.config.ts" /> to expose your custom test context globally. Once you've got that covered, refactor the existing tests to rely on the global `test()` function instead.
+
+You got this!
diff --git a/exercises/02.context/03.problem.global-context/package.json b/exercises/02.context/03.problem.global-context/package.json
@@ -0,0 +1,14 @@
+{
+  "type": "module",
+  "name": "exercises_02.context_03.problem.global-context",
+  "scripts": {
+    "test": "vitest"
+  },
+  "devDependencies": {
+    "vite": "^6.2.6",
+    "vitest": "^3.1.1"
+  },
+  "dependencies": {
+    "sqlite3": "^5.1.7"
+  }
+}
diff --git a/exercises/02.context/03.problem.global-context/src/database.ts b/exercises/02.context/03.problem.global-context/src/database.ts
@@ -0,0 +1,19 @@
+import sqlite3, { type Database } from 'sqlite3'
+
+export class DatabaseClient {
+	constructor(private readonly db: Database) {}
+
+	public async query(query: string, params: Array<unknown>): Promise<any> {
+		return new Promise((resolve, reject) => {
+			this.db.get(query, params, function (error, row) {
+				if (error) {
+					return reject(error)
+				}
+
+				resolve(row)
+			})
+		})
+	}
+}
+
+export const client = new DatabaseClient(new sqlite3.Database(':memory:'))
diff --git a/exercises/02.context/03.problem.global-context/src/query-user.test.ts b/exercises/02.context/03.problem.global-context/src/query-user.test.ts
@@ -0,0 +1,22 @@
+// 💣 Remove this explicit `test` import.
+import { test } from '../test-extend'
+import { queryUser } from './query-user'
+
+test('throws if the user is not found', async () => {
+	await expect(queryUser('abc-123')).resolves.toBeUndefined()
+})
+
+test('returns the user by id', async ({ createMockDatabase }) => {
+	await createMockDatabase((db, done) => {
+		db.run(
+			'INSERT INTO users (id, name) VALUES (?, ?)',
+			['abc-123', 'John Doe'],
+			done,
+		)
+	})
+
+	await expect(queryUser('abc-123')).resolves.toEqual({
+		id: 'abc-123',
+		name: 'John Doe',
+	})
+})
diff --git a/exercises/02.context/03.problem.global-context/src/query-user.ts b/exercises/02.context/03.problem.global-context/src/query-user.ts
@@ -0,0 +1,10 @@
+import { client } from './database'
+
+export interface User {
+	id: string
+	name: string
+}
+
+export async function queryUser(id: string): Promise<User> {
+	return await client.query(`SELECT * FROM users WHERE id = ?`, [id])
+}
diff --git a/exercises/02.context/03.problem.global-context/test-extend.ts b/exercises/02.context/03.problem.global-context/test-extend.ts
@@ -0,0 +1,96 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { test as testBase } from 'vitest'
+import sqlite3, { type Database } from 'sqlite3'
+import * as databaseModule from './src/database'
+
+interface Fixtures {
+	createMockDatabase: (
+		seed: (database: Database, handle: CallbackHandle) => void,
+	) => Promise<void>
+}
+
+// 🐨 Augment the module declaration for "vitest".
+// 💰 declare module 'vitest' {}
+
+// 🐨 In the module declaration, declare an interface called `TestContext`
+// and make it extend your custom `Fixtures` interface. Then, export it.
+// This will annotate the custom test content of the global `test()` function.
+// 💰 export interface A extends B {}
+
+// 🐨 Declare a namespace for `globalThis`.
+// Inside that namespace, declare a variable called `test`
+// and assign it the type of `testBase` function.
+// This annotate the `globalThis.test` function so your extension below
+// would be type-safe.
+// 💰 declare namespace globalThis {}
+// 💰 var test: typeof testBase
+
+type CallbackHandle = (error?: Error | null, ...args: Array<any>) => void
+
+function toPromise<T>(init: (handle: CallbackHandle) => T): Promise<T> {
+	return new Promise<T>((resolve, reject) => {
+		const result = init((error) => {
+			if (error) {
+				return reject(error)
+			}
+			resolve(result)
+		})
+	})
+}
+
+// 💣 Finally, delete the `test` variable declaration
+// and replace it with assigning to `globalThis.test`.
+// 💰 globalThis.test = testBase.extend<T>({})
+export const test = testBase.extend<Fixtures>({
+	createMockDatabase: [
+		async ({ task, onTestFinished }, use) => {
+			const databasePath = `${task.file.filepath}-${task.id}.sqlite`
+
+			if (fs.existsSync(databasePath)) {
+				await fs.promises.rm(databasePath)
+			}
+
+			const mockDatabase = await toPromise((handle) => {
+				return new sqlite3.Database(databasePath, handle)
+			})
+
+			onTestFinished(async ({ task }) => {
+				await toPromise((handle) => mockDatabase.close(handle))
+
+				if (task.type !== 'test') {
+					return
+				}
+
+				if (task.result?.state === 'pass') {
+					await fs.promises.rm(databasePath)
+				} else {
+					task.result?.errors?.push({
+						name: 'Mock database',
+						message: 'See the database state:',
+						codeFrame: path.relative(process.cwd(), databasePath),
+					})
+				}
+			})
+
+			const clientSpy = vi
+				.spyOn(databaseModule, 'client', 'get')
+				.mockReturnValue(new databaseModule.DatabaseClient(mockDatabase))
+
+			await toPromise((handle) => {
+				mockDatabase.run('CREATE TABLE users (id TEXT, name TEXT)', handle)
+			})
+
+			await use((seed) => {
+				return toPromise((handle) => {
+					seed(mockDatabase, handle)
+				})
+			})
+
+			clientSpy.mockRestore()
+		},
+		{
+			auto: true,
+		},
+	],
+})
diff --git a/exercises/02.context/03.problem.global-context/tsconfig.app.json b/exercises/02.context/03.problem.global-context/tsconfig.app.json
@@ -0,0 +1,9 @@
+{
+	"extends": "./tsconfig.base.json",
+	"include": ["src/**/*"],
+	"exclude": ["src/**/*.test.ts*"],
+	"compilerOptions": {
+		"lib": ["ES2020", "DOM", "DOM.Iterable"],
+		"jsx": "react-jsx"
+	}
+}
diff --git a/exercises/02.context/03.problem.global-context/tsconfig.base.json b/exercises/02.context/03.problem.global-context/tsconfig.base.json
@@ -0,0 +1,23 @@
+{
+	"compilerOptions": {
+		"target": "ESNext",
+		"module": "ESNext",
+		"useDefineForClassFields": true,
+		"skipLibCheck": true,
+
+		/* Bundler mode */
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"isolatedModules": true,
+		"moduleDetection": "force",
+		"noEmit": true,
+		"verbatimModuleSyntax": true,
+
+		/* Linting */
+		"strict": true,
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedSideEffectImports": true
+	}
+}
diff --git a/exercises/02.context/03.problem.global-context/tsconfig.json b/exercises/02.context/03.problem.global-context/tsconfig.json
@@ -0,0 +1,8 @@
+{
+	"files": [],
+	"references": [
+		{ "path": "./tsconfig.app.json" },
+		{ "path": "./tsconfig.node.json" },
+		{ "path": "./tsconfig.test.json" }
+	]
+}
diff --git a/exercises/02.context/03.problem.global-context/tsconfig.node.json b/exercises/02.context/03.problem.global-context/tsconfig.node.json
@@ -0,0 +1,7 @@
+{
+	"extends": "./tsconfig.base.json",
+	"compilerOptions": {
+		"lib": ["ES2023"]
+	},
+	"include": ["vitest.config.ts"]
+}
diff --git a/exercises/02.context/03.problem.global-context/tsconfig.test.json b/exercises/02.context/03.problem.global-context/tsconfig.test.json
@@ -0,0 +1,8 @@
+{
+	"extends": "./tsconfig.app.json",
+	"include": ["test-extend.ts", "src/**/*", "src/**/*.test.ts*"],
+	"exclude": [],
+	"compilerOptions": {
+		"types": ["vitest/globals"]
+	}
+}
diff --git a/exercises/02.context/03.problem.global-context/vitest.config.ts b/exercises/02.context/03.problem.global-context/vitest.config.ts
@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+	test: {
+		globals: true,
+		// 🐨 Add a `setupFiles` property and make it equal an array.
+		// In that array, provide a relative path to the "./test-extend.ts" module.
+		// 💰 setupFiles: [filePath]
+	},
+})
diff --git a/exercises/02.context/03.solution.global-context/README.mdx b/exercises/02.context/03.solution.global-context/README.mdx
@@ -1,5 +1,76 @@
 # Global context
 
-## TODO
+If I want to expose my custom test context in `test-extend.ts` globally, Vitest has to evaluate that module as a part of my setup. So a good place to start it so to add that module to the `setupFiles` in `vitest.config.ts`:
 
-- [ ] Review if extending `globalThis` this way makes sense.
+```ts filename=vitest.config.ts add=6
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+	test: {
+		globals: true,
+		setupFiles: ['./test-extend.ts'],
+	},
+})
+```
+
+<callout-success>Adding `test-extend.ts` to `setupFiles` means Vitest will run it as a part of the test setup. This is _one piece_ to not having to import it explicitly.</callout-success>
+
+Now, I need to refactor the way my test context is declared, moving it from a local `test` variable to a global `globalThis.test()` function.
+
+In `test-extend.ts`, I will augment the module declaration for `vitest` to automatically infer the types for my `Fixtures` onto the default `test()` function:
+
+```ts filename=test-extend.ts add=7-9
+interface Fixtures {
+	createMockDatabase: (
+		seed: (database: Database, handle: CallbackHandle) => void,
+	) => Promise<void>
+}
+
+declare module 'vitest' {
+	export interface TestContext extends Fixtures {}
+}
+```
+
+Next, it's time to change the type definitions for the global `test()` function.
+
+When you're using `vitest/globals` in your TypeScript configuration, that exposes functions like `test()` and `expect()` globally, providing the necessary type definitions. Overriding the types for those functions, however, is currently impossible since they are declared as _constants_:
+
+```ts filename=vitest/globals.d.ts highlight=2-3
+declare global {
+	const test: (typeof import('vitest'))['test']
+	const expect: (typeof import('vitest'))['expect']
+	// ...
+}
+export {}
+```
+
+Not to worry. Since I've extended the regular test context in `interface TestContext extends Fixtures`, all I have to do is annotate `globalThis.test` as the imported `testBase` explicitly.
+
+```ts filename=test-extend.ts add=13-15 highlight=1
+import { test from testBase } from 'vitest'
+
+interface Fixtures {
+	createMockDatabase: (
+		seed: (database: Database, handle: CallbackHandle) => void,
+	) => Promise<void>
+}
+
+declare module 'vitest' {
+	export interface TestContext extends Fixtures {}
+}
+
+declare namespace globalThis {
+	var test: typeof testBase
+}
+```
+
+> `testBase` now has its `TestContext` augmented by my custom `Fixtures` interface. Overriding the type definition for global test as `typeof testBase` means that the custom context is also exposed to the global context!
+
+Now, all is left is to refactor the existing tests to remove the explicit `test` import from `test-extend.ts` and rely on the global `test()` function instead:
+
+```ts remove=1
+import { test } from '../test-extend'
+import { queryUser } from './query-user'
+```
+
+And we're done! 🎉
diff --git a/exercises/02.context/03.solution.global-context/package.json b/exercises/02.context/03.solution.global-context/package.json
@@ -2,9 +2,7 @@
   "type": "module",
   "name": "exercises_02.context_03.solution.global-context",
   "scripts": {
-    "dev": "vite",
-    "test": "vitest",
-    "build": "vite build"
+    "test": "vitest"
   },
   "devDependencies": {
     "vite": "^6.2.6",
diff --git a/exercises/02.context/03.solution.global-context/vitest.config.ts b/exercises/02.context/03.solution.global-context/vitest.config.ts
@@ -1,9 +1,6 @@
 import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
-	server: {
-		port: process.env.PORT ? Number(process.env.PORT) : undefined,
-	},
 	test: {
 		globals: true,
 		setupFiles: ['./test-extend.ts'],
diff --git a/tsconfig.json b/tsconfig.json
@@ -34,6 +34,9 @@
     {
       "path": "exercises/02.context/02.solution.automatic-fixtures"
     },
+    {
+      "path": "exercises/02.context/03.problem.global-context"
+    },
     {
       "path": "exercises/02.context/03.solution.global-context"
     },
