03/01: add exercise texts

kettanaito · kettanaito · commit 088dabb72671 · 2025-04-25T13:11:51.000+02:00
diff --git a/exercises/03.assertions/01.problem.custom-matchers/README.mdx b/exercises/03.assertions/01.problem.custom-matchers/README.mdx
@@ -0,0 +1,66 @@
+# Custom matchers
+
+Imagine you're building a full-stack application. Inevitably, it fetches and processes data from the server in order to render the corresponding UI. To keep it both type- and runtime-safe, you introduce a validation library to define schemas for your data types and keep them in check.
+
+For example, you may have a user schema:
+
+```ts filename=src/schemas.ts highlight=3-6
+import z from 'zod'
+
+export const userSchema = z.object({
+	id: z.string(),
+	name: z.string(),
+})
+
+export type User = z.infer<typeof userSchema>
+```
+
+> Above, we are defining a simple `userSchema` containing fields `id` and `name`. Then we are inferring the user object's type using `z.infer` and exporting it as a `User` type for our application to use.
+
+Then, you have a function responsible for fetching the user:
+
+```ts filename=src/fetch-user.ts highlight=4
+import type { User } from './schemas'
+
+export async function fetchUser(id: string): Promise<User> {
+	return db.user.findFirst<User>({ where: { id } })
+}
+```
+
+It is clear that the `fetchUser()` function must return an object of the `User` type, which also means that it must match the `userSchema`.
+
+How would you reflect this intention in tests?
+
+```ts filename=src/fetch-user.test.ts
+import { userSchema } from './schemas'
+
+test('returns the user by id', async () => {
+	const user = await fetchUser('abc-123')
+	const result = userSchema.safeParse(user)
+
+	expect(result.error).toBeUndefined()
+	expect(result.data).toEqual({
+		id: 'abc-123',
+		name: 'John Maverick',
+	})
+})
+```
+
+> You would also need to mock the `fetchUser()`'s dependency on the `db` but I am omitting this step for brevity.
+
+So you fetch the user with the controlled id (`await fetchUser('abc-123')`), parse it with the schema (`userSchema.safeParse(user)`), and assert that there were no errors and the parsed object matches the expected mock user.
+
+While this testing strategy works, there are two issues with it:
+
+1. **It's quite verbose**. Imagine employing this strategy to verify dozens of scenarios. You are paying 3 LOC for what is, conceptually, a single assertion;
+1. **It's distracting**. Parsing the object and validating the parsed result are _technical details_ exclusive to the intention. It's not the intention itself. It has nothing to do with the `fetchUser()` behaviors you're testing.
+
+Luckily, there are ways to redesign this approach to be more declartive and expressive by using a _custom matcher_.
+
+## Your task
+
+👨‍💼 In this exercise, your task will be to rewrite the existing test at <InlineFile file="src/fetch-user.test.ts" /> to use the matcher called `.toMatchSchema()`. The only thing is, this matcher _doesn't exist_. You have to create it!
+
+Head to <InlineFile file="vitest.setup.ts" /> and follow the instructions to implement your custom matcher. Don't forget to include the setup file in <InlineFile file="vitest.config.ts" /> and have the tests passing once you refactor them.
+
+Good luck!
diff --git a/exercises/03.assertions/01.problem.custom-matchers/package.json b/exercises/03.assertions/01.problem.custom-matchers/package.json
@@ -0,0 +1,15 @@
+{
+  "type": "module",
+  "name": "exercises_03.assertions_01.problem.custom-matchers",
+  "scripts": {
+    "test": "vitest"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.1",
+    "vite": "^6.2.6",
+    "vitest": "^3.1.1"
+  },
+  "dependencies": {
+    "zod": "^3.24.2"
+  }
+}
diff --git a/exercises/03.assertions/01.problem.custom-matchers/pnpm-lock.yaml b/exercises/03.assertions/01.problem.custom-matchers/pnpm-lock.yaml
diff --git a/exercises/03.assertions/01.problem.custom-matchers/src/fetch-user.test.ts b/exercises/03.assertions/01.problem.custom-matchers/src/fetch-user.test.ts
@@ -0,0 +1,22 @@
+import { fetchUser } from './fetch-user'
+import { userSchema } from './schemas'
+
+test('returns the user by id', async () => {
+	const user = await fetchUser('abc-123')
+
+	// 💣 Remove this object parsing.
+	// Your custom matcher will perform the parsing now.
+	const result = userSchema.safeParse(user)
+
+	// 💣 Remove both of these assertions.
+	expect(result.error).toBeUndefined()
+	expect(result.data).toEqual({
+		id: 'abc-123',
+		name: 'John Maverick',
+	})
+
+	// 🐨 Add a single assertion over the `user` object
+	// as the received value, using the `.toMatchSchema()` matcher.
+	// Provide the `userSchema` as the expected value.
+	// 💰 expect(this).toMatchSchema(that)
+})
diff --git a/exercises/03.assertions/01.problem.custom-matchers/src/fetch-user.ts b/exercises/03.assertions/01.problem.custom-matchers/src/fetch-user.ts
@@ -0,0 +1,11 @@
+import type { User } from './schemas'
+
+/**
+ * Returns the user with the given ID.
+ */
+export async function fetchUser(id: string): Promise<User> {
+	return {
+		id,
+		name: 'John Maverick',
+	}
+}
diff --git a/exercises/03.assertions/01.problem.custom-matchers/src/schemas.ts b/exercises/03.assertions/01.problem.custom-matchers/src/schemas.ts
@@ -0,0 +1,10 @@
+import z from 'zod'
+
+export const userSchema = z.object({
+	id: z.string(),
+	name: z.string(),
+})
+
+const r = userSchema.safeParse({})
+
+export type User = z.infer<typeof userSchema>
diff --git a/exercises/03.assertions/01.problem.custom-matchers/tsconfig.base.json b/exercises/03.assertions/01.problem.custom-matchers/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/03.assertions/01.problem.custom-matchers/tsconfig.json b/exercises/03.assertions/01.problem.custom-matchers/tsconfig.json
@@ -0,0 +1,8 @@
+{
+	"files": [],
+	"references": [
+		{ "path": "./tsconfig.src.json" },
+		{ "path": "./tsconfig.node.json" },
+		{ "path": "./tsconfig.test.json" }
+	]
+}
diff --git a/exercises/03.assertions/01.problem.custom-matchers/tsconfig.node.json b/exercises/03.assertions/01.problem.custom-matchers/tsconfig.node.json
@@ -0,0 +1,8 @@
+{
+	"extends": "./tsconfig.base.json",
+	"include": ["vitest.config.ts"],
+	"compilerOptions": {
+		"lib": ["ES2023"],
+		"types": ["node"]
+	}
+}
diff --git a/exercises/03.assertions/01.problem.custom-matchers/tsconfig.src.json b/exercises/03.assertions/01.problem.custom-matchers/tsconfig.src.json
@@ -0,0 +1,5 @@
+{
+	"extends": "./tsconfig.base.json",
+	"include": ["src/**/*.ts"],
+	"exclude": ["src/**/*.test.ts"]
+}
diff --git a/exercises/03.assertions/01.problem.custom-matchers/tsconfig.test.json b/exercises/03.assertions/01.problem.custom-matchers/tsconfig.test.json
@@ -0,0 +1,8 @@
+{
+	"extends": "./tsconfig.src.json",
+	"include": ["vitest.setup.ts", "src/**/*", "src/**/*.test.ts*"],
+	"exclude": [],
+	"compilerOptions": {
+		"types": ["node", "vitest/globals"]
+	}
+}
diff --git a/exercises/03.assertions/01.problem.custom-matchers/vitest.config.ts b/exercises/03.assertions/01.problem.custom-matchers/vitest.config.ts
@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+	server: {
+		port: process.env.PORT ? Number(process.env.PORT) : undefined,
+	},
+	test: {
+		globals: true,
+		environment: 'node',
+		// 🐨 Add the `setupFiles` property and include the `./vitest.setup.ts`
+		// as the setup for your tests.
+		// 💰 setupFiles: [pathToSetupFile]
+	},
+})
diff --git a/exercises/03.assertions/01.problem.custom-matchers/vitest.setup.ts b/exercises/03.assertions/01.problem.custom-matchers/vitest.setup.ts
@@ -0,0 +1,59 @@
+// 🐨 Start by importing the `expect` function from `vitest`.
+// 💰 import { this } from 'that'
+//
+// 🐨 Then import the `Schema` type from `zod`.
+// Use will use it to annotate your custom `.toMatchSchema` matcher.
+// 💰 import { this } from 'that'
+//
+// 🐨 Now, declare a new interface in TypeScript called `CustomMatchers`.
+// It accepts a single type argument called `MatcherResult`. Make it default to `any`.
+// 💰 interface Name<T = any> {}
+//
+// 🐨 Inside the `CustomMatchers` interface, add a method called `toMatchSchema`.
+// As the type of this method, provide an arrow function that accepts the argument `schema`
+// of type `Schema` you've imported earlier, and returns `MatcherResult`.
+// 💰 toMatchSchema: (arg: T) => R
+//
+// 🐨 Augment the type definition for the `vitest` module.
+// 💰 declare module 'name' {}
+//
+// 🐨 Inside the module declaration, declare an interface called `Assertion<T = any>`.
+// Make it extend the `CustomMatchers` interface you created earlier.
+// This will extend the type definitions of the `expect()` function to recognize
+// your custom matchers.
+// 💰 interface Assertion<T = any> extends CustomMatchers<T> {}
+//
+// 🐨 In a similar way, declare another interface called `MatchersDeclaration`
+// and make it extend your `CustomMatchers` interface.
+// This will extend the type definitions of the `expect.extend()` function
+// to make the implementation of your custom matchers type-safe.
+// 💰 interface MatchersDeclaration extends CustomMatchers {}
+//
+// This covers your custom matcher on the type-level.
+// Now, let's continue with its implementation!
+// 🐨 Call `expect.extend()` and provide it an empty object as an argument.
+// 💰 expect.extend({})
+//
+// 🐨 Inside the object to `expect.extend()`, define a property called `toMatchSchema`.
+// As the value of this property, provide an arrow function that accepts two arguments:
+// `received` and `expected`.
+// 💰 toMatchSchema(received, expected) {}
+//
+// 🐨 Go inside the `toMatchSchema` function and declare a variable called `result`.
+// Asign it the result of parsing the `received` object with the `expected` schema.
+// 💰 const result = someSchema.safeParse(someValue)
+//
+// 🐨 If the `result.success` is `false`, return an object that represents a failed assertion.
+// That assertion object consists of the following properties:
+// - `pass`, which you should set to `false`, indicating that the assertion failed.
+// - `message`, which is a function that returns the assertion error (e.g. "Does not match the schema").
+// - `actual`, which is the actual value that was received (`received`).
+// - `expected`, which is the expected value (use `result.error.format()`).
+// 💰 (!result.success) { return { ... } }
+//
+// 🐨 Now, handle the successful assertion.
+// Return a similar matcher result object but with the following properties:
+// - `pass` should be `true`, indicating that the assertion passed.
+// - `message` should be a function that returns the assertion success message (e.g. "Matches the schema").
+// - `actual` should be the actual value that was received (`received`).
+// 💰 return { pass, message: () => '', actual }
diff --git a/exercises/03.assertions/01.solution.custom-matchers/README.mdx b/exercises/03.assertions/01.solution.custom-matchers/README.mdx
diff --git a/exercises/03.assertions/01.solution.custom-matchers/src/fetch-user.test.ts b/exercises/03.assertions/01.solution.custom-matchers/src/fetch-user.test.ts
diff --git a/exercises/03.assertions/01.solution.custom-matchers/vitest.config.ts b/exercises/03.assertions/01.solution.custom-matchers/vitest.config.ts
diff --git a/exercises/03.assertions/01.solution.custom-matchers/vitest.setup.ts b/exercises/03.assertions/01.solution.custom-matchers/vitest.setup.ts
diff --git a/tsconfig.json b/tsconfig.json
