03/05: add exercise texts

Author: kettanaito

exercises/03.assertions/04.problem.retryable-assertions/package.json

@@ -1,6 +1,6 @@
 {
   "type": "module",
-  "name": "exercises_03.assertions_04.solution.retryable-assertions",
+  "name": "exercises_03.assertions_04.problem.retryable-assertions",
   "scripts": {
     "dev": "vite",
     "test": "vitest",

exercises/03.assertions/05.problem.soft-assertions/README.mdx

@@ -0,0 +1,52 @@
+# Soft assertions
+
+The software you build tends to get complex, which is a direct reflection of the complexity behind its requirements. Sometimes, you have multiple expectations toward your system even within a single test case (which, by the way, I find to be absolutely normal).
+
+For example, let's say you are testing a user subscription service. There, one of the expectations is that when the user cancels their subscription, their `user.subscriptioon` object must transition to the correct state:
+
+```ts highlight=3-4
+user.cancelSubscription()
+
+expect(user.subscription.state).toBe('cancelled')
+expect(user.subscription.endsAt).toBe('2025-01-01T00:00:00.000Z')
+```
+
+There are two criteria to assume the correct cancellation:
+
+- The `state` property equals to `'cancelled'`;
+- The `endsAt` property equals to the first day of the next month after the subscription has been cancelled.
+
+You refelect these criteria in individual `expect()` calls (i.e. assertions).
+
+<callout-success>You can also rely on [Implicit assertions](https://www.epicweb.dev/implicit-assertions), which are a fantastic way to express more expectations without writing additional assertions.</callout-success>
+
+There is a great deal of value to be had from <u>**how**</u> your tests fail. In fact, most of the decisions you make when writing your tests comes down to designing a nice experience around test failures, one way or another.
+
+So, what happens when our subscription test fails?
+
+Right now, it can fail when either of the assertions fails (incorrect state update) or _both of them fail_ (missing state transition from `active` to `cancelled`). In any case, its failure indicates a problem and must help you get to its root cause faster.
+
+Let's imagine this test fails because the subscription never transitioned from `active` to `cancelled`. Your first piece of feedback from the test will be this:
+
+```txt nocopy remove=3 add=4
+AssertionError: expected 'active' to be 'cancelled'
+
+Expected: "cancelled"
+Received: "active"
+```
+
+This is a useful feedback as it clearly indicates an incorrect (or missing) state transition.
+
+**But it doesn't tell you the whole picture.**
+
+It only tells you the result of the first failed assertion. What about the other expectations? Did they succeed or also failed? Was the `endsAt` date calculated correctly, if at all? What if you have three, five, or _ten_ assertions toward the same state? How did those fare?
+
+All of that information is important when debugging issues. But since assertions are sensitive to order and operate on the fail-fast principle, you are locking yourself in a minigame of addressing failed assertions one-by-one instead of grasping the issue as a whole.
+
+## Your task
+
+Let's change that.
+
+👨‍💼 In this one, you will refactor this user subscription test to use _soft assertions_. It's the kind of assertion that still runs and gives value but _doesn't short-circuit the test_ if it fails. Head straight to <InlineFile file="src/user.test.ts" /> and follow the instructions to refactor the test and gain more value out of its failures.
+
+👨‍💼 Bonus points if you track down and fix the issue to have the tests passing.

exercises/03.assertions/05.problem.soft-assertions/package.json

@@ -0,0 +1,13 @@
+{
+  "type": "module",
+  "name": "exercises_03.assertions_05.problem.soft-assertions",
+  "scripts": {
+    "dev": "vite",
+    "test": "vitest",
+    "build": "vite build"
+  },
+  "devDependencies": {
+    "vite": "^6.2.6",
+    "vitest": "^3.1.1"
+  }
+}

exercises/03.assertions/05.problem.soft-assertions/src/plans.ts

@@ -0,0 +1,57 @@
+export type PlanKind = 'monthly' | 'yearly'
+
+export class Plan {
+	public name: string
+	public kind: PlanKind
+	public state: 'active' | 'cancelled'
+	public chargeAmount: number
+	public endsAt?: string
+
+	constructor(options: {
+		name: string
+		kind: PlanKind
+		chargeAmount: number
+		endsAt?: string
+	}) {
+		this.name = options.name
+		this.kind = options.kind
+		this.chargeAmount = options.chargeAmount
+		this.state = 'active'
+		this.endsAt = options.endsAt
+	}
+
+	public cancel() {
+		if (this.state !== 'active') {
+			return
+		}
+
+		const today = new Date()
+		today.setUTCDate(1)
+
+		if (today.getUTCMonth() === 0) {
+			today.setUTCFullYear(today.getUTCFullYear() + 1)
+		}
+
+		this.endsAt = today.toISOString()
+	}
+}
+
+export class TrialPlan extends Plan {
+	constructor() {
+		super({
+			name: 'Trial',
+			kind: 'monthly',
+			chargeAmount: 0,
+		})
+	}
+}
+
+export class UnlimitedPlan extends Plan {
+	constructor() {
+		super({
+			name: 'Unlimited',
+			kind: 'yearly',
+			chargeAmount: 250,
+		})
+	}
+}

exercises/03.assertions/05.problem.soft-assertions/src/user.test.ts

@@ -0,0 +1,31 @@
+import { User } from './user'
+import { UnlimitedPlan } from './plans'
+
+beforeAll(() => {
+	vi.useFakeTimers()
+	vi.setSystemTime(new Date('2025-12-02T00:00:00Z'))
+})
+
+afterAll(() => {
+	vi.useRealTimers()
+})
+
+test('cancels the user subscription', () => {
+	const user = new User()
+	user.subscribe(new UnlimitedPlan())
+
+	// 🐨 Replace the `expect()` calls with `expect.soft()`.
+	// This will make these assertions soft.
+	// 💰 expect.soft()
+	expect(user.subscription.name).toBe('Unlimited')
+	expect(user.subscription.kind).toBe('yearly')
+	expect(user.subscription.state).toBe('active')
+	expect(user.subscription.endsAt).toBeUndefined()
+
+	user.cancelSubscription()
+
+	// 🐨 In a similar manner, refactor these assertions
+	// to be soft assertions.
+	expect(user.subscription.state).toBe('cancelled')
+	expect(user.subscription.endsAt).toBe('2026-01-01T00:00:00.000Z')
+})

exercises/03.assertions/05.problem.soft-assertions/src/user.ts

@@ -0,0 +1,17 @@
+import { TrialPlan, type Plan } from './plans'
+
+export class User {
+	public subscription: Plan
+
+	constructor() {
+		this.subscription = new TrialPlan()
+	}
+
+	public subscribe(subscription: Plan) {
+		this.subscription = subscription
+	}
+
+	public cancelSubscription() {
+		this.subscription.cancel()
+	}
+}

exercises/03.assertions/05.problem.soft-assertions/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/05.problem.soft-assertions/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/05.problem.soft-assertions/tsconfig.json

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

exercises/03.assertions/05.problem.soft-assertions/tsconfig.node.json

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