add 01/01 exercise text

Author: kettanaito

exercises/01.fundamentals/01.problem.install-and-configure/README.mdx

@@ -13,12 +13,12 @@ npm i @playwright/test --save-dev
 🐨 Then, install the binaries of the browsers you want to use for automated tests. In this workshop, we will be using Chromium for browser automation. Install it using this command:
 
 ```sh
-npx playwright install --with-deps chromium
+npx playwright install chromium --with-deps
 ```
 
 🐨 Next, create `playwright.config.ts` file at the root of your project. This is Playwright's configuration file. You will use it to set up Playwright in the way that makes sense for your project.
 
-🐨 In `package.json`, create a new script called `test`. You will use this script to run your end-to-end tests at the end of this exercise. Use the `npx playwright test` command as the value for that script.
+🐨 In `package.json`, create a new script called `test:e2e`. You will use this script to run your end-to-end tests at the end of this exercise. Use the `npx playwright test` command as the value for that script.
 
 🐨 Create a directory called `tests`. In that directory, create a new test file called `epicweb.test.ts`.
 
@@ -45,4 +45,4 @@ To do that, your test would have to perform a series of steps:
 
 3. Assert that the heading element is visible on the page via `await expect(element).toBeVisible()`.
 
-🐨 Finally, run this test via `npm test` in the terminal. You should see it passing.
+🐨 Finally, run this test via `npm run test:e2e` in the terminal. You should see it passing.

exercises/01.fundamentals/01.solution.install-and-configure/README.mdx

@@ -1,22 +1,245 @@
 # Install & configure
 
-## Summary
+## Installation
 
-1. Install Playwright.
-1. Create `playwright.config.ts`.
-1. Specify `projects` using Chromium as the browser.
-1. Specify quality-of-life options like `fullyParallel` or `forbidOnly`.
-1. A brief mention of `workers` set to `1` on CI.
+### Choosing the right package
 
----
+There are actually _two_ different packages shipped by Playwright:
 
-1. Create a simple test at `./tests/epicweb.test.ts`.
-1. Test block structure (`test()`).
-1. The `page` fixture.
-1. Use `page.goto()` to visit pages (external and internal).
-1. Promise-based `expect()` assertions (retriability).
+- `playwright`, which is a library to help you automate browsers;
+- `@playwright/test`, which is a testing framework build on top of the aforementioned library.
 
----
+Today, you would need the latter so let's get it installed:
 
