@shaykec/bridge 0.4.24 → 0.4.26

package/modules/test-strategy/content.md

@@ -0,0 +1,136 @@
+# Test Strategy — Pyramids, Diamonds, and What to Test
+
+<!-- hint:slides topic="Test strategy: test pyramid, what to test vs skip, test doubles, CI placement, and coverage tradeoffs" slides="5" -->
+
+## Why Test?
+
+Tests give you **confidence to change**. They document behavior, catch regressions, and make refactoring safe. Without tests, every change is a gamble.
+
+## The Classic Test Pyramid
+
+Martin Fowler popularized the **test pyramid**: many fast, cheap unit tests at the base; fewer integration tests in the middle; and few slow, expensive end-to-end (e2e) tests at the top.
+
+```mermaid
+flowchart TB
+    subgraph E2E_layer[E2E - few, slow]
+        E2E[E2E Tests]
+    end
+    subgraph INT_layer[Integration - some]
+        INT[Integration Tests]
+    end
+    subgraph UNIT_layer[Unit - many, fast]
+        UNIT[Unit Tests]
+    end
+    UNIT_layer --> INT_layer
+    INT_layer --> E2E_layer
+```
+
+```mermaid
+flowchart TB
+    subgraph pyramid["Test Pyramid"]
+        E2E["E2E Tests\n(slow, few)\nFull user flows"]
+        INT["Integration Tests\n(medium)\nComponents + DB/API"]
+        UNIT["Unit Tests\n(fast, many)\nSingle functions/classes"]
+    end
+    UNIT --> INT
+    INT --> E2E
+```
+
+### Layer Characteristics
+
+| Layer | What it tests | Speed | Isolation | Count |
+|-------|---------------|-------|-----------|-------|
+| **Unit** | Single function or class in isolation | Fast (ms) | High — mocks/stubs | Many |
+| **Integration** | Components working together (DB, API, services) | Medium (seconds) | Medium — real deps | Some |
+| **E2E** | Full user journey (UI → backend) | Slow (minutes) | Low — real everything | Few |
+
+```javascript
+// Unit: pure function, no I/O
+function add(a, b) { return a + b; }
+// Test: expect(add(2, 3)).toBe(5);
+
+// Integration: hits DB or API
+async function getUser(id) {
+  const res = await db.query('SELECT * FROM users WHERE id = ?', [id]);
+  return res.rows[0];
+}
+
+// E2E: browser clicks → server → DB → response
+// Playwright/Cypress: click "Login", fill form, assert dashboard
+```
+
+## The Testing Diamond (or Trophy)
+
+Some teams invert the pyramid: more integration tests than unit tests. The **diamond** or **trophy** shape reflects that business logic often lives in integration layers. The idea: test what matters, where it matters.
+
+```
+       /\
+      /  \   E2E (few)
+     /----\
+    /      \  Integration (many)
+   /--------\
+  /          \  Unit (some)
+  -------------
+```
+
+## What to Test
+
+| Focus | Examples |
+|-------|----------|
+| **Happy path** | User logs in with valid credentials → sees dashboard |
+| **Edge cases** | Empty list, max length, boundary values |
+| **Error paths** | Invalid input, network failure, permission denied |
+| **Contracts** | API returns expected shape; component accepts valid props |
+
+## What NOT to Test
+
+- **Implementation details** — Don't assert on internal state that might change during refactoring.
+- **Third-party code** — Trust libraries; mock them if needed.
+- **Trivial code** — Getters/setters with no logic.
+- **Everything** — Diminishing returns; prioritize risk.
+
+## Test Doubles: Mocks, Stubs, Spies
+
+| Type | Purpose |
+|------|---------|
+| **Stub** | Returns canned data; no verification |
+| **Mock** | Verifies it was called (expectations) |
+| **Spy** | Records calls; can assert after |
+
+```javascript
+// Stub: fake DB returns specific data
+const stubDb = { query: () => ({ rows: [{ id: 1, name: 'Alice' }] }) };
+
+// Mock: expect fetch to be called with specific URL
+const mockFetch = vi.fn();
+expect(mockFetch).toHaveBeenCalledWith('/api/users');
+```
+
+## Code Coverage
+
+Coverage tells you **what you didn't test**. It's useful for finding gaps, but **100% coverage is not a goal**. Aim for meaningful coverage of critical paths; avoid testing for coverage's sake.
+
+## Testing in CI/CD
+
+- Run unit tests on every commit (fast feedback).
+- Run integration tests on push to main.
+- Run e2e tests on release branches or nightly.
+
+```mermaid
+flowchart LR
+    A[Commit] --> B[Unit Tests]
+    B --> C[Integration Tests]
+    C --> D[E2E Tests]
+    D --> E[Deploy]
+```
+
+---
+
+## Key Takeaways
+
+1. **Pyramid**: Many unit, some integration, few e2e.
+2. **Test what matters**: Happy path, edge cases, error paths.
+3. **Don't test**: Implementation details, third-party code.
+4. **Use doubles** when you need isolation or speed.
+5. **Coverage** is a metric, not a goal.
+6. **CI/CD**: Fast tests first; gate deploys on passing tests.

