Initial Version of sitemap.xml spec

tests/integration/drive-integration.test.js.old

@@ -0,0 +1,395 @@
+/**
+ * Integration Tests: Google Drive API Integration
+ * 
+ * Tests OAuth 2.0 and Drive API integration
+ * Tests T011, T027, T057
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { google } from 'googleapis';
+
+describe('Integration: OAuth2 Client Initialization (T011)', () => {
+  
+  let oauth2Client;
+  
+  before(() => {
+    // Mock global.config for testing
+    global.config = {
+      google: {
+        clientId: 'test-client-id.apps.googleusercontent.com',
+        clientSecret: 'test-client-secret',
+        redirectUri: 'http://localhost:3000/oauth/callback',
+        scopes: [
+          'https://www.googleapis.com/auth/drive.readonly',
+          'https://www.googleapis.com/auth/drive.metadata.readonly'
+        ]
+      }
+    };
+  });
+
+  it('T011: should initialize OAuth2 client from global.config', () => {
+    // Given: global.config contains OAuth credentials
+    const { clientId, clientSecret, redirectUri } = global.config.google;
+    
+    // When: Creating OAuth2 client
+    oauth2Client = new google.auth.OAuth2(
+      clientId,
+      clientSecret,
+      redirectUri
+    );
+    
+    // Then: Client should be initialized
+    assert.ok(oauth2Client, 'OAuth2 client should be initialized');
+    assert.equal(oauth2Client._clientId, clientId, 'Client ID should match config');
+    assert.equal(oauth2Client._clientSecret, clientSecret, 'Client secret should match config');
+  });
+
+  it('T011: should set credentials with access and refresh tokens', () => {
+    // Given: OAuth2 client is initialized
+    const credentials = {
+      access_token: 'ya29.test_access_token',
+      refresh_token: '1//test_refresh_token',
+      token_type: 'Bearer',
+      expiry_date: Date.now() + 3600000 // 1 hour from now
+    };
+    
+    // When: Setting credentials
+    oauth2Client.setCredentials(credentials);
+    
+    // Then: Credentials should be set
+    const creds = oauth2Client.credentials;
+    assert.equal(creds.access_token, credentials.access_token, 'Access token should be set');
+    assert.equal(creds.refresh_token, credentials.refresh_token, 'Refresh token should be set');
+  });
+
+  it('T011: should listen for token refresh events', (t, done) => {
+    // Given: OAuth2 client with credentials
+    let tokenRefreshed = false;
+    
+    // When: Listening for tokens event
+    oauth2Client.on('tokens', (tokens) => {
+      tokenRefreshed = true;
+      assert.ok(tokens, 'Tokens should be emitted on refresh');
+      done();
+    });
+    
+    // Then: Event listener should be registered
+    assert.ok(oauth2Client.listenerCount('tokens') > 0, 'Should have tokens event listener');
+    
+    // Manually emit to test listener (in real scenario, googleapis emits this)
+    oauth2Client.emit('tokens', { access_token: 'new_token' });
+  });
+});
+
+describe('Integration: Drive API files.get() (T011)', () => {
+  
+  let drive;
+  
+  before(() => {
+    // Initialize Drive API client (will use mocked auth in tests)
+    const auth = new google.auth.OAuth2(
+      global.config.google.clientId,
+      global.config.google.clientSecret,
+      global.config.google.redirectUri
+    );
+    
+    auth.setCredentials({
+      access_token: 'test_token',
+      refresh_token: 'test_refresh'
+    });
+    
+    drive = google.drive({ version: 'v3', auth });
+  });
+
+  it('T011: should call files.get() with exportLinks field parameter', async () => {
+    // Given: A document ID
+    const fileId = '1BxAA_testDocumentId';
+    
+    // When: Calling files.get() with fields parameter
+    // Note: This will fail in tests without real Drive API access (expected in TDD red phase)
+    try {
+      const response = await drive.files.get({
+        fileId,
+        fields: 'id,name,mimeType,modifiedTime,size,exportLinks,webViewLink'
+      });
+      
+      // Then: Response should contain expected fields
+      assert.ok(response.data, 'Response should contain data');
+      assert.ok(response.data.id, 'Response should contain id field');
+      assert.ok(response.data.name, 'Response should contain name field');
+      
+    } catch (error) {
+      // Expected to fail without real credentials - this is TDD red phase
+      assert.ok(
+        error.message.includes('invalid') || error.message.includes('auth') || error.message.includes('credentials'),
+        'Should fail with auth-related error in test environment'
+      );
+    }
+  });
+
+  it('T011: should handle token expiry and refresh', async () => {
+    // Given: OAuth2 client with expired token
+    const auth = new google.auth.OAuth2(
+      global.config.google.clientId,
+      global.config.google.clientSecret,
+      global.config.google.redirectUri
+    );
+    
+    // Set expired token
+    auth.setCredentials({
+      access_token: 'expired_token',
+      refresh_token: 'valid_refresh_token',
+      expiry_date: Date.now() - 1000 // Expired 1 second ago
+    });
+    
+    // When: Making API call with expired token
+    // Then: googleapis should automatically refresh (or fail trying)
+    const drive = google.drive({ version: 'v3', auth });
+    
+    try {
+      await drive.files.get({ fileId: 'test', fields: 'id' });
+    } catch (error) {
+      // Expected to fail in test environment - validates refresh attempt
+      assert.ok(error, 'Should attempt token refresh and fail without real refresh token');
+    }
+  });
+});
+
+describe('Integration: Drive API files.list() with Pagination (T027)', () => {
+  
+  let drive;
+  
+  before(() => {
+    const auth = new google.auth.OAuth2(
+      global.config.google.clientId,
+      global.config.google.clientSecret,
+      global.config.google.redirectUri
+    );
+    
+    auth.setCredentials({
+      access_token: 'test_token',
+      refresh_token: 'test_refresh'
+    });
+    
+    drive = google.drive({ version: 'v3', auth });
+  });
+
+  it('T027: should retrieve paginated list of documents', async () => {
+    // Given: Drive API client
+    let allFiles = [];
+    let pageToken = null;
+    
+    // When: Retrieving files with pagination
+    try {
+      do {
+        const response = await drive.files.list({
+          pageSize: 100,
+          pageToken,
+          fields: 'nextPageToken,files(id,name,mimeType,modifiedTime)',
+          q: "mimeType='application/vnd.google-apps.document'"
+        });
+        
+        // Then: Response should contain files array
+        assert.ok(Array.isArray(response.data.files), 'Response should contain files array');
+        allFiles = allFiles.concat(response.data.files);
+        
+        // Update pageToken for next iteration
+        pageToken = response.data.nextPageToken;
+        
+      } while (pageToken);
+      
+      // Then: Should have retrieved all files
+      assert.ok(allFiles.length >= 0, 'Should retrieve files (may be 0 in test)');
+      
+    } catch (error) {
+      // Expected to fail without real credentials
+      assert.ok(
+        error.message.includes('invalid') || error.message.includes('auth'),
+        'Should fail with auth error in test environment'
+      );
+    }
+  });
+
+  it('T027: should handle large result sets (>1000 documents)', async () => {
+    // Given: Query that might return many documents
+    let pageCount = 0;
+    let pageToken = null;
+    const maxPages = 15; // Test pagination up to 1500 docs (100 per page)
+    
+    // When: Paginating through results
+    try {
+      do {
+        const response = await drive.files.list({
+          pageSize: 100,
+          pageToken,
+          fields: 'nextPageToken,files(id,name)',
+          q: "trashed=false"
+        });
+        
+        pageCount++;
+        pageToken = response.data.nextPageToken;
+        
+        // Then: Should handle pagination correctly
+        assert.ok(pageCount <= maxPages, 'Should not infinite loop');
+        
+        if (!pageToken) break; // No more pages
+        
+      } while (pageCount < maxPages);
+      
+      assert.ok(pageCount > 0, 'Should process at least one page');
+      
+    } catch (error) {
+      // Expected to fail without real credentials
+      assert.ok(error, 'Should handle auth error gracefully');
+    }
+  });
+});
+
+describe('Integration: Large Document Streaming (T057)', () => {
+  
+  it('T057: should stream 5MB document without excessive memory usage', async () => {
+    // Given: A large document (5MB)
+    const initialMemory = process.memoryUsage().heapUsed;
+    
+    // When: Streaming large document
+    // (This would be a real streaming operation in implementation)
+    const mockStreamSize = 5 * 1024 * 1024; // 5MB
+    const chunks = [];
+    const chunkSize = 64 * 1024; // 64KB chunks
+    
+    // Simulate streaming by processing chunks
+    for (let i = 0; i < mockStreamSize; i += chunkSize) {
+      const chunk = Buffer.alloc(Math.min(chunkSize, mockStreamSize - i));
+      chunks.push(chunk);
+    }
+    
+    // Then: Memory increase should be reasonable (<100MB)
+    const finalMemory = process.memoryUsage().heapUsed;
+    const memoryIncrease = (finalMemory - initialMemory) / (1024 * 1024); // MB
+    
+    assert.ok(
+      memoryIncrease < 100,
+      `Memory increase should be <100MB for 5MB document, was ${memoryIncrease.toFixed(2)}MB`
+    );
+  });
+
+  it('T057: should handle streaming with backpressure', async () => {
+    // Given: A mock readable stream
+    const { Readable } = await import('node:stream');
+    
+    let chunksRead = 0;
+    const totalChunks = 100;
+    
+    const mockStream = new Readable({
+      read() {
+        if (chunksRead < totalChunks) {
+          this.push(Buffer.alloc(1024)); // 1KB chunk
+          chunksRead++;
+        } else {
+          this.push(null); // EOF
+        }
+      }
+    });
+    
+    // When: Consuming stream with backpressure handling
+    const chunks = [];
+    for await (const chunk of mockStream) {
+      chunks.push(chunk);
+    }
+    
+    // Then: All chunks should be received
+    assert.equal(chunks.length, totalChunks, 'Should receive all chunks');
+    assert.equal(chunksRead, totalChunks, 'Should read all chunks');
+  });
+});
+
+describe('Integration: Drive API Error Mapping', () => {
+  
+  it('should map Drive API 404 error to HTTP 404', () => {
+    // Given: Drive API 404 error
+    const driveError = {
+      code: 404,
+      message: 'File not found'
+    };
+    
+    // When: Mapping to HTTP status
+    const httpStatus = driveError.code;
+    
+    // Then: Should map to 404
+    assert.equal(httpStatus, 404, 'Drive 404 should map to HTTP 404');
+  });
+
+  it('should map Drive API 403 error to HTTP 403', () => {
+    // Given: Drive API 403 error
+    const driveError = {
+      code: 403,
+      message: 'The user does not have permission'
+    };
+    
+    // When: Mapping to HTTP status
+    const httpStatus = driveError.code;
+    
+    // Then: Should map to 403
+    assert.equal(httpStatus, 403, 'Drive 403 should map to HTTP 403');
+  });
+
+  it('should map Drive API 401 error to HTTP 401', () => {
+    // Given: Drive API 401 error
+    const driveError = {
+      code: 401,
+      message: 'Invalid credentials'
+    };
+    
+    // When: Mapping to HTTP status
+    const httpStatus = driveError.code;
+    
+    // Then: Should map to 401
+    assert.equal(httpStatus, 401, 'Drive 401 should map to HTTP 401');
+  });
+
+  it('should map Drive API 429 error to HTTP 429 with Retry-After', () => {
+    // Given: Drive API rate limit error
+    const driveError = {
+      code: 429,
+      message: 'Rate limit exceeded',
+      errors: [{ reason: 'rateLimitExceeded' }]
+    };
+    
+    // When: Mapping to HTTP status and calculating retry delay
+    const httpStatus = driveError.code;
+    const retryAfter = 60; // Default 60 seconds
+    
+    // Then: Should map to 429 with Retry-After header
+    assert.equal(httpStatus, 429, 'Drive 429 should map to HTTP 429');
+    assert.equal(retryAfter, 60, 'Should include Retry-After of 60 seconds');
+  });
+
+  it('should map Drive API 500 error to HTTP 500', () => {
+    // Given: Drive API internal error
+    const driveError = {
+      code: 500,
+      message: 'Internal server error'
+    };
+    
+    // When: Mapping to HTTP status
+    const httpStatus = driveError.code;
+    
+    // Then: Should map to 500
+    assert.equal(httpStatus, 500, 'Drive 500 should map to HTTP 500');
+  });
+
+  it('should map Drive API 503 error to HTTP 503', () => {
+    // Given: Drive API service unavailable
+    const driveError = {
+      code: 503,
+      message: 'Service unavailable'
+    };
+    
+    // When: Mapping to HTTP status
+    const httpStatus = driveError.code;
+    
+    // Then: Should map to 503
+    assert.equal(httpStatus, 503, 'Drive 503 should map to HTTP 503');
+  });
+});

tests/integration/error-scenarios.test.js

@@ -0,0 +1,234 @@
+/**
+ * Integration Tests: Error Scenarios
+ * 
+ * Tests T025-T028: Error handling for /sitemap.xml endpoint
+ * Tests: >50k documents (413), rate limiting (429), service unavailable (503), invalid endpoints (404)
+ * 
+ * @module tests/integration/error-scenarios
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+
+const TEST_PORT = 3001;
+
+// =============================================================================
+// T025: Integration test for >50k documents (413 error)
+// =============================================================================
+
+describe('T025: /sitemap.xml with >50k Documents', () => {
+  it('should return 413 when Drive contains more than 50,000 documents', async () => {
+    // Mock Drive API to return count > 50,000
+    // TODO: Configure mock to simulate large document count
+    
+    const response = await makeRequest(`http://localhost:${TEST_PORT}/sitemap.xml`);
+
+    // Verify 413 Payload Too Large
+    assert.equal(response.statusCode, 413, 'Should return 413 when documents exceed 50k limit');
+    
+    // Verify no response body (per spec: status code only, no body)
+    assert.equal(response.body, '', 'Should have no response body for 413 error');
+    
+    // Verify no Content-Type header for error responses
+    assert.equal(response.headers['content-type'], undefined, 'Should not have Content-Type header for errors');
+  });
+});
+
+// =============================================================================
+// T026: Integration test for Drive API rate limiting (429 error)
+// =============================================================================
+
+describe('T026: /sitemap.xml with Drive API Rate Limiting', () => {
+  it('should return 429 with Retry-After header when Drive API rate limits', async () => {
+    // Mock Drive API to return 429 with Retry-After header
+    // TODO: Configure mock to simulate rate limit with Retry-After: 60
+    
+    const response = await makeRequest(`http://localhost:${TEST_PORT}/sitemap.xml`);
+
+    // Verify 429 Too Many Requests
+    assert.equal(response.statusCode, 429, 'Should return 429 when Drive API rate limits');
+    
+    // Verify Retry-After header is present (in seconds)
+    assert.ok(response.headers['retry-after'], 'Should include Retry-After header');
+    
+    const retryAfter = parseInt(response.headers['retry-after']);
+    assert.ok(retryAfter > 0, 'Retry-After should be a positive number (seconds)');
+    
+    // Verify no response body (per spec: status code only, no body)
+    assert.equal(response.body, '', 'Should have no response body for 429 error');
+  });
+
+  it('should pass through Retry-After value from Drive API', async () => {
+    // Mock Drive API to return specific Retry-After value
+    const expectedRetryAfter = 120; // 2 minutes
+    // TODO: Configure mock to return Retry-After: 120
+    
+    const response = await makeRequest(`http://localhost:${TEST_PORT}/sitemap.xml`);
+
+    assert.equal(response.statusCode, 429, 'Should return 429');
+    assert.equal(
+      response.headers['retry-after'],
+      String(expectedRetryAfter),
+      'Should pass through exact Retry-After value from Drive API'
+    );
+  });
+});
+
+// =============================================================================
+// T027: Integration test for Drive API 503 error (no retry)
+// =============================================================================
+
+describe('T027: /sitemap.xml with Drive API 503 Error', () => {
+  it('should return 503 immediately without retry when Drive API is unavailable', async () => {
+    // Mock Drive API to return 503 Service Unavailable
+    // TODO: Configure mock to simulate Drive API 503 error
+    
+    const startTime = Date.now();
+    const response = await makeRequest(`http://localhost:${TEST_PORT}/sitemap.xml`);
+    const elapsed = Date.now() - startTime;
+
+    // Verify 503 Service Unavailable (passthrough)
+    assert.equal(response.statusCode, 503, 'Should return 503 when Drive API is unavailable');
+    
+    // Verify no response body (per spec: status code only, no body)
+    assert.equal(response.body, '', 'Should have no response body for 503 error');
+    
+    // Verify NO retry was attempted (response should be immediate, < 1 second)
+    assert.ok(elapsed < 1000, 'Should return immediately without retry (< 1 second)');
+  });
+
+  it('should NOT retry on Drive API 503 per specification', async () => {
+    // Mock Drive API to track number of calls
+    let driveApiCallCount = 0;
+    // TODO: Configure mock to count API calls and return 503
+    
+    const response = await makeRequest(`http://localhost:${TEST_PORT}/sitemap.xml`);
+
+    assert.equal(response.statusCode, 503, 'Should return 503');
+    // Verify only ONE call was made (no retry)
+    // assert.equal(driveApiCallCount, 1, 'Should call Drive API only once (no retry on 503)');
+  });
+});
+
+// =============================================================================
+// T028: Integration test for invalid endpoint requests (404 error)
+// =============================================================================
+
+describe('T028: Invalid Endpoint Requests', () => {
+  it('should return 404 for non-/sitemap.xml paths', async () => {
+    const invalidPaths = [
+      '/',
+      '/documents/abc123',
+      '/api/documents',
+      '/health',
+      '/status',
+      '/favicon.ico',
+      '/documents/abc123/export'
+    ];
+
+    for (const path of invalidPaths) {
+      const response = await makeRequest(`http://localhost:${TEST_PORT}${path}`);
+
+      // Verify 404 Not Found
+      assert.equal(
+        response.statusCode,
+        404,
+        `Should return 404 for invalid path: ${path}`
+      );
+      
+      // Verify no response body (per spec: status code only, no body)
+      assert.equal(
+        response.body,
+        '',
+        `Should have no response body for 404 error on path: ${path}`
+      );
+      
+      // Verify no Content-Type header
+      assert.equal(
+        response.headers['content-type'],
+        undefined,
+        `Should not have Content-Type header for 404 on path: ${path}`
+      );
+    }
+  });
+
+  it('should return 404 for POST/PUT/DELETE requests to /sitemap.xml', async () => {
+    // Only GET is allowed, all other methods should return 404
+    const methods = ['POST', 'PUT', 'DELETE', 'PATCH'];
+
+    for (const method of methods) {
+      const response = await makeRequestWithMethod(
+        `http://localhost:${TEST_PORT}/sitemap.xml`,
+        method
+      );
+
+      // Note: Spec says 404 for non-/sitemap.xml paths, but should also handle wrong methods
+      // Could be 404 or 405, depending on implementation - check spec
+      assert.ok(
+        response.statusCode === 404 || response.statusCode === 405,
+        `Should return 404 or 405 for ${method} method`
+      );
+      
+      assert.equal(response.body, '', 'Should have no response body for method errors');
+    }
+  });
+});
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Make HTTP GET request
+ * @param {string} url - Full URL to request
+ * @returns {Promise<Object>} Response object
+ */
+function makeRequest(url) {
+  return new Promise((resolve, reject) => {
+    http.get(url, (res) => {
+      let body = '';
+      res.on('data', chunk => body += chunk);
+      res.on('end', () => {
+        resolve({
+          statusCode: res.statusCode,
+          headers: res.headers,
+          body
+        });
+      });
+    }).on('error', reject);
+  });
+}
+
+/**
+ * Make HTTP request with specific method
+ * @param {string} url - Full URL to request
+ * @param {string} method - HTTP method
+ * @returns {Promise<Object>} Response object
+ */
+function makeRequestWithMethod(url, method) {
+  return new Promise((resolve, reject) => {
+    const urlObj = new URL(url);
+    const options = {
+      hostname: urlObj.hostname,
+      port: urlObj.port,
+      path: urlObj.pathname,
+      method: method
+    };
+
+    const req = http.request(options, (res) => {
+      let body = '';
+      res.on('data', chunk => body += chunk);
+      res.on('end', () => {
+        resolve({
+          statusCode: res.statusCode,
+          headers: res.headers,
+          body
+        });
+      });
+    });
+
+    req.on('error', reject);
+    req.end();
+  });
+}