-1. Add the `test:e2e` script in `package.json` that runs Playwright.
-1. Run the test via `npm run test:e2e`. See the result.
+```sh
+npm i @playwright/test --save-dev
+```
+
+> I'm installing this package as a development dependency (`--save-dev`), but this is not required. The distinction between save/dev dependencies is irrelevant in the context of enterprise applications.
+
+### Installing browser binaries
+
+You can think of Playwright as a wrapped around the browser. And as such, it doesn't actually ship any browsers with it. You have to install the exact browser binaries you need to test your application.
+
+Luckily, Playwright comes with a CLI to help you do that (**don't run it just yet**):
+
+```sh
+npx playwright install
+```
+
+Without any arguments, this command will install _all binaries for all supported browsers_. This includes Chromium, Firefox, WebKit... That's quite a lot! Especially if you aren't using all of those browsers to test your app.
+
+In this workshop, you will be using Chromium exclusively so it makes sense to install just that binary:
+
+```sh
+npx playwright install chromium --with-deps
+```
+
+> Notice the `--with-deps` flag here, which makes sure that all the system dependencies required by this browser binary are also installed. This is less relevant for local use but is extremely handy when running Playwright on CI.
+
+## Configuration
+
+Okay, so you've got Playwright installed. Now it's time to configure it.
+
+Create a file called `playwright.config.ts` at the root of your project and fill it with a minimal configuration options:
+
+```ts filename=playwright.config.ts
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+	projects: [
+		{
+			name: 'chromium',
+			use: {
+				...devices['Desktop Chrome'],
+			},
+		},
+	],
+	fullyParallel: true,
+	forbidOnly: !!process.env.CI,
+	workers: process.env.CI ? 1 : undefined,
+})
+```
+
+Let's go through every option and see what it does one-by-one.
+
+### Projects
+
+Similar to Vitest, you can have multiple test projects in Playwright. This allows you to decouple the test suites from the orchestration that runs it. In practice, this means you can:
+
+- Have the same tests run in multiple browsers;
+- Have unique test suites that run only in some browsers;
+- Have browsers configured a certain way to make test cases possible (e.g. specific viewport sizes, enabling `prefers-reduced-motion`, using different locales or timezones).
+
+```ts filename=playwright.config.ts highlight=4-11
+// ...
+
+export default defineConfig({
+	projects: [
+		{
+			name: 'chromium',
+			use: {
+				...devices['Desktop Chrome'],
+			},
+		},
+	],
+	// ...
+})
+```
+
+In our case, we have a single project that uses `Desktop Chrome` as the browser.
+
+### Full parallelization
+
+Similar to Vitest, Playwright has the same behaviors when it comes to concurrency and parallelization:
+
+- All test _files_ run in parallel in isolated workers;
+- All test _cases_ in those files run sequentially.
+
+This is a good default, but we are going to opt out from it and make all our test cases run concurrently by setting `fullyParallel` option to `true`:
+
+```ts filename=playwright.config.ts highlight=5
+// ...
+
+export default defineConfig({
+	// ...
+	fullyParallel: true,
+	// ...
+})
+```
+
+### Forbidding `test.only`
+
+Isolating invididual test cases while writing or debugging tests can be really handy. Playwright supports that via `test.only()`. The problem is, it's extremely easy to forget about a test case you've isolated and get your CI running just that single test 😬
+
+There's an option to guard you from that mistake by making Playwright throw an error if it detects `test.only`. Naturally, let's set that option to `true` only for remote, CI runs:
+
+```ts filename=playwright.config.ts highlight=5
+// ...
+
+export default defineConfig({
+	// ...
+	forbidOnly: !!process.env.CI,
+	// ...
+})
+```
+
+> The `process.env.CI` environment variable is commonly set by CI providers, like GitHub Actions. Make sure to fine-tune this condition if your provider marks the environment differently.
+
+### Worker count
+
+The last thing we are going to configure is the `workers` option that controls the number of parallel workers spawned for each test run. By default, Playwright will use _half_ of your available CPU cores for that, but that can cause trouble in CI runs.
+
+It's generally recommended to use a _single_ worker for your end-to-end tests on CI.
+
+```ts filename=playwright.config.ts highlight=5
+// ...
+
+export default defineConfig({
+	// ...
+	workers: process.env.CI ? 1 : undefined,
+	// ...
+})
+```
+
+This means _slower_ but more _reliable_ test results on machines that are normally nowhere near as powerful as those you use for development.
+
+> Note that you should configure Playwright to suit the specifics of your CI context. Today, we are going through the safe defaults that make sense in the majority of projects. The beauty is, **you can opt out from them!** And I strongly encourage you to experiment with your environment and find the optimal options for your end-to-end tests.
+
+## Writing a test
+
+End-to-end tests follow the same test anatomy you already know.
+
+```ts
+import { test, expect } from '@playwright/test'
+
+test('test title', testFunction)
+```
+
+> Note that Playwright does _not_ expose its functions, like `test` or `expect` globally, and those have to be imported.
+
+The test case we have at hand today is the one that makes sure a correct heading is displayed on the Epic Web website. So let's give this test a descriptive name and navigate to `https://epicweb.dev/` for starters.
+
+```ts add=2
+test('displays the page heading', async ({ page }) => {
+	await page.goto('https://epicweb.dev/')
+})
+```
+
+In Playwright, you use the `page` object from the test context argument to interact with the underlying browser page. For example, calling `page.goto()` will trigger a navigation to the given URL!
+
+<callout-warning>
+
+The test context **MUST** be destructured in Playwright. The framework analyzes which context properties each test uses to implement lazy fixtures.
+
+```ts remove=1-3 add=5-7
+test('displays the page heading', async (context) => {
+	await context.page.goto(url)
+})
+
+test('displays the page heading', async ({ page }) => {
+	await page.goto(url)
+})
+```
+
+</callout-warning>
+
+### Locating elements
+
+Next, let's find the `<h1>` element on the page that we want to assert on. You can use many of the `page.getBy*` utilities to locate elements by their accessible role, associated label text, text content, etc.
+
+Let's use `page.getByRole()` to locate the heading we need by its role (`heading`) and its accessible name, which in case of the heading elements equals to its text content.
+
+```ts add=6-8
+import { test, expect } from '@playwright/test'
+
+test('displays the page heading', async ({ page }) => {
+	await page.goto('https://epicweb.dev/')
+
+	page.getByRole('heading', {
+		name: 'Full Stack Workshop Training for Professional Web Developers',
+	})
+})
+```
+
+When you find elements on the page, you don't get a direct reference to their DOM nodes straight away. Instead, Playwright gives you a _locator_. Think of it as a promise to that element that will be resolved only when the element is needed. For example, when you assert on it.
+
+### Assertions
+
+Finally, let's express some expectations, shall we?
+
+We've already located the heading element we need, and all that remains is to make sure that it is visible on the page. To do that, use the `expect()` function, provide it the locator of the element you want to assert on, and use one of the many available matchers, like `.toBeVisible()`, for example.
+
+```ts add=6-10
+import { test, expect } from '@playwright/test'
+
+test('displays the page heading', async ({ page }) => {
+	await page.goto('https://epicweb.dev/')
+
+	await expect(
+		page.getByRole('heading', {
+			name: 'Full Stack Workshop Training for Professional Web Developers',
+		}),
+	).toBeVisible()
+})
+```
+
+> Note that matchers in Playwright _return a promise_ that you have to await. That is because every assertion is retryable by default to deal with asynchronicity and race conditions—two common problems that result in flakiness if left unchecked.
+
+## Running tests
+
+Now that the test is ready, let's run it, using the npm script we've prepared earlier:
+
+```
+npm run test:e2e
+```
+
+```
+Running 1 test using 1 worker
+
+  ✓  1 [chromium] › tests/epicweb.test.ts:3:5 › displays the page heading (935ms)
+
+  1 passed (2.8s)
+```
+
+Sweet! :tada:

exercises/01.fundamentals/FINISHED.mdx

@@ -1,5 +1,5 @@
 # Fundamentals
 
-Congratulations, you've completed this exercise block! 🥳 Let's have a short rest and continue.
+Congratulations, you've completed this exercise block! 🥳 Have a short break and let's continue.
 
 <callout-success>Meanwhile, I would be grateful if you _filled out the feedback form_ on your right. Your feedback helps me polish the exercises and improve the workshop before recording it. Thank you!</callout-success>

exercises/01.fundamentals/README.mdx

@@ -1 +1,3 @@
 # Fundamentals
+
+First, let's get on the same page when it comes to what an end-to-end test is and what it's meant for. Join me to learn how end-to-end tests complete your testing strategy without repeating everything you have tested before; how these tests manifest themselves in other mediums of software; what contributes to the infamous reputation of end-to-end tests being slow and flaky; what modern end-to-end testing frameworks you can choose from today, and which one you will be using in this workshop.

exercises/02.authentication/README.mdx

@@ -1,6 +1,8 @@
 # Authentication
 
-- Authentication is both a feature to test and a prerequisite to test other features.
-- A login page example.
-- Users log in to _do_ something. Those actions treat authentication as a _given_.
-- In this block, you will learn how to test different authentication methods as well as how to provision authentication state as a part of your test setup.
+Authentication is an inseparable part of end-to-end tests just like it is an inseparable part of your applications. But there's a catch. Authentication encompases _two_ distinct areas from the testing perspective:
+
+- **Authentication as a feature**. These are the authentication options you provide to your users (e.g. email+password, 2FA, passkeys, third-party providers);
+- **Authentication as a dependency**. The functionality behind authentication (e.g. managing resources, performing authorized operations).
+
+In this block, you will learn about the difference between testing authentication as a feature and testing features that are behind authentication with Playwright.

exercises/README.mdx

@@ -1 +1,31 @@
 # End-to-end React Testing with Playwright
+
+Hi :wave: Artem's here.
+
+Today, you and I are going to explore end-to-end tests. You know the type—expensive, slow, and unreliable. Only you won't be writing any of those. Instead, I will teach you how to use Playwright to test your web applications in a meaningful and performant way.
+
+## Exercises
+
+This workshop consists of four exercise blocks.
+
+### Fundamentals
+
+You will start by installing Playwright and covering the essential configuration options for a great testing experience both locally and on CI. You will get familiar with the test structure, using the `page` object, and why it gives you element _locators_ instead of direct DOM references. And you will wrap up by writing your own custom fixture for type-safe page navigation in your end-to-end tests.
+
+### Authentication
+
+In this one, you will learn the differnce between testing authentication as a feature and testing features that are _behind_ authentication (yes, those require entirely different approaches). You will write tests for the most common authentication methods in web applications:
+
+- **Basic**, where you will create a disposable `createUser()` utility that will create a test user in the database and delete it when the test is done;
+- **Two-factor Authentication**, where you will create test OTP tokens and store their verification records in the database for your test user;
+- **Passkeys**, where you will leverage a Chrome Developer Protocol session to create a web autnentication client with the passkey you provide and use it in your test.
+
+After that, you will explore how to create and manage authentication in your test setup using [Personas](https://github.com/kettanaito/playwright-persona)—reproducible snapshots of different authentication states that bridge the DX gap of `setStorageState` in Playwright.
+
+### Guides
+
+Next, you will dive straight into practical tips for writing end-to-end tests: from provisioning mock databases and test data to mocking client-side requests. As a bonus, I will show you how to write tests by recording your interactions in the browser using Playwright's extension for Visual Studio Code.
+
+### Debugging
+
+It's become somewhat of a tradition to include debugging techniques in my workshops, and this one will be no different. In the final section, you will master the UI mode to preview and debug your tests _visually_ and after that, learn how to debug failed CI tests with the Trace Viewer (this is, seriously, such a time-saver).