package/modules/test-strategy/exercises.md

@@ -0,0 +1,84 @@
+# Test Strategy Exercises
+
+## Exercise 1: Draw Your Pyramid
+
+**Task:** Pick a feature in a project you know (or a hypothetical one). Draw a test pyramid with 3 layers. For each layer, list 2–3 example tests. Estimate: how many of each? (e.g., 20 unit, 5 integration, 2 e2e)
+
+**Validation:**
+- [ ] Unit tests focus on single functions/classes
+- [ ] Integration tests involve at least 2 components or real I/O
+- [ ] E2E tests cover a full user flow
+- [ ] Counts follow pyramid (many unit, few e2e)
+
+**Hints:**
+1. Start with the main user flows — what's critical?
+2. Unit = logic you can run in memory with no DB/network
+3. Integration = DB, API, file system, message queues
+
+---
+
+## Exercise 2: Happy Path, Edge Case, Error Path
+
+**Task:** For a function `divide(a, b)` that returns `a / b`, write test case descriptions (not code) for: (a) happy path, (b) 2 edge cases, (c) 1 error path.
+
+**Validation:**
+- [ ] Happy path: normal inputs, expected output
+- [ ] Edge cases: e.g., divide by 1, divide 0 by something
+- [ ] Error path: e.g., divide by 0 — what should happen?
+
+**Hints:**
+1. Edge = boundaries, empty, single item, max values
+2. Error = invalid input, exceptional conditions
+3. Consider: does divide(0, 5) return 0? Is that edge or happy?
+
+---
+
+## Exercise 3: Stub vs Mock
+
+**Task:** You're testing `checkout(cart, paymentService)`. The function calls `paymentService.charge(total)` and returns a receipt. Write two test scenarios in plain English: one where a stub is enough, one where you need a mock.
+
+**Validation:**
+- [ ] Stub scenario: you only care about the return value / receipt
+- [ ] Mock scenario: you need to verify charge was called with correct amount
+- [ ] Explanation of when each is appropriate
+
+**Hints:**
+1. Stub = "fake the answer so the code under test can run"
+2. Mock = "verify the collaborator was used correctly"
+3. Would you trust the code if charge was never called?
+
+---
+
+## Exercise 4: What NOT to Test
+
+**Task:** Review this list. Which would you skip testing? Why?
+- A React component that renders `{user.name}`
+- A function that parses a query string into an object
+- A wrapper that calls `axios.get(url)` and returns `response.data`
+- A sorting function that orders items by date
+
+**Validation:**
+- [ ] Identifies thin wrappers / third-party usage as low value
+- [ ] Identifies parsing/sorting as good candidates (logic)
+- [ ] Can justify each decision
+
+**Hints:**
+1. Trivial = no branching, no logic
+2. Third-party = you don't own it; maybe one smoke test
+3. Business logic = always test
+
+---
+
+## Exercise 5: Coverage Trap
+
+**Task:** A team boasts 95% line coverage. You discover their tests mostly do `expect(fn()).toBeDefined()` and rarely assert on actual behavior. Write 3 guidelines for "meaningful" coverage vs "coverage for its own sake."
+
+**Validation:**
+- [ ] Meaningful = asserts behavior, not just "it didn't throw"
+- [ ] Guideline about edge cases and error paths
+- [ ] Guideline about refactoring — tests should catch regressions
+
+**Hints:**
+1. What would 95% coverage miss if assertions are shallow?
+2. If you change behavior, would the test fail?
+3. Coverage can be gamed; what can't be gamed?