tests/integration/queue-concurrency.test.js

@@ -0,0 +1,192 @@
+/**
+ * Integration Tests: FIFO Queue Concurrency
+ * 
+ * Test T029: Verify concurrent requests are processed in FIFO order (one at a time)
+ * Tests the request queue implementation for /sitemap.xml endpoint
+ * 
+ * @module tests/integration/queue-concurrency
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+
+const TEST_PORT = 3001;
+
+// =============================================================================
+// T029: Integration test for concurrent requests (FIFO processing)
+// =============================================================================
+
+describe('T029: Concurrent Requests FIFO Processing', () => {
+  it('should process multiple concurrent requests in FIFO order (sequential)', async () => {
+    // Send multiple requests simultaneously
+    const requestCount = 5;
+    const startTime = Date.now();
+    const requests = [];
+
+    // Launch all requests at once
+    for (let i = 0; i < requestCount; i++) {
+      requests.push(makeTimedRequest(`http://localhost:${TEST_PORT}/sitemap.xml`, i));
+    }
+
+    // Wait for all requests to complete
+    const responses = await Promise.all(requests);
+
+    // Verify all requests succeeded
+    responses.forEach((response, index) => {
+      assert.equal(
+        response.statusCode,
+        200,
+        `Request ${index} should succeed with 200 OK`
+      );
+    });
+
+    // Verify sequential processing (FIFO)
+    // Each request should complete before the next starts
+    // If processed in parallel, total time ≈ single request time
+    // If processed sequentially, total time ≈ single request time × count
+    
+    const totalElapsed = Date.now() - startTime;
+    const averageRequestTime = responses.reduce((sum, r) => sum + r.elapsed, 0) / responses.length;
+
+    // Sequential processing means total time should be close to sum of individual times
+    // Allow some overhead for queue management
+    const expectedMinTime = averageRequestTime * (requestCount - 1); // Allow first request to be instant
+    
+    assert.ok(
+      totalElapsed >= expectedMinTime * 0.8, // 80% threshold for timing variability
+      `Total time (${totalElapsed}ms) should be close to sequential sum (${expectedMinTime}ms), indicating FIFO processing`
+    );
+  });
+
+  it('should maintain FIFO order: first request finishes before second starts processing', async () => {
+    // Track request processing order
+    const processingLog = [];
+
+    // Mock Drive API to log when each request is processed
+    // TODO: Add timing hooks in implementation to verify order
+
+    // Send two requests with small delay
+    const request1 = makeTimedRequest(`http://localhost:${TEST_PORT}/sitemap.xml`, 1);
+    
+    // Small delay to ensure request 1 is queued first
+    await new Promise(resolve => setTimeout(resolve, 10));
+    
+    const request2 = makeTimedRequest(`http://localhost:${TEST_PORT}/sitemap.xml`, 2);
+
+    const [response1, response2] = await Promise.all([request1, request2]);
+
+    // Both should succeed
+    assert.equal(response1.statusCode, 200, 'Request 1 should succeed');
+    assert.equal(response2.statusCode, 200, 'Request 2 should succeed');
+
+    // Request 1 should complete before request 2 starts processing
+    // Verify by checking that request 2 completion time > request 1 completion time
+    assert.ok(
+      response2.completedAt > response1.completedAt,
+      'Request 2 should complete after Request 1 (FIFO order)'
+    );
+  });
+
+  it('should only process one request at a time (no concurrent Drive API calls)', async () => {
+    // Send 3 requests simultaneously
+    const requests = [
+      makeTimedRequest(`http://localhost:${TEST_PORT}/sitemap.xml`, 1),
+      makeTimedRequest(`http://localhost:${TEST_PORT}/sitemap.xml`, 2),
+      makeTimedRequest(`http://localhost:${TEST_PORT}/sitemap.xml`, 3)
+    ];
+
+    const responses = await Promise.all(requests);
+
+    // Verify all succeeded
+    responses.forEach((response, index) => {
+      assert.equal(response.statusCode, 200, `Request ${index + 1} should succeed`);
+    });
+
+    // Check that completion times don't overlap
+    // Sort responses by completion time
+    const sortedResponses = responses.sort((a, b) => a.completedAt - b.completedAt);
+
+    // Each request should complete before the next one starts
+    for (let i = 0; i < sortedResponses.length - 1; i++) {
+      const current = sortedResponses[i];
+      const next = sortedResponses[i + 1];
+
+      // Next request should start after current completes
+      // (Allow small timing variance)
+      assert.ok(
+        next.startedAt >= current.completedAt - 50, // 50ms tolerance for timing
+        `Request ${i + 2} should start after Request ${i + 1} completes (FIFO guarantee)`
+      );
+    }
+  });
+
+  it('should handle queue correctly when requests fail', async () => {
+    // Test scenario: Request 1 succeeds, Request 2 fails (e.g., Drive API error), Request 3 succeeds
+    // Queue should continue processing despite failures
+
+    // TODO: Mock Drive API to fail for specific request
+    
+    const requests = [
+      makeTimedRequest(`http://localhost:${TEST_PORT}/sitemap.xml`, 1), // Should succeed
+      makeTimedRequest(`http://localhost:${TEST_PORT}/sitemap.xml`, 2), // Will fail (mock)
+      makeTimedRequest(`http://localhost:${TEST_PORT}/sitemap.xml`, 3)  // Should succeed
+    ];
+
+    const responses = await Promise.all(requests);
+
+    // Request 1 should succeed
+    assert.equal(responses[0].statusCode, 200, 'Request 1 should succeed');
+
+    // Request 2 should fail (mocked error)
+    // assert.notEqual(responses[1].statusCode, 200, 'Request 2 should fail');
+
+    // Request 3 should still succeed (queue continues)
+    assert.equal(responses[2].statusCode, 200, 'Request 3 should succeed despite Request 2 failure');
+
+    // All requests should still be processed in FIFO order
+    assert.ok(
+      responses[0].completedAt < responses[1].completedAt,
+      'Request 1 should complete before Request 2'
+    );
+    assert.ok(
+      responses[1].completedAt < responses[2].completedAt,
+      'Request 2 should complete before Request 3'
+    );
+  });
+});
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Make HTTP request and track timing
+ * @param {string} url - Full URL to request
+ * @param {number} requestId - Request identifier for logging
+ * @returns {Promise<Object>} Response with timing data
+ */
+function makeTimedRequest(url, requestId) {
+  const startedAt = Date.now();
+  
+  return new Promise((resolve, reject) => {
+    http.get(url, (res) => {
+      let body = '';
+      res.on('data', chunk => body += chunk);
+      res.on('end', () => {
+        const completedAt = Date.now();
+        const elapsed = completedAt - startedAt;
+        
+        resolve({
+          requestId,
+          statusCode: res.statusCode,
+          headers: res.headers,
+          body,
+          startedAt,
+          completedAt,
+          elapsed
+        });
+      });
+    }).on('error', reject);
+  });
+}

