02/01: add exercise texts

Author: kettanaito

exercises/02.context/01.problem.custom-fixtures/README.mdx

@@ -0,0 +1,52 @@
+# Custom fixtures
+
+Crafting custom, domain-specific utilities is a great way to elevate your test setup and turn your tests into a _composition_ of declarative steps and assertions that follow them. As always, there are multiple ways to approach test utilities. You can just import them when you need them _or_ you can use _fixtures_ instead.
+
+Vitest's concept of a fixture is heavily inspired by Playwright, where you can access both built-in and custom fixtures from the test context:
+
+```ts filename=playwright.test.ts highlight=3
+import { test } from '@playwright/test'
+
+test('...', ({ page, myCustomFixture }) => {})
+//             👆    👆
+```
+
+> The first argument to the test callback function is referred to as **test context**.
+
+Vitest already exposes a few built-in utilities in its test context, such as the `expect` function:
+
+```ts filename=vitest.test.ts highlight=1
+test('...', ({ expect }) => {
+	expect(this).toBe(that)
+})
+```
+
+But you can push this further. You can extend the default test context and imbue it with custom fixtures specific to the software you're testing. It's time you learned how.
+
+## Your task
+
+Our e-commerce application has a neat utility to calculate any given cart's total using a function called `getTotalPrice`:
+
+```ts filename=src/cart-utils.ts
+export function getTotalPrice(cart: Cart): number {
+	return cart.reduce((total, item) => {
+		return total + item.price * item.quantity
+	}, 0)
+}
+```
+
+It expects a `cart: Cart` object as the argument, which means that in order to test different calculation scenarios you have to create different states of the cart. You certainly can do that manually in each test or you can utilize a custom fixture to help you out.
+
+👨‍💼 In this one, your task is to _extend the default test context in Vitest_ and implement a custom fixture called `createMockCart()`. You will use `@faker-js/faker` to help you with generating random values for your mock, such as cart item names and quantity. You will implement your custom fixture so it has a default random state but also supports overriding that state on the individual test basis to model the scenarios you need.
+
+🐨 Start by installing `@faker-js/faker` as a dependency:
+
+```
+npm install @faker-js/faker --save-dev
+```
+
+🐨 Next, proceed to <InlineFile file="test-extend.ts" /> file ane follow the instructions to implement a custom fixture.
+
+🐨 Once the fixture is ready, import the custom `test` function you've created in the <InlineFile file="src/cart-utils.test.ts" /> test file _and complete it_. By the end, run `npm test` to verify that your tests are passing.
+
+Good luck!

exercises/02.context/01.problem.custom-fixtures/package.json

@@ -0,0 +1,10 @@
+{
+  "type": "module",
+  "name": "exercises_02.context_01.problem.custom-fixtures",
+  "scripts": {
+    "test": "vitest"
+  },
+  "devDependencies": {
+    "vitest": "^3.1.1"
+  }
+}

exercises/02.context/01.problem.custom-fixtures/src/cart-utils.test.ts

@@ -0,0 +1,19 @@
+// 🐨 Import the custom `test` function from `../test-extend`.
+// 💰 import { this } from 'that'
+import { getTotalPrice } from './cart-utils'
+
+test('returns the total price for the cart', () => {
+	// 💰 ({ createMockCart }) => {} // Inside that object, access your newly created fixture `createMockCart`. // 🐨 Destructure the first argument of the `test()` function.
+	// 🐨 Declare a new variable called `cart` and assign it the result
+	// of calling the `createMockCart()` fixture.
+	// 💰 const cart = yourFixture(args)
+	//
+	// 🐨 Provide a fixed set of cart items to your mock cart.
+	// This way, the state of the cart item is fixed to this test case,
+	// guaranteeing explicit and reliable test results.
+	// 💰 [{ price: 5, quantity: 10 }, { price: 8, quantity: 4 }]
+	//
+	// 🐨 Finally, write an assertion that calling `getTotalPrice()` with your
+	// mock `cart` as an argument returns the correct total price.
+	// 💰 expect(actual).toBe(expected)
+})

exercises/02.context/01.problem.custom-fixtures/src/cart-utils.ts

@@ -0,0 +1,14 @@
+export type Cart = Array<CartItem>
+
+export interface CartItem {
+	id: string
+	name: string
+	price: number
+	quantity: number
+}
+
+export function getTotalPrice(cart: Cart): number {
+	return cart.reduce((total, item) => {
+		return total + item.price * item.quantity
+	}, 0)
+}

exercises/02.context/01.problem.custom-fixtures/test-extend.ts

@@ -0,0 +1,56 @@
+// 🐨 Import the `test` function from `vitest`.
+// Since you're going to create a custom version of that function,
+// alias its import as `testBase`.
+// 💰 import { this as that } from 'pkg'
+//
+// 🐨 Import the `faker` object from `@faker-js/faker`.
+// You will use this object to generate random data for your mock cart.
+//
+// 🐨 Lastly, import types `Cart` and `CartItem` from `./src/cart-utils`.
+// These will help you keep your custom fixture type-safe.
+//
+// 🐨 Declare a new TypeScript interface called `Fixtures`.
+// This interface will describe the types of your custom fixtures.
+// 💰 interface Fixtures {}
+//
+// 🐨 In the `Fixtures` interface, declare a property called `createMockCart`.
+// Assign an arrow function as the value of that property.
+// The function accepts a single argument called `items` of type `Array<Partial<CartItem>>`
+// and returns a `Cart` object.
+// 💰 fn: (arg: T) => R
+//
+// 🐨 Now, create a new variable called `test` and export it from this module.
+// As the value, assign it the result of calling `testBase.extend({})`.
+// Narrow down the types of custom fixtures by providing the `Fixtures` interface
+// as the type argument to the `testBase.extend()` method.
+// 💰 export const test = testBase.extend({})
+// 💰 testBase.extend<T>({})
+//
+// 🐨 In the object argument to `testBase.extend()`, declare a new async function
+// called `createMockCart()`. It will accept two arguments:
+// - Text context (an empty object);
+// - The `use` function to apply custom fixtures.
+// 💰 async createMockCart({}, use ) {}
+//
+// 🐨 In the `createMockCart` function body, await the call to the `use()` function.
+// As the argument to `use()`, pass an arrow function that accepts a single argument called `items`.
+// 💰 await use((items) => {})
+//
+// At this point, you can see TypeScript complaining about your `use()` function
+// as it's expected to return a `Cart` object!
+// 🐨 Return the result of iterating over the given `items` array.
+// 💰 return items.map((item) => {})
+//
+// 🐨 In the return of the `.map()`, return an object matching the `Cart` type.
+// Use various methods on the `faker` object to create a cart object populated with random data.
+// 💰
+// {
+//   id: faker.string.ulid(),
+//   name: faker.commerce.productName(),
+//   price: faker.number.int({ min: 1, max: 25 }),
+//   quantity: faker.number.int({ min: 1, max: 10 }),
+// }
+//
+// 🐨 Finally, at the end of the returned `Cart` object, spread the `item` object
+// from the `.map()` argument to enable value overrides from tests.
+// 💰 return { id, name, price, quantity, ...item }

exercises/02.context/01.problem.custom-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/01.problem.custom-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/01.problem.custom-fixtures/tsconfig.json

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

exercises/02.context/01.problem.custom-fixtures/tsconfig.node.json

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

exercises/02.context/01.problem.custom-fixtures/tsconfig.test.json

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