package/modules/test-strategy/game.yaml

@@ -0,0 +1,99 @@
+games:
+  - type: classify
+    title: "Test Layer Classifier"
+    categories:
+      - name: "Unit Test"
+        color: "#58a6ff"
+      - name: "Integration Test"
+        color: "#3fb950"
+      - name: "E2E Test"
+        color: "#d29922"
+    items:
+      - text: "Tests a single function in isolation with dependencies mocked. Fast, many tests."
+        category: "Unit Test"
+      - text: "Spins up a real database, hits real endpoints, verifies service + DB together."
+        category: "Integration Test"
+      - text: "Launches the full app in a browser, simulates user clicks, checks rendered UI."
+        category: "E2E Test"
+      - text: "Tests that UserRepository.save() correctly persists to the DB with a test DB."
+        category: "Integration Test"
+      - text: "Tests formatPrice(99.99) returns '$99.99' with no external deps."
+        category: "Unit Test"
+      - text: "Uses Playwright to log in, add item to cart, and complete checkout flow."
+        category: "E2E Test"
+      - text: "Mocks PaymentService; tests OrderService.applyDiscount() with fake payment client."
+        category: "Unit Test"
+      - text: "Starts API server + DB, sends HTTP request, asserts response and DB state."
+        category: "Integration Test"
+      - text: "Tests a React component with React Testing Library; mocks child components."
+        category: "Unit Test"
+      - text: "Runs in a real browser, tests full signup → email verify → first login flow."
+        category: "E2E Test"
+
+  - type: speed-round
+    title: "Test Double Sprint"
+    rounds:
+      - question: "You need to verify that sendEmail() was called with the user's address. Which double?"
+        options:
+          - "Stub"
+          - "Mock"
+          - "Fake"
+          - "Dummy"
+        answer: 1
+        timeLimit: 16
+      - question: "You need a simple object to satisfy a parameter but never use it. Which?"
+        options:
+          - "Mock"
+          - "Stub"
+          - "Spy"
+          - "Dummy"
+        answer: 3
+        timeLimit: 16
+      - question: "You need to return a fixed response without hitting the real API. Which?"
+        options:
+          - "Mock"
+          - "Stub"
+          - "Spy"
+          - "Dummy"
+        answer: 1
+        timeLimit: 16
+      - question: "You want to record calls to a method for later assertion. Which?"
+        options:
+          - "Stub"
+          - "Spy"
+          - "Fake"
+          - "Dummy"
+        answer: 1
+        timeLimit: 16
+      - question: "You need a working in-memory implementation instead of real DB. Which?"
+        options:
+          - "Mock"
+          - "Stub"
+          - "Fake"
+          - "Dummy"
+        answer: 2
+        timeLimit: 16
+      - question: "You need to assert that a method was called exactly once. Which double?"
+        options:
+          - "Stub"
+          - "Mock"
+          - "Fake"
+          - "Dummy"
+        answer: 1
+        timeLimit: 16
+      - question: "You need to replace a slow service with a simple return value. Which?"
+        options:
+          - "Mock"
+          - "Stub"
+          - "Spy"
+          - "Dummy"
+        answer: 1
+        timeLimit: 15
+      - question: "You wrap a real object to record its calls. Which?"
+        options:
+          - "Stub"
+          - "Mock"
+          - "Spy"
+          - "Dummy"
+        answer: 2
+        timeLimit: 16

package/modules/test-strategy/module.yaml