tests/integration/sitemap-endpoint.test.js

@@ -0,0 +1,136 @@
+/**
+ * Integration Tests: /sitemap.xml Endpoint
+ * 
+ * Tests T024, T030: End-to-end tests for sitemap generation
+ * Tests the complete flow: HTTP request → auth → Drive API → sitemap generation → HTTP response
+ * 
+ * @module tests/integration/sitemap-endpoint
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+
+// =============================================================================
+// T024: Integration test for /sitemap.xml endpoint success scenario
+// =============================================================================
+
+describe('T024: /sitemap.xml Endpoint Success Integration', () => {
+  let server;
+  const TEST_PORT = 3001;
+
+  before(async () => {
+    // TODO: Start server with mocked Drive API
+    // This will be implemented when src/server.js is complete
+  });
+
+  after(async () => {
+    // TODO: Stop server
+    if (server) {
+      server.close();
+    }
+  });
+
+  it('should return 200 with valid sitemap XML when Drive API returns documents', async () => {
+    // Mock Drive API to return sample documents
+    const mockDriveDocuments = [
+      {
+        id: 'doc1',
+        name: 'Test Document 1',
+        mimeType: 'application/pdf',
+        modifiedTime: '2024-03-01T10:30:00Z'
+      },
+      {
+        id: 'doc2',
+        name: 'Test Document 2',
+        mimeType: 'text/plain',
+        modifiedTime: '2024-03-02T15:45:00Z'
+      }
+    ];
+
+    // Make HTTP request to /sitemap.xml
+    const response = await makeRequest(`http://localhost:${TEST_PORT}/sitemap.xml`);
+
+    // Verify response
+    assert.equal(response.statusCode, 200, 'Should return 200 OK');
+    assert.equal(
+      response.headers['content-type'],
+      'application/xml; charset=utf-8',
+      'Should return XML content type'
+    );
+
+    // Verify XML structure
+    assert.match(response.body, /<urlset xmlns="http:\/\/www\.sitemaps\.org\/schemas\/sitemap\/0\.9">/, 'Should have valid urlset');
+    assert.match(response.body, /<url>/, 'Should contain URL entries');
+    assert.match(response.body, /<loc>.*\/documents\/doc1<\/loc>/, 'Should contain doc1 URL');
+    assert.match(response.body, /<loc>.*\/documents\/doc2<\/loc>/, 'Should contain doc2 URL');
+    assert.match(response.body, /<lastmod>2024-03-01<\/lastmod>/, 'Should contain formatted lastmod');
+  });
+
+  it('should return 200 with empty sitemap when Drive has no documents', async () => {
+    // Mock Drive API to return empty result
+    const response = await makeRequest(`http://localhost:${TEST_PORT}/sitemap.xml`);
+
+    assert.equal(response.statusCode, 200, 'Should return 200 OK for empty Drive');
+    assert.match(response.body, /<urlset xmlns="http:\/\/www\.sitemaps\.org\/schemas\/sitemap\/0\.9">/, 'Should have urlset');
+    assert.match(response.body, /<\/urlset>/, 'Should close urlset');
+    assert.doesNotMatch(response.body, /<url>/, 'Should not contain any url entries');
+  });
+});
+
+// =============================================================================
+// T030: Integration test for Service Account token refresh
+// =============================================================================
+
+describe('T030: Service Account Token Refresh Integration', () => {
+  it('should handle token expiry and refresh automatically', async () => {
+    // Mock scenario: first request succeeds, token expires, second request triggers refresh
+    
+    // First request - should succeed with valid token
+    const response1 = await makeRequest(`http://localhost:${TEST_PORT}/sitemap.xml`);
+    assert.equal(response1.statusCode, 200, 'First request should succeed');
+
+    // TODO: Mock token expiry by manipulating auth client
+    
+    // Second request - should auto-refresh token and succeed
+    const response2 = await makeRequest(`http://localhost:${TEST_PORT}/sitemap.xml`);
+    assert.equal(response2.statusCode, 200, 'Second request should succeed after token refresh');
+  });
+
+  it('should return 401 if token refresh fails', async () => {
+    // Mock scenario: token expires and refresh fails (invalid credentials)
+    
+    // TODO: Mock googleapis auth to fail on refresh
+    
+    const response = await makeRequest(`http://localhost:${TEST_PORT}/sitemap.xml`);
+    assert.equal(response.statusCode, 401, 'Should return 401 when auth fails');
+    
+    // Verify no response body (per spec: status code only errors)
+    assert.equal(response.body, '', 'Should have no response body for errors');
+  });
+});
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Make HTTP request and return response
+ * @param {string} url - Full URL to request
+ * @returns {Promise<Object>} Response object with statusCode, headers, body
+ */
+function makeRequest(url) {
+  return new Promise((resolve, reject) => {
+    http.get(url, (res) => {
+      let body = '';
+      res.on('data', chunk => body += chunk);
+      res.on('end', () => {
+        resolve({
+          statusCode: res.statusCode,
+          headers: res.headers,
+          body
+        });
+      });
+    }).on('error', reject);
+  });
+}

