Workshop 2: Live demo script

Share-screen guide. Walk through these steps with students mirroring in their own clones. Total time: ~20 minutes (the workshop's two hands-on blocks combined).

Setup before the demo

• Have my terminal split: editor on top, terminal on bottom.
• Have baseline.log open in the editor.
• Repo state: clean, no edits.

---

Demo 1: Reading a build log together (Block 2, ~5 min)

Goal: show students how to scan timing data for outliers.

1. Open baseline.log in my editor. Share screen.

   "This is the file we generated last week. Let's read it line by line."

2. Walk down the stages, calling out durations:

   • test:api: ~12 min (~95% of the whole run): "this is the hot spot. Everything else is a rounding error next to it. We're going to break this one open right now."
   • install: ~7s: "barely registers, and yes, that surprises people. The dependency download is not the problem here."
   • Everything else (lint, typecheck, test:web, builds, deploy): ~1–18s each: "all candidates someday, but noise compared to test:api."

3. Have students open their own baseline.log and confirm the same ranking; test:api should dwarf everything. Take questions for ~1 minute.

---

Demo 2: Profiling the slow test (Block 2, ~5 min)

Goal: identify the specific test that dominates test:api.

1. Run the api test suite with reporters:

   cd apps/api && npx jest --verbose

2. Scroll up to find the slow line:

   ✓ rolls up end-of-month billing across many customers (~16000–24000 ms; your number will vary)

   "Sixteen-plus seconds. One test. And it's not alone."

3. Open the file: apps/api/tests/reports.test.ts. Read the test out loud. Note the loop with ~50 real HTTP calls (25 users × enroll + charge).

4. Now open the directory apps/api/tests/integration/: billing.rollup, email.campaigns, webhooks.fanout, search.reindex, notifications.blast. "This whole suite is the same shape: each test makes many real HTTP round-trips, run serially under maxWorkers: 1. Together they, not any single test, are why test:api takes ~12 minutes."

5. Have students open the same files. Ask: "What do you think makes this slow?" Take 2–3 answers from the chat.

---

Demo 3: 5 Whys on the slow test (Block 3, ~5 min)

Goal: model the technique so students can apply it themselves in Block 4.

Run the 5 Whys live, on screen, with students contributing answers:

Why	Q	A
1	Why is this test slow?	It makes 50 real HTTP round-trips to the mock billing service.
2	Why does it use real HTTP?	Because the test calls BillingService which uses BillingClient which uses fetch.
3	Why isn't BillingClient mocked?	Because there's no manual mock, and no team convention to add one.
4	Why is there no convention?	The team adopted external service tests without writing guidelines.
5	Why?	Standards weren't a priority when the codebase was small. They are now.

Root cause: missing AI/external-service mocking convention. We address it in Workshop 7.

Tactical fix: add a manual mock for BillingClient. We do that together in Workshop 5.

---

Demo 4: Catching the flaky test live (Block 4, ~5 min)

Goal: show students that flaky tests are non-deterministic, then walk through a 5 Whys.

1. Run the reports tests three times in a row:

   cd apps/api && npx jest --testPathPattern=reports

2. One of those runs will fail on:

   ✗ processes async events within budget

   "Same test, same code, sometimes pass, sometimes fail. This is the canonical flaky-test smell."

3. Open the test file. Show the Promise.race against Math.random(). Run the 5 Whys live:

Why	A
Why does it sometimes fail?	The "fast" branch uses a random delay 50–250ms; the "slow" branch is fixed at 150ms. When the random side is > 150ms, fast loses.
Why is the assertion timing-dependent?	The test asserts on which promise resolves first, which is by definition timing-dependent.
Why?	The test was written quickly and depends on real wall-clock time.
Why didn't a code review catch it?	No team standard for "tests must be deterministic."

Root cause: the same as the slow test, missing engineering standards (W7).

Tactical fix: use vi.useFakeTimers() and advance time manually. We do that together in Workshop 5.

---

After the live demo

Send a chat message:

"You've seen me run the technique twice. Now we do it together on your top 3 bottlenecks. 10 minutes, start now, I'm on screen with you."

We run the top-3 5 Whys together, live: I keep my screen up and work it alongside the room while students fill their W2 logbook section. The first demo gave them the pattern; doing it together in session cements it. Anyone who wants to tidy their logbook notes afterward can, but that's optional polish.