02/02: add exercise texts

Author: kettanaito

exercises/02.authentication/02.problem.2fa/README.mdx

@@ -1,7 +1,13 @@
 # Two-factor authentication
 
+Two-factor authentication (2FA) is a common addition to any authentication flow. It exists as a separate, additional layer of identity verification not only to supplement authentication but also act as a guard for sensitive and destructive actions of already authenticated users. You've likely seen it in action in both of those ways.
+
+And now you're going to test it yourself.
+
 ## Your task
 
-- Write the `tests/e2e/authentication-2fa.test.ts`.
-- Implement a `createVerification()` utility.
-- Use `@epic-web/totp` to generate the OTP in the test case.
+👨‍💼 In this one, follow the instructions in <InlineFile filename="./tests/e2e/authentication-2fa.test.ts">`tests/e2e/authentication-2fa.test.ts`</InlineFile> to write an end-to-end test for the two-factor authentication flow in Epic Stack.
+
+🐨 Then, in addition to the `createUser()` utility you've prepared earlier, create another utility called `createVerification()` that would collocate a given user with a One-Time Password (OTP), storing that relationship in the database.
+
+🐨 And, finally, log in with the test user and fill in the OTP input that will appear now as a part of the authentication attempt. As always, have the test passing.

exercises/02.authentication/02.problem.2fa/tests/db-utils.ts

@@ -59,21 +59,20 @@ export async function createVerification(input: {
 	userId: string
 }) {
 	const { otp, ...totpConfig } = input.totp
-	const verification = await prisma.verification.create({
-		data: {
-			...totpConfig,
-			type: '2fa',
-			target: input.userId,
-		},
-	})
+
+	// 🐨 Create a new 2FA verification record in the database
+	// and store it in a variable called "verification".
+	// 💰 await prisma.verification.create({
+	//   data: { ...totpConfig, type: '2fa', target: input.userId }
+	// })
 
 	return {
 		async [Symbol.asyncDispose]() {
-			await prisma.verification.deleteMany({
-				where: { id: verification.id },
-			})
+			// 🐨 Delete the previously created verification record fr om
+			// 💰 await prisma.verification.deleteMany({ where: { ... } })
 		},
-		...verification,
+		// 🐨 Return the verification object by spreading it here.
+		// 💰 ...verification
 	}
 }
 

exercises/02.authentication/02.problem.2fa/tests/e2e/authentication-2fa.test.ts

@@ -6,5 +6,38 @@ test('authenticates using two-factor authentication', async ({
 	navigate,
 	page,
 }) => {
-	/** @todo Instructions */
+	// 🐨 Create a test user by calling "createUser()" and storing
+	// the returned disposable object in a variable called "user".
+	// 💰 await using user = await fn()
+
+	// 🐨 Generate a Time-based One-Time Password (TOPT) using the
+	// "generateTOTP" function from the "@epic-web/totp" package and
+	// store it in a variable called "totp".
+	// 💰 const totp = await generateTOTP()
+
+	// 🐨 Create a verification for the user by calling "createVerification()"
+	// with an object containing the "totp" and the "userId" (which is the
+	// "id" property of the created user). Store the returned disposable
+	// object in placeholder variable "_".
+	// 💰 await using _ = await fn({ totp, userId: user.id })
+
+	await navigate('/login')
+
+	// 🐨 Fill in the "user.username" into the field with the label "Username".
+	// 💰 await page.getByLabel(label).fill(value)
+
+	// 🐨 Fill in the "user.password" into the field with the label "Password".
+	// 🐨 Submit the login form.
+
+	// 🐨 Write an assertion that expects a heading element with the text
+	// "Check your 2FA app" to be visible on the page.
+	// 💰 await expect(page.getByRole(role, { name: name })).toBeVisible()
+
+	// 🐨 Next, generate and enter a new TOTP into the textbox with an
+	// accessible name matching /code/i.
+	// 💰 await page.getByRole(role, { name: name }).fill((await generateTOTP(totp)).otp)
+
+	// 🐨 Finally, add an assertion that expects the link element
+	// with the user's name to be visible on the page.
+	// 💰 await expect(page.getByRole(role, { name: user.name })).toBeVisible()
 })

exercises/02.authentication/02.solution.2fa/README.mdx

@@ -1,22 +1,116 @@
 # Two-factor authentication
 
-## Summary
+The 2FA flow introduces a new element to authentication: One-Time Password. Unlike regular passwords, OTP doesn't get stored anywhere as that would defeat the point of the "One-Time" part. Instead, the server stores a _verification_ record associating a user with a _secret_ that can be used to check whether any OTP actually belongs to that user.
 
-1. Install `@epic-web/totp`. We will use it to generate verification codes for our 2FA test.
-1. In `test/db-utils.ts`, create a new function called `createVerification`. Go through its implementation step-by-step.
-1. Add an `asyncDispose` symbol to auto-cleanup the test data when the test closure it garbage-collected.
+Our test setup has to mirror this specifics if we want to achieve reliable test coverage.
 
----
+## `createVerification()` utility
 