@@ -0,0 +1,45 @@
+slug: test-strategy
+title: "Test Strategy — Pyramids, Diamonds, and What to Test"
+version: 1.0.0
+description: "Design a balanced test strategy: the test pyramid, diamonds, and what to test at each layer."
+category: quality-assurance
+tags: [testing, test-strategy, test-pyramid, unit-tests, integration-tests, e2e]
+difficulty: beginner
+
+xp:
+  read: 10
+  walkthrough: 30
+  exercise: 20
+  quiz: 15
+  quiz-perfect-bonus: 10
+  game: 20
+  game-perfect-bonus: 10
+
+time:
+  quick: 5
+  read: 15
+  guided: 45
+
+prerequisites: []
+related: [exploratory-testing, debugging-systematically]
+
+triggers:
+  - "What should I test?"
+  - "What is the test pyramid?"
+  - "How many unit tests do I need?"
+  - "What's the difference between unit, integration, and e2e tests?"
+
+visuals:
+  diagrams: [diagram-mermaid, diagram-flow]
+  quiz-types: [quiz-drag-order, quiz-matching]
+  game-types: [classify, speed-round]
+  playground: javascript
+  slides: true
+
+sources:
+  - url: "https://martinfowler.com/articles/practical-test-pyramid.html"
+    label: "The Practical Test Pyramid (Martin Fowler)"
+    type: docs
+  - url: "https://www.amazon.com/Test-Driven-Development-Kent-Beck/dp/0321146530"
+    label: "TDD by Kent Beck (book)"
+    type: book

package/modules/test-strategy/quick-ref.md

@@ -0,0 +1,66 @@
+# Test Strategy — Quick Reference
+
+## Test Pyramid
+
+| Layer | What It Tests | Speed | Count |
+|-------|---------------|-------|-------|
+| **Unit** | Single function/class in isolation | Fast (ms) | Many |
+| **Integration** | Components + DB/API/services | Medium | Some |
+| **E2E** | Full user journey (UI → backend) | Slow (min) | Few |
+
+**Rule:** Many unit, some integration, few e2e.
+
+## What to Test
+
+| Focus | Examples |
+|-------|----------|
+| **Happy path** | Valid input → expected output |
+| **Edge cases** | Empty list, boundary values, max length |
+| **Error paths** | Invalid input, network failure, permission denied |
+| **Contracts** | API shape, component props |
+
+## What NOT to Test
+
+- **Implementation details** — Internal state, hook call counts
+- **Third-party code** — Trust libraries; mock if needed
+- **Trivial code** — Getters/setters with no logic
+- **Everything** — Prioritize risk; diminishing returns
+
+## Test Doubles
+
+| Type | Purpose |
+|------|---------|
+| **Stub** | Returns canned data; no verification |
+| **Mock** | Verifies it was called (expectations) |
+| **Spy** | Records calls; assert after |
+
+**When stub:** You only need a fake response.  
+**When mock:** You need to verify the collaborator was used correctly.
+
+## CI/CD Order
+
+```
+Commit → Unit (fast) → Integration → E2E → Deploy
+```
+
+- Unit + integration: every PR
+- E2E: merge to main or nightly (optional per-PR)
+
+## Coverage
+
+- **Use:** Find gaps in critical paths
+- **Don't:** Aim for 100%; avoid testing for coverage's sake
+- **Meaningful coverage:** Assert behavior, not just "didn't throw"
+
+## Diamond/Trophy Shape
+
+Some teams invert the pyramid: more integration than unit. Use when business logic lives in integration layers. Test what matters, where it matters.
+
+## Quick Checklist
+
+- [ ] Unit tests for logic, validation, edge cases
+- [ ] Integration tests for DB, API, services
+- [ ] E2E for critical user flows (few)
+- [ ] Stub/mock external dependencies in unit tests
+- [ ] Avoid asserting on implementation details
+- [ ] Run fast tests first in CI

package/modules/test-strategy/quiz.md

