02/02: add exercise texts

Author: kettanaito

exercises/02.context/02.problem.automatic-fixtures/README.mdx

@@ -0,0 +1,85 @@
+# Automatic fixtures
+
+Your custom fixtures can introduce side effects that run before and after the fixture (i.e. after the test case is done). For example, let's take a look at this `createMockFile()` fixture:
+
+```ts filename=test-extend.ts
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+interface Fixtures {
+	createMockFile: (content: string, filename: string) => Promise<void>
+}
+
+test.extend({
+	async createMockFile({}, use) {
+		// 1. Prepare.
+		const temporaryDirectory = await fs.promises.mkdtemp(
+			path.join(os.tmpdir(), 'test-'),
+		)
+
+		// 2. Use.
+		await use(async (content, filename) => {
+			const filePath = path.join(temporaryDirectory, filename)
+			await fs.promises.writeFile(content, filePath)
+			return filePath
+		})
+
+		// 3. Clean up.
+		await fs.promises.rmdir(temporaryDirectory, { recursive: true })
+	},
+})
+```
+
+You can spot three distinct phases in this fixture:
+
+1. **Prepare**, where the temporary directory is created on disk;
+1. **Use**, where the `content` gets written at the `filename` provided by the test;
+1. **Clean up**, where the temporary directory gets deleted.
+
+Then, if you wish to create a mock file in your test, you call the `createMockFile()` fixture:
+
+```ts
+test('...', ({ createMockFile }) => {
+	const filePath = await createMockFile('hello world', 'greeting.txt')
+})
+```
+
+Once you access that fixture from the test context object, Vitest will know that you intend to use it. So it will run the "prepare" and "clean up" phases before the test starts and after it's done, respectively.
+
+But what about the tests that _don't_ use that fixture?
+
+Since they never reference it, _Vitest will skip its initalization_. That makes sense. If you don't need a temporary file for this test, there's no need to create and delete the temporary directory. Nothing is going to use it.
+
+<callout-info>In other words, all fixtures are _lazy_ by default. Their implementation won't be called unless you reference that fixture in your test.</callout-info>
+
+## Opt out from lazy initialization
+
+That being said, not all fixtures are meant to be explicitly referenced.
+
+For example, think of API mocking. Whether you're referencing it in your test or not, the network must still be mocked consistently for all test cases. The same is true for, say, a mocked database.
+
+```ts
+test('throws if the user is not found', async () => {
+	await expect(queryUser('abc-123')).resolves.toBeUndefined()
+})
+```
+
+> Above, the `queryUser()` function looks up a user by ID in a database. This test case wants assert the behavior when the user by the given ID does not exist. For that, it's nice to utilize a default, empty state of the mock database.
+
+If that database mock is implemented like a custom fixture, _it will never run for this test_ because this test never referenced it. The test case will fail and that's rather unfortunate.
+
+```
+ FAIL  src/query-user.test.ts > throws if the user is not found
+AssertionError: promise rejected "Error: SQLITE_ERROR: no such table: users { …(2) }" instead of resolving
+```
+
+This is where you can opt out from the lazy fixture initialization. You can tell Vitest that a certain fixture, like `createMockDatabase()`, should be instantiated regardless if any tests are referencing it.
+
+## Your task
+
+👨‍💼 In this exercise, your task is to modify the existing `createMockDatabase()` fixture to be initialized no matter if it's referenced in the tests.
+
+🐨 First, go to the <InlineFile file="text-extend.js" /> file, find the declaration for that fixture, and follow the instructions to turn off the lazy initialization.
+
+🐨 Next, find your next assignment in the <InlineFile file="src/query-user.test.ts" /> test file, where you will add a new test case for the `queryUser()` function. You will use the `createMockDatabase()` fixture to seed the mock database with a mock user before asserting that it can be found using the right ID.

exercises/02.context/02.problem.automatic-fixtures/package.json

@@ -0,0 +1,16 @@
+{
+  "type": "module",
+  "name": "exercises_02.context_02.problem.automatic-fixtures",
+  "scripts": {
+    "dev": "vite",
+    "test": "vitest",
+    "build": "vite build"
+  },
+  "devDependencies": {
+    "vite": "^6.2.6",
+    "vitest": "^3.1.1"
+  },
+  "dependencies": {
+    "sqlite3": "^5.1.7"
+  }
+}

exercises/02.context/02.problem.automatic-fixtures/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:'))

exercises/02.context/02.problem.automatic-fixtures/src/query-user.test.ts

@@ -0,0 +1,16 @@
+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()
+})
+
+// 🐨 Add a new test case called "returns the user by id".
+// In this test, use the `createMockDatabase()` fixture to seed the mock
+// database with a mock user. Make it have the id "abc-123" and the name "John Doe".
+// 💰 test('...', () => {})
+// 💰 await createMockDatabase((db, done) => {})
+
+// 🐨 Then, write an assertion that querying for the given user ID
+// indeed returns the mock user you've created.
+// 💰 await expect(fn(args)).resolves.toEqual({})

exercises/02.context/02.problem.automatic-fixtures/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])
+}

exercises/02.context/02.problem.automatic-fixtures/test-extend.ts

@@ -0,0 +1,79 @@
+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>
+}
+
+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)
+		})
+	})
+}
+
+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()
+		},
+		// 🐨 Add an object here that will stand for this fixture's options.
+		// Inside that object, set the `auto` property to `true.`
+		// This will make the `createMockDatabase` fixture initialize even
+		// if no tests are referencing it explicitly.
+		// 💰 { key: value }
+	],
+})

exercises/02.context/02.problem.automatic-fixtures/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"
+	}
+}

exercises/02.context/02.problem.automatic-fixtures/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
+	}
+}

exercises/02.context/02.problem.automatic-fixtures/tsconfig.json

@@ -0,0 +1,8 @@
+{
+	"files": [],
+	"references": [
+		{ "path": "./tsconfig.app.json" },
+		{ "path": "./tsconfig.node.json" },
+		{ "path": "./tsconfig.test.json" }
+	]
+}

exercises/02.context/02.problem.automatic-fixtures/tsconfig.node.json

@@ -0,0 +1,7 @@
+{
+	"extends": "./tsconfig.base.json",
+	"compilerOptions": {
+		"lib": ["ES2023"]
+	},
+	"include": ["vitest.config.ts"]
+}