-1. Create a new test at `tests/e2e/authentication-2fa.test.ts`.
-1. Use the `createUser` utility to create a random user.
-1. Use the `generatTOTP` from `@epic-web/totp` to generate an OTP.
-1. Use the new `createVerification` utility to generate a verification code with the given OTP for the given test user.
-1. Go to the login page, log in using the credentials.
-1. Wait until the 2FA verification prompt becomes visible.
-1. Enter the generated verification code.
-1. Verify that the auth was successful by the visibility of the user profile link.
+Just like creating test users with `createUser()`, the OTP verification record is one more server-side resource we need to seed for the test. To actually create OTP tokens, we are going to use a library called [`@epic-web/totp`](https://github.com/epicweb-dev/totp). This is _not_ a testing library. In fact, if you examine the authentication code for Epic Stack, you can quickly spot that we are using it to back up the actual authentication. This kind of reusage is most welcome in tests.
 
----
+```ts filename=test/db-utils.ts add=6-12,16-18
+export async function createVerification(input: {
+	totp: Awaited<ReturnType<typeof generateTOTP>>
+	userId: string
+}) {
+	const { otp, ...totpConfig } = input.totp
+	const verification = await prisma.verification.create({
+		data: {
+			...totpConfig,
+			type: '2fa',
+			target: input.userId,
+		},
+	})
 
-1. `npm run test:e2e`. to confirm.
+	return {
+		async [Symbol.asyncDispose]() {
+			await prisma.verification.deleteMany({
+				where: { id: verification.id },
+			})
+		},
+		...verification,
+	}
+}
+```
+
+> The exact shape of the verification record (`type`, `target`, etc.) is, once again, dictated by our application's architecture. Make sure your test setup reflects <u>**your**</u> application.
+
+## Testing Two-factor authentication
+
+With `createVerification()` ready, we've got all the pieces we need to put our application into the right state for testing the 2FA flow.
+
+```ts filename=tests/e2e/authentication-2fa.test.ts
+import { generateTOTP } from '@epic-web/totp'
+import { createUser, createVerification } from '#tests/db-utils.ts'
+import { test, expect } from '#tests/test-extend.ts'
+
+test('authenticates using two-factor authentication', async ({
+	navigate,
+	page,
+}) => {
+	// Setup.
+	await using user = await createUser()
+	const totp = await generateTOTP()
+	await using _ = await createVerification({
+		totp,
+		userId: user.id,
+	})
+
+	await navigate('/login')
+
+	// Actions.
+	await page.getByLabel('Username').fill(user.username)
+	await page.getByLabel('Password').fill(user.password)
+	await page.getByRole('button', { name: 'Log in' }).click()
+
+	// Assertions.
+	await expect(
+		page.getByRole('heading', { name: 'Check your 2FA app' }),
+	).toBeVisible()
+
+	// Actions.
+	await page
+		.getByRole('textbox', { name: /code/i })
+		.fill((await generateTOTP(totp)).otp)
+
+	await page.getByRole('button', { name: 'Submit' }).click()
+
+	// Assertions.
+	await expect(page.getByRole('link', { name: user.name! })).toBeVisible()
+})
+```
+
+Let's take a moment to appreciate how genuinely straightforward this test is. Despite tackling a rather complex flow, the test case itself reads not unlike a regular component test. **This is not a coincidence but a direct result of managing complexity through the test setup.**
+
+`createUser()` and `generateTOTP()` and `createVerification()` are complex functions doing complex things, but they aren't leaking any of that complexity into the test case. Instead, they encapsulate it in clean and understandable steps:
+
+1. Create a test user;
+1. Genereate a One-Time Password;
+1. Create a verification for this user and this OTP.
+
+They expose control while offloading the implementation details and the complexity behind them to the backstage—to the test setup—where it belongs. And they give you a nice eagle-eye overview of what this test case involves, which is also nice!
+
+The key part here is that once we arrive at the "Check your 2FA app" page, we enter a new TOTP the same way a user would open their password manager and copy-paste a new token into our app:
+
+```ts
+await expect(
+	page.getByRole('heading', { name: 'Check your 2FA app' }),
+).toBeVisible()
+
+await page
+	.getByRole('textbox', { name: /code/i })
+	.fill((await generateTOTP(totp)).otp)
+```
+
+The rest of this test case interacts with the application and asserts on the UI the same way we did in the previous tests and requires no further explanation.
+
+## Running tests
+
+```
+npm run test:e2e
+```
+
+## Related materials
+
+- [(Video) Dissecting Complexity in Tests](https://www.youtube.com/watch?v=nUozijHdgMM&t=419s)
+- [`@epic-web/totp`](https://github.com/epicweb-dev/totp)

exercises/02.authentication/02.solution.2fa/tests/e2e/authentication-2fa.test.ts

@@ -6,15 +6,13 @@ test('authenticates using two-factor authentication', async ({
 	navigate,
 	page,
 }) => {
-	// Create a test user and enable 2FA for them directly in the database.
 	await using user = await createUser()
 	const totp = await generateTOTP()
 	await using _ = await createVerification({
 		totp,
 		userId: user.id,
 	})
 
-	// Log in as the created user.
 	await navigate('/login')
 
 	await page.getByLabel('Username').fill(user.username)