@@ -0,0 +1,99 @@
+# Test Strategy Quiz
+
+## Question 1
+
+In the classic test pyramid, which layer should have the most tests?
+
+A) Integration tests
+B) End-to-end tests
+C) Unit tests
+D) All layers should have roughly equal numbers
+
+<!-- ANSWER: C -->
+<!-- EXPLANATION: The test pyramid recommends many fast, cheap unit tests at the base; fewer integration tests in the middle; and few slow e2e tests at the top. Unit tests run quickly and give fast feedback. -->
+
+## Question 2
+
+What is the main difference between a stub and a mock?
+
+A) Stubs are faster; mocks are slower
+B) A stub returns canned data; a mock verifies it was called with expectations
+C) Stubs are for unit tests; mocks are for integration tests
+D) There is no meaningful difference
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: A stub provides fake responses so the code under test can run—you don't verify how it was used. A mock lets you assert that it was called with specific arguments. Stubs fake; mocks verify. -->
+
+## Question 3
+
+Which of these is generally NOT recommended to test?
+
+A) Business logic that computes tax based on state and subtotal
+B) A thin wrapper that calls axios.get and returns response.data
+C) Edge cases (empty list, boundary values)
+D) Error paths (invalid input, network failure)
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Thin wrappers over third-party code add little value to test—you're mostly testing the library. Business logic, edge cases, and error paths are high-value targets. You might add one smoke test for the wrapper. -->
+
+## Question 4
+
+When might a team use a "diamond" or "trophy" test shape instead of the classic pyramid?
+
+A) When they want fewer unit tests
+B) When business logic lives in integration layers and they test what matters where it matters
+C) When e2e tests are faster than unit tests
+D) When they have no integration tests
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: The diamond/trophy inverts the pyramid: more integration tests than unit tests. Teams use it when critical logic lives in components working together (DB, API, services). The principle: test what matters, where it matters. -->
+
+## Question 5
+
+Why might you run e2e tests only on merge to main, not on every PR?
+
+A) E2E tests are less important than unit tests
+B) E2E tests are slow and expensive; unit + integration on every PR gives fast feedback; e2e catches integration issues less frequently
+C) E2E tests require manual approval
+D) E2E tests cannot run in CI
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: E2E tests are valuable but slow. Running them on every PR increases feedback time. Many teams run unit + integration on every commit/PR for fast feedback, and run e2e on merge to main or nightly to balance speed and confidence. -->
+
+## Question 6
+
+Which assertion is most likely testing implementation details rather than behavior?
+
+A) Assert that the user's name appears on the screen after login
+B) Assert that the API was called with the correct parameters
+C) Assert that useEffect was called exactly twice
+D) Assert that the response status is 200
+
+<!-- ANSWER: C -->
+<!-- EXPLANATION: useEffect count is an implementation detail—if you refactor to a different hook or pattern, the test breaks even though user-visible behavior is unchanged. Asserting rendered output, API calls, or response status tests behavior. -->
+
+## Question 7
+
+<!-- VISUAL: drag-order -->
+
+Put these test pyramid layers in order from base (most tests) to top (fewest tests):
+
+A) Integration tests
+B) Unit tests
+C) End-to-end tests
+
+<!-- ANSWER: B,A,C -->
+<!-- EXPLANATION: The pyramid has many unit tests at the base (B), fewer integration tests in the middle (A), and few e2e tests at the top (C). -->
+
+## Question 8
+
+<!-- VISUAL: matching -->
+
+Match each test type to its primary purpose:
+
+A) Unit test → 1) Verify the full system works together (UI + backend + DB)
+B) Integration test → 2) Verify a single function or class in isolation
+C) E2E test → 3) Verify components work together (API + DB, or module + service)
+
+<!-- ANSWER: A2,B3,C1 -->
+<!-- EXPLANATION: Unit tests isolate small units (2). Integration tests verify component interaction (3). E2E tests exercise the full stack (1). -->

package/modules/test-strategy/resources.md

