Phase 3 / Ep 16 | The Simple Way to Mock External APIs

Let's move on to the next step in our task_plan.md: creating the API handler class (the API Adapter layer) for sending requests to Google.

According to the ironclad rule we established earlier—"No code without tests"—before we can write this class, we must first write its google_sync.spec.ts. This is where we encounter a critical problem in project development:

During the few minutes it takes to run TDD automatically, the Agent might try to debug errors by re-running the entire test file 30 times in a minute. If the test code actually contained a raw fetch('https://www.googleapis.com/'), the Google API Key you worked so hard to obtain would be blocked by Google's rate-limiting firewall for being treated as a malicious crawler.

1. Teaching the Agent the Art of Substitution (Mocking)

We must further tighten our process description. When you approach testing, you need to instill this mindset by adding a technical principle to GEMINI.md or the test-driven-development prompt from the previous two episodes:

[Black Box Testing Principle] Any I/O test involving external HTTP requests or external databases must never initiate real network actions. You must prioritize using function interception methods like vi.mock / nock or similar tools to fake a sandboxed external response.

2. Simulating a Google API Call

When we ask the Agent to implement and test a function for fetching Google Calendar events, the test it generates this time (under the constraints of your rules) will look like this:

import { describe, it, expect, vi } from 'vitest';
import { fetchCalendarEvents } from '../src/google_adapter.ts';

// The crucial step: The Agent listened to you and automatically hijacked the entire underlying request layer!
global.fetch = vi.fn(); 

describe('Google Calendar Sync Adapter', () => {
   it('should fetch and map event to local formats', async () => {
       // The Agent fakes the data that Google would normally return (Mocking!)
       const mockGoogleResponse = {
           items: [{ id: '123', start: { dateTime: '2026-10-01' } }]
       };
       (fetch as any).mockResolvedValue({
           ok: true,
           json: async () => mockGoogleResponse
       });

       const res = await fetchCalendarEvents('fake_token');
       
       // It only tests whether our parsing logic correctly places '123' into our system's structured object.
       expect(res).toHaveLength(1);
       expect(res[0].eventId).toBe('123');
   });
});

3. Phase 3 Conclusion

By now, you should feel the immense power of TDD combined with external mocking. You have cut off and shielded all "external interference." As long as this google_adapter gets a green light, the probability of issues when connecting to the live environment in the future will approach zero (unless Google changes its API dictionary definitions).

Summary of Phase 3 Progress: We now not only have an architect capable of generating its own requirements, but also a paranoid programmer whose code will never be left unfinished (Test-Driven, knows to alert after 3 failures, and can write stubs to isolate external communications).

In the upcoming Phase 4, this roaring war machine will advance into the deep waters of the front lines. We will engage in a bloody battle with real external entities (authentication and authorization controlled by OAuth, and a real webhook message pool)