1# Mocking Strategy: Real vs Mock Services
2 
3## Table of Contents
4 
51. [Core Principle](#core-principle)
62. [Decision Matrix](#decision-matrix)
73. [Decision Flowchart](#decision-flowchart)
84. [Mocking Techniques](#mocking-techniques)
95. [Real Service Strategies](#real-service-strategies)
106. [Hybrid Approach: Fixture-Based Mock Control](#hybrid-approach-fixture-based-mock-control)
117. [Validating Mock Accuracy](#validating-mock-accuracy)
128. [Anti-Patterns](#anti-patterns)
13 
14> **When to use**: Deciding whether to mock API calls, intercept network requests, or hit real services in Playwright tests.
15 
16## Core Principle
17 
18**Mock at the boundary, test your stack end-to-end.** Mock third-party services you don't own (payment gateways, email providers, OAuth). Never mock your own frontend-to-backend communication. Tests should prove YOUR code works, not that third-party APIs are available.
19 
20## Decision Matrix
21 
22| Scenario | Mock? | Strategy |
23| --- | --- | --- |
24| Your own REST/GraphQL API | Never | Hit real API against staging or local dev |
25| Your database (through your API) | Never | Seed via API or fixtures |
26| Authentication (your auth system) | Mostly no | Use `storageState` to skip login in most tests |
27| Stripe / payment gateway | Always | `route.fulfill()` with expected responses |
28| SendGrid / email service | Always | Mock the API call, verify request payload |
29| OAuth providers (Google, GitHub) | Always | Mock token exchange, test your callback handler |
30| Analytics (Segment, Mixpanel) | Always | `route.abort()` or `route.fulfill()` |
31| Maps / geocoding APIs | Always | Mock with static responses |
32| Feature flags (LaunchDarkly) | Usually | Mock to force specific flag states |
33| CDN / static assets | Never | Let them load normally |
34| Flaky external dependency | CI: mock, local: real | Conditional mocking based on environment |
35| Slow external dependency | Dev: mock, nightly: real | Separate test projects in config |
36 
37## Decision Flowchart
38 
39```text
40Is this service part of YOUR codebase?
41├── YES → Do NOT mock. Test the real integration.
42│   ├── Is it slow? → Optimize the service, not the test.
43│   └── Is it flaky? → Fix the service. Flaky infra is a bug.
44└── NO → It's a third-party service.
45    ├── Is it paid per call? → ALWAYS mock.
46    ├── Is it rate-limited? → ALWAYS mock.
47    ├── Is it slow or unreliable? → ALWAYS mock.
48    └── Is it a complex multi-step flow? → Mock with HAR recording.
49```
50 
51## Mocking Techniques
52 
53### Blocking Unwanted Requests
54 
55Block third-party scripts that slow tests and add no coverage:
56 
57```typescript
58test.beforeEach(async ({ page }) => {
59  await page.route('**/{analytics,tracking,segment,hotjar}.{com,io}/**', (route) => {
60    route.abort();
61  });
62});
63 
64test('dashboard renders without tracking scripts', async ({ page }) => {
65  await page.goto('/dashboard');
66  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
67});
68```
69 
70### Full Mock (route.fulfill)
71 
72Completely replace a third-party API response:
73 
74```typescript
75test('order flow with mocked payment service', async ({ page }) => {
76  await page.route('**/api/charge', (route) => {
77    route.fulfill({
78      status: 200,
79      contentType: 'application/json',
80      body: JSON.stringify({
81        transactionId: 'txn_mock_abc',
82        status: 'completed',
83      }),
84    });
85  });
86 
87  await page.goto('/order/confirm');
88  await page.getByRole('button', { name: 'Complete Purchase' }).click();
89  await expect(page.getByText('Order confirmed')).toBeVisible();
90});
91 
92test('display error on payment decline', async ({ page }) => {
93  await page.route('**/api/charge', (route) => {
94    route.fulfill({
95      status: 402,
96      contentType: 'application/json',
97      body: JSON.stringify({
98        error: { code: 'insufficient_funds', message: 'Card declined.' },
99      }),
100    });
101  });
102 
103  await page.goto('/order/confirm');
104  await page.getByRole('button', { name: 'Complete Purchase' }).click();
105  await expect(page.getByRole('alert')).toContainText('Card declined');
106});
107```
108 
109### Partial Mock (Modify Responses)
110 
111Let the real API call happen but tweak the response:
112 
113```typescript
114test('display low inventory warning', async ({ page }) => {
115  await page.route('**/api/inventory/*', async (route) => {
116    const response = await route.fetch();
117    const data = await response.json();
118 
119    data.quantity = 1;
120    data.lowStock = true;
121 
122    await route.fulfill({
123      response,
124      body: JSON.stringify(data),
125    });
126  });
127 
128  await page.goto('/products/widget-pro');
129  await expect(page.getByText('Only 1 remaining')).toBeVisible();
130});
131 
132test('inject test notification into real response', async ({ page }) => {
133  await page.route('**/api/alerts', async (route) => {
134    const response = await route.fetch();
135    const data = await response.json();
136 
137    data.items.push({
138      id: 'test-alert',
139      text: 'Report generated',
140      category: 'info',
141    });
142 
143    await route.fulfill({
144      response,
145      body: JSON.stringify(data),
146    });
147  });
148 
149  await page.goto('/home');
150  await expect(page.getByText('Report generated')).toBeVisible();
151});
152```
153 
154### Record and Replay (HAR Files)
155 
156For complex API sequences (OAuth flows, multi-step wizards):
157 
158**Recording:**
159 
160```typescript
161test('capture API traffic for admin panel', async ({ page }) => {
162  await page.routeFromHAR('tests/fixtures/admin-panel.har', {
163    url: '**/api/**',
164    update: true,
165  });
166 
167  await page.goto('/admin');
168  await page.getByRole('tab', { name: 'Reports' }).click();
169  await page.getByRole('tab', { name: 'Settings' }).click();
170});
171```
172 
173**Replaying:**
174 
175```typescript
176test('admin panel loads with recorded data', async ({ page }) => {
177  await page.routeFromHAR('tests/fixtures/admin-panel.har', {
178    url: '**/api/**',
179    update: false,
180  });
181 
182  await page.goto('/admin');
183  await expect(page.getByRole('heading', { name: 'Reports' })).toBeVisible();
184});
185```
186 
187**HAR maintenance:**
188 
189- Record against a known-good staging environment
190- Commit `.har` files to version control
191- Re-record when APIs change
192- Scope HAR to specific URL patterns
193 
194## Real Service Strategies
195 
196### Local Dev Server
197 
198```typescript
199// playwright.config.ts
200export default defineConfig({
201  webServer: {
202    command: 'npm run dev',
203    url: 'http://localhost:3000',
204    reuseExistingServer: !process.env.CI,
205    timeout: 30_000,
206  },
207  use: {
208    baseURL: 'http://localhost:3000',
209  },
210});
211```
212 
213### Staging Environment
214 
215```typescript
216// playwright.config.ts
217export default defineConfig({
218  use: {
219    baseURL: process.env.CI
220      ? 'https://staging.example.com'
221      : 'http://localhost:3000',
222  },
223});
224```
225 
226### Test Containers
227 
228```typescript
229// playwright.config.ts
230export default defineConfig({
231  webServer: {
232    command: 'docker compose -f docker-compose.test.yml up --wait',
233    url: 'http://localhost:3000/health',
234    reuseExistingServer: !process.env.CI,
235    timeout: 120_000,
236  },
237  globalTeardown: './tests/global-teardown.ts',
238});
239```
240 
241```typescript
242// tests/global-teardown.ts
243import { execSync } from 'child_process';
244 
245export default function globalTeardown() {
246  if (process.env.CI) {
247    execSync('docker compose -f docker-compose.test.yml down -v');
248  }
249}
250```
251 
252## Hybrid Approach: Fixture-Based Mock Control
253 
254Create fixtures that let individual tests opt into mocking specific services:
255 
256```typescript
257// tests/fixtures/service-mocks.ts
258import { test as base } from '@playwright/test';
259 
260type MockConfig = {
261  mockPayments: boolean;
262  mockNotifications: boolean;
263  mockAnalytics: boolean;
264};
265 
266export const test = base.extend<MockConfig>({
267  mockPayments: [true, { option: true }],
268  mockNotifications: [true, { option: true }],
269  mockAnalytics: [true, { option: true }],
270 
271  page: async ({ page, mockPayments, mockNotifications, mockAnalytics }, use) => {
272    if (mockPayments) {
273      await page.route('**/api/billing/**', (route) => {
274        route.fulfill({
275          status: 200,
276          contentType: 'application/json',
277          body: JSON.stringify({ status: 'paid', id: 'inv_mock_789' }),
278        });
279      });
280    }
281 
282    if (mockNotifications) {
283      await page.route('**/api/notify', (route) => {
284        route.fulfill({
285          status: 200,
286          contentType: 'application/json',
287          body: JSON.stringify({ delivered: true }),
288        });
289      });
290    }
291 
292    if (mockAnalytics) {
293      await page.route('**/{segment,mixpanel,amplitude}.**/**', (route) => {
294        route.abort();
295      });
296    }
297 
298    await use(page);
299  },
300});
301 
302export { expect } from '@playwright/test';
303```
304 
305```typescript
306// tests/billing.spec.ts
307import { test, expect } from './fixtures/service-mocks';
308 
309test('subscription renewal sends notification', async ({ page }) => {
310  await page.goto('/account/billing');
311  await page.getByRole('button', { name: 'Renew Now' }).click();
312  await expect(page.getByText('Subscription renewed')).toBeVisible();
313});
314 
315test.describe('integration suite', () => {
316  test.use({ mockPayments: false });
317 
318  test('real billing flow against test gateway', async ({ page }) => {
319    await page.goto('/account/billing');
320    await page.getByRole('button', { name: 'Renew Now' }).click();
321    await expect(page.getByText('Subscription renewed')).toBeVisible();
322  });
323});
324```
325 
326### Environment-Based Test Projects
327 
328```typescript
329// playwright.config.ts
330export default defineConfig({
331  projects: [
332    {
333      name: 'ci-fast',
334      testMatch: '**/*.spec.ts',
335      use: { baseURL: 'http://localhost:3000' },
336    },
337    {
338      name: 'nightly-full',
339      testMatch: '**/*.integration.spec.ts',
340      use: { baseURL: 'https://staging.example.com' },
341      timeout: 120_000,
342    },
343  ],
344});
345```
346 
347## Validating Mock Accuracy
348 
349Guard against mock drift from real APIs:
350 
351```typescript
352test.describe('contract validation', () => {
353  test('billing mock matches real API shape', async ({ request }) => {
354    const realResponse = await request.post('/api/billing/charge', {
355      data: { amount: 5000, currency: 'usd' },
356    });
357    const realBody = await realResponse.json();
358 
359    const mockBody = {
360      status: 'paid',
361      id: 'inv_mock_789',
362    };
363 
364    expect(Object.keys(mockBody).sort()).toEqual(Object.keys(realBody).sort());
365 
366    for (const key of Object.keys(mockBody)) {
367      expect(typeof mockBody[key]).toBe(typeof realBody[key]);
368    }
369  });
370});
371```
372 
373## Anti-Patterns
374 
375| Don't Do This | Problem | Do This Instead |
376| --- | --- | --- |
377| Mock your own API | Tests pass, app breaks. Zero integration coverage. | Hit your real API. Mock only third-party services. |
378| Mock everything for speed | You test a fiction. Frontend and backend may be incompatible. | Mock only external boundaries. |
379| Never mock anything | Tests are slow, flaky, fail when third parties have outages. | Mock third-party services. |
380| Use outdated mocks | Mock returns different shape than real API. | Run contract validation tests. Re-record HAR files regularly. |
381| Mock with `page.evaluate()` to stub fetch | Fragile, doesn't survive navigation. | Use `page.route()` which intercepts at network layer. |
382| Copy-paste mocks across files | One API change requires updating many files. | Centralize mocks in fixtures. |
383| Block all network and whitelist | Extremely brittle. Every new endpoint requires update. | Allow all by default. Selectively mock third-party services. |
384