Phase 3 / Ep 16: External Interface Mocking: The Minimalist Way

Moving on to our next task_plan.md phase: establishing the API handling class (API Adapter layer) we need to send to Google.

According to the previously established "No code without tests" iron rule, if we want to write this class, we must first write its google_sync.spec.ts. Here we will encounter a fatal problem in project development:

During the few minutes of automated TDD execution, the Agent might, due to attempting to debug, automatically run the entire test file 30 times within a minute. If the test code actually contained the original fetch('https://www.googleapis.com/'), your hard-earned Google API Key would be blocked midway by Google due to rate-limiting firewall rules, being mistaken for a malicious crawler.

1. Instructing the Agent to Master Espionage Replacement (Mocking)

We must further tighten our process description. When you face testing, you need to instill this idea, supplementing a technical detail principle in GEMINI.md or the previous two test-driven-development issues:

"[Test Black Box Principle] Any I/O test involving external HTTP requests and external databases must never initiate real network actions. It must prioritize using vi.mock / nock or similar function hijacking methods to fake external sandbox responses."

2. Simulating a Google API Call

When we ask the Agent to implement and successfully test the Google Calendar event extraction function, the test it generates this time (under your strict rules) will take this form:

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

// Fatal step: The Agent listened to you, it automatically hijacked the entire base request layer!
global.fetch = vi.fn(); 

describe('Google Calendar Sync Adapter', () => {
   it('should fetch and map event to local formats', async () => {
       // The Agent faked data that Google would return if it responded normally (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 code correctly placed '123' into the system's structural object.
       expect(res).toHaveLength(1);
       expect(res[0].eventId).toBe('123');
   });
});

3. Phase 3 Conclusion

By now, you should have felt the immense power of TDD and external Mocking. You have completely cut off and shielded all "external interferences". As long as this google_adapter can successfully run green, the probability of problems when connecting in a production environment will approach 0 indefinitely (unless Google changes its interface dictionary definition).

Phase 3 Progress Summary: We now not only have an architect who can autonomously generate requirements, but also a paranoid programmer whose code will never be left unfinished (Test-Driven, knows to alert after 3 failures, writes assertion stubs to isolate external communication).

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