notelm-mcp 1.2.1

package/docs/07_e2e-testing-safety.qmd

@@ -0,0 +1,754 @@
+---
+title: "E2E 테스트: Google 자동화 감지 회피 전략"
+subtitle: "안전한 브라우저 자동화 테스트를 위한 종합 연구 가이드"
+author: "NotebookLM MCP Team"
+date: 2026-01-02
+format:
+  html:
+    toc: true
+    toc-depth: 3
+    number-sections: true
+    highlight-style: github
+    code-fold: false
+---
+
+## 요약
+
+Google의 자동화 감지 시스템은 매우 정교하며, 무분별한 자동화 테스트는 계정 정지나 차단으로 이어질 수 있습니다. 본 문서는 안전한 E2E 테스트를 위한 전략을 4단계로 분류하여 제시합니다.
+
+> [!CAUTION]
+> **계정 보호가 최우선입니다.** 실제 Google 계정으로 자동화 로그인을 시도하면 계정이 정지될 수 있습니다.
+
+### 권장 전략 우선순위
+
+| 순위 | 전략 | 계정 위험도 | 구현 복잡도 | 테스트 신뢰도 |
+|:---:|:---|:---:|:---:|:---:|
+| 1 | 완전 모킹 (LoFi Mock) | ⭐ 0% | 중간 | 높음 |
+| 2 | 사전인증 세션 재사용 | ⭐ 5% | 낮음 | 매우 높음 |
+| 3 | Patchright 스텔스 | ⚠️ 20% | 낮음 | 높음 |
+| 4 | 실제 인증 자동화 | 🔴 높음 | 낮음 | 매우 높음 |
+
+---
+
+## Google 자동화 감지 메커니즘
+
+Google은 브라우저 자동화를 감지하기 위해 다중 계층 방어 시스템을 사용합니다.
+
+### 1단계: 브라우저 핑거프린트 분석
+
+```javascript
+// Google이 감지하는 주요 자동화 신호
+const detectionSignals = {
+  // 1. WebDriver 플래그
+  navigatorWebdriver: navigator.webdriver,  // true면 자동화
+  
+  // 2. User-Agent 문자열
+  headlessChrome: navigator.userAgent.includes('HeadlessChrome'),
+  
+  // 3. Chrome DevTools Protocol (CDP) 사용
+  runtimeEnabled: typeof Runtime !== 'undefined',  // CDP 활성화
+  
+  // 4. 자동화 관련 플래그
+  automationControlled: window.navigator.plugins.length === 0,
+  
+  // 5. Chrome 객체 부재
+  chromeAppMissing: !window.chrome?.app,
+  chromeCsiMissing: !window.chrome?.csi,
+};
+```
+
+### 2단계: 행동 패턴 분석
+
+| 감지 항목 | 정상 사용자 | 자동화 봇 |
+|:---|:---|:---|
+| 마우스 이동 | 곡선, 불규칙 | 직선, 순간이동 |
+| 타이핑 속도 | 50-150 WPM, 오타 포함 | 매우 빠름, 일정 |
+| 페이지 탐색 | 스크롤, 읽기 시간 | 즉시 대상 요소 접근 |
+| 클릭 간격 | 불규칙 (0.5-3초) | 일정한 고정 값 |
+| IP 패턴 | 일관된 지역 | 빈번한 변경 |
+
+### 3단계: reCAPTCHA v3 스코어링
+
+```mermaid
+flowchart LR
+    A[사용자 접속] --> B{reCAPTCHA v3<br/>행동 분석}
+    B -->|Score 0.9| C[정상 사용자]
+    B -->|Score 0.5| D[경고 모니터링]
+    B -->|Score 0.1| E[봇 의심]
+    E --> F[챌린지 또는 차단]
+```
+
+### Google 계정 정지 조건
+
+> [!WARNING]
+> 다음 행동이 감지되면 계정 정지가 발생할 수 있습니다:
+
+1. **비정상적 로그인 패턴**: 동일 계정으로 짧은 시간 내 다수 로그인 시도
+2. **자동화된 로그인**: `navigator.webdriver` 감지
+3. **비정상적 API 요청**: 과도한 요청 빈도
+4. **의심스러운 위치**: 갑작스러운 지역 변경
+5. **서비스 약관 위반**: 자동화 접근 금지 서비스 이용
+
+---
+
+## 전략 1: 완전 모킹 (권장)
+
+> [!TIP]
+> **가장 안전한 접근법**: Google 서버에 전혀 접속하지 않고 테스트
+
+### 개념
+
+```mermaid
+sequenceDiagram
+    participant Test as E2E Test
+    participant App as NotebookLM App
+    participant MSW as MSW Mock
+    participant Real as Google 서버
+    
+    Test->>App: 페이지 로드
+    App->>MSW: OAuth 요청
+    MSW-->>App: 모킹된 응답
+    Note right of Real: 실제 서버 접속 없음
+    App-->>Test: 테스트 완료
+```
+
+### MSW (Mock Service Worker) 구현
+
+```typescript
+// tests/mocks/handlers.ts
+import { http, HttpResponse } from 'msw';
+
+export const googleOAuthHandlers = [
+  // OAuth 인증 엔드포인트 모킹
+  http.get('https://accounts.google.com/o/oauth2/v2/auth', () => {
+    const mockAuthCode = 'mock_auth_code_12345';
+    return HttpResponse.redirect(
+      `http://localhost:3000/callback?code=${mockAuthCode}`
+    );
+  }),
+
+  // 토큰 교환 엔드포인트 모킹
+  http.post('https://oauth2.googleapis.com/token', () => {
+    return HttpResponse.json({
+      access_token: 'mock_access_token',
+      refresh_token: 'mock_refresh_token',
+      expires_in: 3600,
+      token_type: 'Bearer',
+    });
+  }),
+
+  // 사용자 정보 엔드포인트 모킹
+  http.get('https://www.googleapis.com/oauth2/v3/userinfo', () => {
+    return HttpResponse.json({
+      sub: '123456789',
+      name: 'Test User',
+      email: 'test@example.com',
+      picture: 'https://example.com/avatar.jpg'
+    });
+  }),
+];
+```
+
+### NotebookLM API 응답 모킹
+
+```typescript
+// tests/mocks/notebooklm-handlers.ts
+import { http, HttpResponse } from 'msw';
+
+export const notebookLMHandlers = [
+  // 채팅 응답 모킹
+  http.post('https://notebooklm.google.com/api/chat', async ({ request }) => {
+    const body = await request.json();
+    
+    return HttpResponse.json({
+      response: `Mocked response for: ${body.question}`,
+      sources: [
+        { title: 'Mock Source 1', snippet: 'Relevant content...' }
+      ],
+      thinking_time: 1500,
+    });
+  }),
+
+  // 노트북 목록 모킹
+  http.get('https://notebooklm.google.com/api/notebooks', () => {
+    return HttpResponse.json({
+      notebooks: [
+        { id: 'mock-001', title: 'Test Notebook 1' },
+        { id: 'mock-002', title: 'Test Notebook 2' },
+      ]
+    });
+  }),
+];
+```
+
+### Playwright MSW 통합 예제
+
+```typescript
+// tests/e2e/authenticated-flow.spec.ts
+import { test, expect } from '@playwright/test';
+import { setupMSW } from '../mocks/setup';
+
+test.describe('NotebookLM E2E Tests (Mocked)', () => {
+  test.beforeEach(async ({ page }) => {
+    // MSW 설정
+    await setupMSW(page, [
+      ...googleOAuthHandlers,
+      ...notebookLMHandlers,
+    ]);
+  });
+
+  test('should display notebooks after login', async ({ page }) => {
+    await page.goto('/');
+    
+    // 로그인 버튼 클릭 (모킹된 OAuth 흐름)
+    await page.click('[data-testid="login-button"]');
+    
+    // 노트북 목록 확인
+    await expect(page.getByText('Test Notebook 1')).toBeVisible();
+    await expect(page.getByText('Test Notebook 2')).toBeVisible();
+  });
+
+  test('should receive chat response', async ({ page }) => {
+    await page.goto('/notebook/mock-001');
+    
+    await page.fill('[data-testid="chat-input"]', 'What is AI?');
+    await page.click('[data-testid="send-button"]');
+    
+    // 모킹된 응답 확인
+    await expect(page.getByText('Mocked response for: What is AI?')).toBeVisible();
+  });
+});
+```
+
+### 장단점
+
+| ✅ 장점 | ❌ 단점 |
+|:---|:---|
+| 계정 위험 0% | 실제 서버 동작과 차이 가능 |
+| 빠른 테스트 실행 | 모킹 유지보수 필요 |
+| CI/CD 친화적 | API 변경 시 업데이트 필요 |
+| 네트워크 독립적 | 모킹 로직 구현 비용 |
+
+---
+
+## 전략 2: 사전인증 세션 재사용
+
+> [!IMPORTANT]
+> **1회 수동 로그인 후 세션을 저장**하여 반복 로그인을 회피합니다.
+
+### 인증 상태 저장 및 재사용
+
+```mermaid
+sequenceDiagram
+    participant Manual as 수동 로그인<br/>(1회)
+    participant Save as storageState<br/>저장
+    participant Test1 as Test 1
+    participant Test2 as Test 2
+    participant TestN as Test N
+    
+    Manual->>Save: 쿠키/세션 저장
+    Save-->>Test1: 상태 로드
+    Save-->>Test2: 상태 로드
+    Save-->>TestN: 상태 로드
+    Note over Test1,TestN: 로그인 없이<br/>인증된 상태로 시작
+```
+
+### 구현: 세션 저장
+
+```typescript
+// scripts/save-auth-state.ts
+import { chromium } from 'patchright';
+import path from 'path';
+
+async function saveAuthenticationState() {
+  const browser = await chromium.launch({ headless: false });
+  const context = await browser.newContext();
+  const page = await context.newPage();
+
+  // 1. NotebookLM 접속
+  await page.goto('https://notebooklm.google.com');
+
+  // 2. 사용자에게 수동 로그인 요청
+  console.log('🔐 Please login manually in the browser window...');
+  console.log('⏳ Waiting for you to complete authentication...');
+
+  // 3. 인증 완료 대기 (특정 URL 또는 요소 감지)
+  await page.waitForURL('https://notebooklm.google.com/*', {
+    timeout: 300000 // 5분 대기
+  });
+
+  // 4. 인증 상태 저장
+  const authStatePath = path.join(__dirname, '../.auth/user-state.json');
+  await context.storageState({ path: authStatePath });
+
+  console.log(`✅ Authentication state saved to: ${authStatePath}`);
+  console.log('⚠️  Add this file to .gitignore!');
+
+  await browser.close();
+}
+
+saveAuthenticationState();
+```
+
+### 구현: 세션 로드
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    // 인증이 필요한 테스트
+    {
+      name: 'authenticated',
+      use: {
+        storageState: '.auth/user-state.json',
+      },
+    },
+    // 비인증 테스트
+    {
+      name: 'unauthenticated',
+      use: {
+        storageState: undefined,
+      },
+    },
+  ],
+});
+```
+
+```typescript
+// tests/e2e/notebook-operations.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.use({ storageState: '.auth/user-state.json' });
+
+test.describe('NotebookLM Authenticated Tests', () => {
+  test('should access notebooks without login', async ({ page }) => {
+    // 이미 인증된 상태로 시작
+    await page.goto('https://notebooklm.google.com');
+
+    // 즉시 노트북 목록 접근 가능
+    await expect(page.locator('[data-testid="notebooks-list"]')).toBeVisible();
+  });
+});
+```
+
+### 세션 만료 처리
+
+```typescript
+// utils/auth-manager.ts
+import fs from 'fs/promises';
+
+export async function isSessionValid(statePath: string): Promise<boolean> {
+  try {
+    const stateData = await fs.readFile(statePath, 'utf-8');
+    const state = JSON.parse(stateData);
+
+    // 쿠키 만료 확인
+    const now = Date.now() / 1000;
+    const criticalCookies = ['__Secure-1PSID', '__Secure-3PSID', 'SID'];
+
+    for (const cookie of state.cookies) {
+      if (criticalCookies.includes(cookie.name)) {
+        if (cookie.expires && cookie.expires < now) {
+          console.warn(`Cookie ${cookie.name} has expired`);
+          return false;
+        }
+      }
+    }
+
+    return true;
+  } catch (error) {
+    console.error('Failed to validate session:', error);
+    return false;
+  }
+}
+```
+
+### 보안 주의사항
+
+> [!CAUTION]
+> 세션 파일은 민감한 정보를 포함합니다!
+
+```gitignore
+# .gitignore
+.auth/
+*.auth.json
+user-state.json
+```
+
+```yaml
+# CI/CD 환경 변수로 관리
+# GitHub Actions 예제
+env:
+  AUTH_STATE: ${{ secrets.NOTEBOOK_AUTH_STATE }}
+```
+
+---
+
+## 전략 3: Patchright 스텔스 모드
+
+### Patchright란?
+
+Patchright는 Playwright의 "언디텍티드" 버전으로, 브라우저 자동화 감지를 회피하도록 설계되었습니다.
+
+> [!NOTE]
+> 현재 프로젝트는 이미 Patchright 1.56.0을 사용하고 있습니다.
+
+### Patchright의 감지 회피 기법
+
+```mermaid
+graph TD
+    subgraph "Playwright (감지됨)"
+        A1[Runtime.enable 호출] --> B1[navigator.webdriver = true]
+        B1 --> C1[HeadlessChrome UA]
+        C1 --> D1[--enable-automation 플래그]
+    end
+
+    subgraph "Patchright (스텔스)"
+        A2[Isolated Context 실행] --> B2[navigator.webdriver = undefined]
+        B2 --> C2[Chrome UA]
+        C2 --> D2[자동화 플래그 제거]
+    end
+
+    style A1 fill:#ff6b6b
+    style B1 fill:#ff6b6b
+    style C1 fill:#ff6b6b
+    style D1 fill:#ff6b6b
+    style A2 fill:#51cf66
+    style B2 fill:#51cf66
+    style C2 fill:#51cf66
+    style D2 fill:#51cf66
+```
+
+### 주요 패치 내용
+
+| 감지 포인트 | Playwright | Patchright |
+|:---|:---|:---|
+| `navigator.webdriver` | `true` | `undefined` |
+| User-Agent | `HeadlessChrome` | `Chrome` |
+| `Runtime.enable` | 호출됨 | 격리된 컨텍스트 사용 |
+| `Console.enable` | 호출됨 | 패치됨 |
+| `--enable-automation` | 있음 | 제거됨 |
+| 팝업 차단 | 비활성화 | 기본값 유지 |
+
+### 현재 프로젝트의 스텔스 구현
+
+```typescript
+// src/utils/stealth-utils.ts (현재 구현)
+export async function humanType(
+  page: Page,
+  selector: string,
+  text: string,
+  options?: { wpm?: number; typos?: boolean }
+): Promise<void> {
+  if (!CONFIG.stealthEnabled || !CONFIG.stealthHumanTyping) {
+    await page.fill(selector, text);
+    return;
+  }
+
+  // 인간적인 타이핑 시뮬레이션
+  const wpm = options?.wpm ?? randomInt(CONFIG.typingMinWPM, CONFIG.typingMaxWPM);
+  const baseDelay = (60 * 1000) / (wpm * 5);
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+
+    // 오타 시뮬레이션 (5% 확률)
+    if (options?.typos && Math.random() < 0.05 && i > 0) {
+      const typoChar = randomChar();
+      await page.fill(selector, currentText + typoChar);
+      await randomDelay(100, 200);
+      // 백스페이스
+      currentText = currentText.slice(0, -1);
+      await page.fill(selector, currentText);
+    }
+
+    currentText += char;
+    await page.fill(selector, currentText);
+
+    // 문자별 지연
+    let delay = baseDelay * randomFloat(0.8, 1.2);
+    if (char === ' ' || char === '.' || char === '!') {
+      delay *= 1.5; // 문장부호 후 더 긴 지연
+    }
+    await sleep(delay);
+  }
+}
+```
+
+```typescript
+// src/utils/stealth-utils.ts
+export async function randomMouseMovement(
+  page: Page,
+  endX?: number,
+  endY?: number,
+  steps?: number
+): Promise<void> {
+  if (!CONFIG.stealthEnabled || !CONFIG.stealthMouseMovements) {
+    return;
+  }
+
+  // 베지어 커브 기반 마우스 이동
+  for (let step = 0; step < steps; step++) {
+    const progress = step / steps;
+
+    // 자연스러운 곡선 이동
+    const jitterX = Math.sin(progress * Math.PI) * randomInt(-10, 10);
+    const jitterY = Math.cos(progress * Math.PI) * randomInt(-10, 10);
+
+    const currentX = startX + (endX - startX) * progress + jitterX;
+    const currentY = startY + (endY - startY) * progress + jitterY;
+
+    await page.mouse.move(currentX, currentY);
+
+    // 이동 속도 변화 (가속→감속)
+    const delay = 10 + 30 * Math.sin(2.5 * progress);
+    await sleep(delay);
+  }
+}
+```
+
+### 고급 스텔스 설정
+
+```typescript
+// patchright-config.ts
+import { chromium } from 'patchright';
+
+export async function launchStealthBrowser() {
+  const browser = await chromium.launch({
+    headless: false, // 헤드리스 감지 회피
+    channel: 'chrome', // 실제 Chrome 사용
+
+    args: [
+      '--disable-blink-features=AutomationControlled',
+      '--no-sandbox',
+      '--disable-setuid-sandbox',
+      '--disable-dev-shm-usage',
+      '--disable-accelerated-2d-canvas',
+      '--no-first-run',
+      '--no-zygote',
+      '--disable-gpu',
+      '--hide-scrollbars',
+      '--mute-audio',
+    ],
+
+    ignoreDefaultArgs: ['--enable-automation'],
+  });
+
+  const context = await browser.newContext({
+    // 실제 사용자 User-Agent
+    userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ' +
+      'AppleWebKit/537.36 (KHTML, like Gecko) ' +
+      'Chrome/120.0.0.0 Safari/537.36',
+
+    // 실제 뷰포트 크기
+    viewport: { width: 1920, height: 1080 },
+
+    // 지역 설정
+    locale: 'ko-KR',
+    timezoneId: 'Asia/Seoul',
+
+    // 권한 설정
+    permissions: ['geolocation', 'notifications'],
+
+    // 지리적 위치
+    geolocation: { latitude: 37.5665, longitude: 126.9780 }, // 서울
+  });
+
+  return { browser, context };
+}
+```
+
+### 여전히 존재하는 위험
+
+> [!WARNING]
+> Patchright를 사용해도 **Google 로그인 자동화는 위험**합니다!
+
+- Google은 지속적으로 감지 로직을 업데이트
+- 오픈소스 스텔스 도구는 뒤처질 수 있음
+- 계정 정지는 복구가 어려움
+
+---
+
+## 전략 4: Google API 대안 탐색
+
+### NotebookLM Enterprise API
+
+Google은 기업 사용자를 위한 NotebookLM Enterprise API를 제공합니다.
+
+```http
+# NotebookLM Enterprise API Endpoints
+POST /v1/notebooks
+GET  /v1/notebooks/{notebookId}
+POST /v1/notebooks/{notebookId}/sources
+POST /v1/notebooks/{notebookId}/chat
+```
+
+> [!NOTE]
+> Enterprise API 접근은 Google Cloud 계정과 별도 계약이 필요합니다.
+
+### 오픈소스 대안: Open Notebook
+
+[Open Notebook](https://github.com/smol-ai/open-notebook)은 NotebookLM의 오픈소스 대안으로, 자체 호스팅이 가능합니다.
+
+```bash
+# Docker로 Open Notebook 실행
+docker run -d \
+  -p 3000:3000 \
+  -e LLM_PROVIDER=openai \
+  -e OPENAI_API_KEY=sk-xxx \
+  opennotebook/server:latest
+```
+
+### Vertex AI 대안
+
+Google Cloud Vertex AI를 사용하면 공식 API로 유사한 기능을 구현할 수 있습니다.
+
+```typescript
+// Vertex AI 문서 요약 예제
+import { VertexAI } from '@google-cloud/vertexai';
+
+const vertexAI = new VertexAI({
+  project: 'your-project',
+  location: 'us-central1',
+});
+
+const model = vertexAI.getGenerativeModel({
+  model: 'gemini-1.5-pro',
+});
+
+async function summarizeDocument(content: string) {
+  const result = await model.generateContent({
+    contents: [{ role: 'user', parts: [{ text: content }] }],
+    systemInstruction: 'You are a document summarization assistant.',
+  });
+
+  return result.response.candidates[0].content;
+}
+```
+
+---
+
+## 권장 테스트 아키텍처
+
+### 테스트 피라미드 적용
+
+```mermaid
+graph TB
+    subgraph "E2E Tests (실제 브라우저)"
+        E1[세션 재사용 테스트]
+        E2[Patchright 스텔스]
+    end
+
+    subgraph "Integration Tests (가장 권장)"
+        I1[MSW 모킹 테스트]
+        I2[API 통합 테스트]
+    end
+
+    subgraph "Unit Tests"
+        U1[유틸리티 테스트]
+        U2[컴포넌트 테스트]
+    end
+
+    E1 --> I1
+    E2 --> I1
+    I1 --> U1
+    I2 --> U2
+
+    style I1 fill:#40c057
+    style I2 fill:#40c057
+```
+
+### 실제 테스트 전략 구성
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    // 단위 테스트: 빠르고 안전
+    include: ['src/**/*.test.ts'],
+    exclude: ['tests/e2e/**'],
+
+    // 커버리지
+    coverage: {
+      reporter: ['text', 'json', 'html'],
+    },
+  },
+});
+```
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    // 1. 모킹 기반 테스트 (권장)
+    {
+      name: 'mocked',
+      testDir: './tests/mocked',
+      use: {
+        baseURL: 'http://localhost:3000',
+      },
+    },
+
+    // 2. 세션 재사용 테스트 (수동 로그인 필요)
+    {
+      name: 'authenticated',
+      testDir: './tests/authenticated',
+      use: {
+        storageState: '.auth/user-state.json',
+        baseURL: 'https://notebooklm.google.com',
+      },
+    },
+  ],
+
+  // 병렬 실행 제한 (실제 서버 테스트)
+  workers: process.env.CI ? 1 : undefined,
+
+  // 재시도 설정
+  retries: process.env.CI ? 2 : 0,
+});
+```
+
+---
+
+## 결론 및 권장사항
+
+### 최종 권장 전략
+
+1. **개발 단계**: MSW 모킹 사용 (100% 안전)
+2. **로컬 검증**: 세션 재사용 + Patchright 스텔스
+3. **CI/CD**: 모킹 테스트만 실행
+4. **프로덕션 검증**: 수동 테스트 또는 Enterprise API
+
+### 체크리스트
+
+- [ ] MSW 핸들러 구현
+- [ ] Playwright storageState 설정
+- [ ] .gitignore에 인증 파일 추가
+- [ ] CI/CD 파이프라인에 모킹 테스트 통합
+- [ ] 세션 만료 처리 로직 구현
+- [ ] 테스트 전용 Google 계정 생성 (선택)
+
+### 절대 하지 말아야 할 것
+
+> [!CAUTION]
+> 
+> 1. ❌ 실제 Google 계정으로 자동화 로그인 반복 시도
+> 2. ❌ 인증 파일을 버전 관리에 포함
+> 3. ❌ CI/CD에서 실제 Google 로그인 실행
+> 4. ❌ 프록시 우회로 다중 세션 생성 시도
+
+---
+
+## 참고 자료
+
+- [Patchright GitHub](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright-nodejs)
+- [MSW Documentation](https://mswjs.io/)
+- [Playwright Authentication](https://playwright.dev/docs/auth)
+- [Google Cloud Vertex AI](https://cloud.google.com/vertex-ai)
+- [Open Notebook (오픈소스 대안)](https://github.com/smol-ai/open-notebook)