03/03: add exercise text

Author: kettanaito

exercises/03.assertions/03.problem.custom-quality-testers/README.mdx

@@ -0,0 +1,35 @@
+# Custom equality testers
+
+Assertions in tests often come down to _value comparison_. You expect the result of <span style={{ whiteSpace: 'nowrap' }}>`sum(2, 3)`</span> to equal `5`; you expect `cart` to have a property `items` of type `Array`, and so on. And, sometimes, comparing things isn't as straightforward.
+
+For example, imagine testing software that deals with measurements. Each measurement has a `value` (e.g. 1, 5, or 57) and a `unit` (inches, millimeters, centimeters, etc). It's quite easy to compare two measurements if both their values and units are the same:
+
+```ts nonumber
+expect(new Measurement(1, 'in')).toEqual(new Measurement(1, 'in')) // ✅
+```
+
+It's a bit harder if those two are different.
+
+```ts nonumber
+expect(new Measurement(1, 'in')).toEqual(new Measurement(2.54, 'cm')) // ❌
+```
+
+Semantically, these two measurements _are_ equal. 1 inch is, indeed, 2.54 centimeters. But syntanctically these two measurements produce different class instances that cannot be compared literally:
+
+```ts nonumber
+// If you unwrap measurements, you can imagine them as plain objects.
+// Vitest will attempt to compare them as such, which will fail.
+expect({ value: 1, unit: 'in' }).toEqual({ value: 2.54, unit: 'cm' }) // ❌
+```
+
+Although you can, technically, solve this problem by introducing a custom matcher (something like `.toEqualMeasurement()`), that would be like using a fire hose to pour oneself a glass of water. It will work, but it's rather an overkill.
+
+In situations like this, all you want is to _teach Vitest how to compare custom values_. That would still be equality comparison, but the one you fine-tune to compare measurements for what they stand for and not what objects they produce.
+
+You need to extend `.toEqual()` itself.
+
+## Your task
+
+👨‍💼 In this exercise, your task is to implement a _custom equality checker_ for Vitest. Head to the <InlineFile file="vitest.setup.ts" /> file and follow the instructions to do that.
+
+As always, run the tests (`npm test`) to verify your solution. The tests shall pass!

exercises/03.assertions/03.problem.custom-quality-testers/package.json

@@ -0,0 +1,13 @@
+{
+  "type": "module",
+  "name": "exercises_03.assertions_03.problem.custom-quality-testers",
+  "scripts": {
+    "dev": "vite",
+    "test": "vitest",
+    "build": "vite build"
+  },
+  "devDependencies": {
+    "vite": "^6.2.6",
+    "vitest": "^3.1.1"
+  }
+}

exercises/03.assertions/03.problem.custom-quality-testers/src/measurement.test.ts

@@ -0,0 +1,17 @@
+import { Measurement } from './measurement'
+
+test('compares measurements', () => {
+	expect(new Measurement(10, 'in')).toEqual(new Measurement(25.4, 'cm'))
+})
+
+test('compares nested measurements', () => {
+	expect({
+		id: 1,
+		name: 'fabric',
+		length: new Measurement(10, 'in'),
+	}).toEqual({
+		id: 1,
+		name: 'fabric',
+		length: new Measurement(25.4, 'cm'),
+	})
+})

exercises/03.assertions/03.problem.custom-quality-testers/src/measurement.ts

@@ -0,0 +1,19 @@
+type MeasurementUnit = 'in' | 'cm'
+
+export class Measurement {
+	constructor(
+		public readonly value: number,
+		public readonly unit: MeasurementUnit,
+	) {}
+
+	public equals(other: Measurement): boolean {
+		if (this.unit === other.unit) {
+			return this.value === other.value
+		}
+
+		const thisValue = this.unit === 'in' ? this.value * 2.54 : this.value
+		const otherValue = other.unit === 'in' ? other.value * 2.54 : other.value
+
+		return thisValue === otherValue
+	}
+}

exercises/03.assertions/03.problem.custom-quality-testers/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/03.assertions/03.problem.custom-quality-testers/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/03.assertions/03.problem.custom-quality-testers/tsconfig.json

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

exercises/03.assertions/03.problem.custom-quality-testers/tsconfig.node.json

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

exercises/03.assertions/03.problem.custom-quality-testers/tsconfig.test.json

@@ -0,0 +1,8 @@
+{
+	"extends": "./tsconfig.app.json",
+	"include": ["vitest.setup.ts", "src/**/*", "src/**/*.test.ts*"],
+	"exclude": [],
+	"compilerOptions": {
+		"types": ["vitest/globals"]
+	}
+}

exercises/03.assertions/03.problem.custom-quality-testers/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+	server: {
+		port: process.env.PORT ? Number(process.env.PORT) : undefined,
+	},
+	test: {
+		globals: true,
+		setupFiles: ['./vitest.setup.ts'],
+	},
+})