@@ -0,0 +1,60 @@
+# Test Strategy — Resources
+
+## Core Reading
+
+- [The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html) — Martin Fowler. The definitive article: pyramid, trade-offs, and practical guidance.
+- [Test Pyramid](https://martinfowler.com/bliki/TestPyramid.html) — Martin Fowler. Original bliki entry.
+- [The Testing Trophy and Testing Classifications](https://kentcdodds.com/blog/the-testing-trophy-and-testing-classifications) — Kent C. Dodds. Diamond/trophy alternative to the pyramid.
+
+## Books
+
+- **Test Driven Development: By Example** by Kent Beck — TDD fundamentals: red-green-refactor, writing tests first.
+- **Growing Object-Oriented Software, Guided by Tests** by Steve Freeman & Nat Pryce — Test-first design and mocking strategies.
+
+## Testing Frameworks
+
+- [Jest](https://jestjs.io/) — JavaScript unit testing. Fast, snapshot support, built-in mocks.
+- [Vitest](https://vitest.dev/) — Vite-native test runner. Jest-compatible API, ESM, fast.
+- [Playwright](https://playwright.dev/) — Cross-browser e2e testing. Reliable, modern API.
+- [Cypress](https://www.cypress.io/) — E2E testing for the web. Great DX, time-travel debugging.
+
+## Articles
+
+- [What to Test](https://kentcdodds.com/blog/what-to-test) — Kent C. Dodds. Focus on implementation details vs behavior.
+- [Unit Testing Best Practices](https://docs.microsoft.com/en-us/dotnet/core/testing/unit-testing-best-practices) — Microsoft. Naming, structure, what to mock.
+- [Test Double Patterns](https://martinfowler.com/bliki/TestDouble.html) — Martin Fowler. Stub, mock, spy, fake, dummy.
+
+## Videos
+
+- [The Test Pyramid](https://www.youtube.com/watch?v=o0dS02sE_2c) — Martin Fowler (conference talk). Rationale and real-world use.
+- [Rethinking the Test Pyramid](https://www.youtube.com/watch?v=z2q5_y-4qy0) — Google Testing Blog. Alternative shapes and when they fit.
+- [Jest Tutorial](https://www.youtube.com/watch?v=FgnxcUQ5xho) — Academind. Getting started with Jest.
+
+## Tools
+
+- [Testing Library](https://testing-library.com/) — Test components from the user's perspective. React, Vue, DOM.
+- [MSW (Mock Service Worker)](https://mswjs.io/) — Mock API at the network level. No changes to app code.
+- [Sinon](https://sinonjs.org/) — Standalone mocks, stubs, spies for JavaScript.
+
+## CI/CD
+
+- [GitHub Actions — Test workflow](https://docs.github.com/en/actions/automating-builds-and-tests) — Run tests on push/PR.
+- [Vitest — CI Configuration](https://vitest.dev/guide/ci.html) — Configuring Vitest for CI.
+- [Playwright — CI](https://playwright.dev/docs/ci) — Running Playwright in GitHub Actions, etc.
+
+## Podcasts
+
+- [Test & Code](https://testandcode.com/) — Brian Okken. Episodes on testing strategies, TDD, and pytest patterns.
+- [Software Engineering Daily — Testing](https://softwareengineeringdaily.com/?s=testing) — Deep dives on testing at scale, flaky tests, and CI pipelines.
+- [JS Party — Testing Episodes](https://changelog.com/jsparty) — Panel discussions on JavaScript testing tools and strategies.
+
+## Interactive and Visual
+
+- [Testing Playground](https://testing-playground.com/) — Find the right Testing Library query for any DOM element visually.
+- [Playwright Trace Viewer](https://playwright.dev/docs/trace-viewer-intro) — Replay test execution with screenshots, DOM snapshots, and network at each step.
+- [Vitest UI](https://vitest.dev/guide/ui.html) — Visual test runner dashboard for browsing and debugging test results.
+
+## Courses
+
+- [Testing JavaScript (Kent C. Dodds)](https://testingjavascript.com/) — Comprehensive course: static analysis through E2E, with real-world projects.
+- [freeCodeCamp — Quality Assurance](https://www.freecodecamp.org/learn/quality-assurance/) — Free certification covering unit testing, functional testing, and Chai assertions.