tests/integration/sitemap-integration.test.js

@@ -0,0 +1,75 @@
+/**
+ * Integration Tests for Sitemap Generation
+ * Tests the full sitemap generation flow with mocked Drive API
+ * 
+ * These tests verify:
+ * - T021: Full sitemap generation flow
+ * - T022: Pagination with 50k+ documents
+ * - T023: Rate limiting and retry logic
+ * - T024: OAuth token refresh
+ */
+
+import { test, describe, before, after, mock } from 'node:test';
+import assert from 'node:assert';
+
+describe('Integration: Sitemap Generation Flow', () => {
+  
+  test('T021: Should generate sitemap with mocked Drive API', async () => {
+    // This is a placeholder for the full integration test
+    // In the actual implementation, this would:
+    // 1. Mock the Drive API client
+    // 2. Provide mock document list
+    // 3. Call handleSitemapRequest
+    // 4. Verify XML output
+    
+    // Mock Drive API response
+    const mockDocuments = [
+      {
+        id: 'doc1',
+        name: 'Document 1',
+        mimeType: 'application/vnd.google-apps.document',
+        modifiedTime: '2026-03-07T10:00:00.000Z'
+      },
+      {
+        id: 'doc2',
+        name: 'Document 2',
+        mimeType: 'application/vnd.google-apps.spreadsheet',
+        modifiedTime: '2026-03-06T15:30:00.000Z'
+      }
+    ];
+    
+    // TODO: Implement full flow test with mocked Drive client
+    assert.ok(true, 'Integration test placeholder');
+  });
+  
+  test('T022: Should handle pagination for 50k+ documents', async () => {
+    // Test pagination logic
+    // This would mock Drive API to return multiple pages
+    // and verify all documents are included (up to 50k limit)
+    
+    const mockPageSize = 100;
+    const totalDocs = 500; // Simulate 500 documents across 5 pages
+    
+    // TODO: Implement pagination test
+    assert.ok(true, 'Pagination test placeholder');
+  });
+  
+  test('T023: Should handle rate limiting with retry logic', async () => {
+    // Test exponential backoff on 429 errors
+    // Mock Drive API to return 429 on first few attempts
+    // Verify retry logic works correctly
+    
+    // TODO: Implement rate limit test
+    assert.ok(true, 'Rate limit test placeholder');
+  });
+  
+  test('T024: Should handle OAuth token refresh', async () => {
+    // Test Service Account token refresh
+    // Mock expired token scenario
+    // Verify automatic re-authentication
+    
+    // TODO: Implement token refresh test
+    assert.ok(true, 'Token refresh test placeholder');
+  });
+  
+});