@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/04-REFERENCE/testing/modules/04-reference-testing-05-debugging.md

@@ -1,478 +1,478 @@
-# Module 5: Debugging
-
-**Level:** Intermediate
-**Estimated Time:** 20 minutes
-
-## Overview
-
-This module covers debugging techniques for test failures, error analysis patterns, and troubleshooting common issues.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Know how to enable verbose logging for detailed debugging
-- ✅ Understand how to analyze test errors systematically
-- ✅ Be able to categorize and diagnose common failure patterns
-- ✅ Know troubleshooting techniques for specific error types
-
-## Verbose Logging
-
-Enable detailed logging to understand what's happening during tests:
-
-```typescript
-import { S3SDKTester, createConsoleLogger } from '@fluentcommerce/fc-connect-sdk';
-
-// Create S3 tester with credentials
-const tester = new S3SDKTester({
-  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-  region: 'us-east-1'
-});
-
-// Run all S3 tests with verbose output
-const results = await tester.testAll('test-bucket');
-
-// Display verbose results
-console.log('Test Results:');
-console.log(`  Total: ${results.summary.total}`);
-console.log(`  Passed: ${results.summary.passed}`);
-console.log(`  Failed: ${results.summary.failed}`);
-console.log(`  Success Rate: ${results.summary.successRate.toFixed(2)}%`);
-
-// Show each test result
-Object.entries(results.tests).forEach(([testName, result]) => {
-  console.log(`\n${testName}:`, result.success ? '✅' : ');
-  if (result.message) console.log(`  Message: ${result.message}`);
-  if (result.duration) console.log(`  Duration: ${result.duration}ms`);
-  if (result.error) console.log(`  Error: ${result.error}`);
-});
-```
-
-### Analyzing Test Results with Categories
-
-```typescript
-import { S3SDKTester } from '@fluentcommerce/fc-connect-sdk';
-
-async function analyzeTestResults() {
-  const tester = new S3SDKTester({
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-    region: 'us-east-1'
-  });
-
-  const results = await tester.testAll('test-bucket');
-
-  // Categorize results
-  const passed = Object.entries(results.tests).filter(([_, r]) => r.success);
-  const failed = Object.entries(results.tests).filter(([_, r]) => !r.success);
-
-  console.log('TEST SUMMARY');
-  console.log('============');
-  console.log(`Total: ${results.summary.total}`);
-  console.log(`Passed: ${passed.length} (${results.summary.successRate.toFixed(1)}%)`);
-  console.log(`Failed: ${failed.length}`);
-  console.log(`Duration: ${results.summary.totalDuration}ms`);
-
-  if (failed.length > 0) {
-    console.log('\nFAILED TESTS');
-    console.log('============');
-    failed.forEach(([name, result]) => {
-      console.log(`${name}:`);
-      console.log(`  Message: ${result.message}`);
-      if (result.error) console.log(`  Error: ${result.error}`);
-    });
-  }
-
-  // Performance analysis
-  console.log('\nPERFORMANCE');
-  console.log('===========');
-  const avgDuration = results.summary.averageDuration;
-  console.log(`Average test duration: ${avgDuration.toFixed(0)}ms`);
-
-  const slowTests = Object.entries(results.tests)
-    .filter(([_, r]) => r.duration && r.duration > avgDuration * 2)
-    .sort((a, b) => (b[1].duration || 0) - (a[1].duration || 0));
-
-  if (slowTests.length > 0) {
-    console.log('Slow tests:');
-    slowTests.forEach(([name, result]) => {
-      console.log(`  ${name}: ${result.duration}ms`);
-    });
-  }
-}
-
-analyzeTestResults().catch(console.error);
-```
-
-## Categorizing Errors
-
-Systematically categorize and diagnose test failures:
-
-```typescript
-import { S3SDKTester } from '@fluentcommerce/fc-connect-sdk';
-
-async function categorizeErrors() {
-  const tester = new S3SDKTester({
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-    region: 'us-east-1'
-  });
-
-  const results = await tester.testAll('test-bucket');
-
-  if (results.summary.successRate === 100) {
-    console.log('✅ All tests passed, no errors to analyze');
-    return;
-  }
-
-  console.log('ERROR ANALYSIS');
-  console.log('==============\n');
-
-  // Collect all errors
-  const errors = Object.entries(results.tests)
-    .filter(([_, result]) => !result.success)
-    .map(([name, result]) => ({
-      test: name,
-      message: result.message,
-      error: result.error
-    }));
-
-  // Categorize errors
-  const authErrors = errors.filter(e =>
-    e.error?.includes('401') || e.error?.includes('403') ||
-    e.error?.includes('Unauthorized') || e.error?.includes('Forbidden')
-  );
-
-  const permissionErrors = errors.filter(e =>
-    e.error?.includes('Access Denied') || e.error?.includes('NoSuchBucket')
-  );
-
-  const networkErrors = errors.filter(e =>
-    e.error?.includes('ENOTFOUND') || e.error?.includes('ETIMEDOUT') ||
-    e.error?.includes('ECONNREFUSED') || e.error?.includes('Network')
-  );
-
-  // Report by category
-  if (authErrors.length > 0) {
-    console.log('AUTHENTICATION ISSUES:');
-    authErrors.forEach(e => {
-      console.log(`  ${e.test}: ${e.error}`);
-    });
-    console.log('  Action: Verify AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY\n');
-  }
-
-  if (permissionErrors.length > 0) {
-    console.log('PERMISSION ISSUES:');
-    permissionErrors.forEach(e => {
-      console.log(`  ${e.test}: ${e.error}`);
-    });
-    console.log('  Action: Check IAM policy and bucket permissions\n');
-  }
-
-  if (networkErrors.length > 0) {
-    console.log('NETWORK ISSUES:');
-    networkErrors.forEach(e => {
-      console.log(`  ${e.test}: ${e.error}`);
-    });
-    console.log('  Action: Check network connectivity and firewall rules\n');
-  }
-
-  // Other errors
-  const otherErrors = errors.filter(e =>
-    !authErrors.includes(e) &&
-    !permissionErrors.includes(e) &&
-    !networkErrors.includes(e)
-  );
-
-  if (otherErrors.length > 0) {
-    console.log('OTHER ERRORS:');
-    otherErrors.forEach(e => {
-      console.log(`  ${e.test}: ${e.error}`);
-    });
-  }
-}
-
-categorizeErrors().catch(console.error);
-```
-
-## Common Error Patterns
-
-### S3 Access Denied
-
-```typescript
-// Error: AccessDenied
-// Cause: Insufficient IAM permissions
-// Solution:
-
-async function diagnoseS3AccessDenied() {
-  console.log('Diagnosing S3 Access Denied error...');
-
-  // Check if credentials are set
-  if (!process.env.AWS_ACCESS_KEY_ID) {
-    console.error('❌ AWS_ACCESS_KEY_ID not set');
-    return;
-  }
-  if (!process.env.AWS_SECRET_ACCESS_KEY) {
-    console.error('❌ AWS_SECRET_ACCESS_KEY not set');
-    return;
-  }
-
-  console.log('✅ Credentials are set');
-
-  // Check bucket access
-  console.log('Testing bucket access...');
-  const tester = new S3SDKTester({
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
-    region: 'us-east-1'
-  });
-
-  const results = await tester.testAll('test-bucket');
-
-  // Check which operations failed
-  const failedOps = Object.entries(results.tests)
-    .filter(([_, result]) => !result.success);
-
-  if (failedOps.length > 0) {
-    console.error('❌ Some operations failed:');
-    failedOps.forEach(([op, result]) => {
-      console.log(`  ${op}: ${result.error}`);
-    });
-
-    console.log('\nRequired IAM permissions:');
-    console.log('  - s3:ListBucket');
-    console.log('  - s3:GetObject');
-    console.log('  - s3:PutObject');
-    console.log('  - s3:DeleteObject');
-    console.log('  - s3:GetBucketLocation');
-  } else {
-    console.log('✅ All S3 operations successful');
-  }
-}
-```
-
-### Fluent Authentication Failed
-
-```typescript
-// Error: 401 Unauthorized
-// Cause: Invalid OAuth2 credentials
-// Solution:
-
-async function diagnoseFluentAuth() {
-  console.log('Diagnosing Fluent Authentication...');
-
-  // Verify credentials are set
-  const required = [
-    'FLUENT_BASE_URL',
-    'FLUENT_CLIENT_ID',
-    'FLUENT_CLIENT_SECRET',
-    'FLUENT_USERNAME',
-    'FLUENT_PASSWORD',
-    'FLUENT_RETAILER_ID'
-  ];
-
-  const missing = required.filter(key => !process.env[key]);
-
-  if (missing.length > 0) {
-    console.error('❌ Missing required environment variables:');
-    missing.forEach(key => console.error(`  - ${key}`));
-    return;
-  }
-
-  console.log('✅ All environment variables set');
-
-  // Test connection
-  try {
-    const client = await createClient({
-      config: {
-        baseUrl: process.env.FLUENT_BASE_URL!,
-        clientId: process.env.FLUENT_CLIENT_ID!,
-        clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-        username: process.env.FLUENT_USERNAME!,
-        password: process.env.FLUENT_PASSWORD!,
-        retailerId: process.env.FLUENT_RETAILER_ID!
-      }
-    });
-
-    const tester = new FluentConnectionTester(client, {
-      retailerId: process.env.FLUENT_RETAILER_ID!
-    });
-
-    const result = await tester.testConnection();
-
-    if (result.success) {
-      console.log('✅ Connection test successful');
-      console.log(`   User: ${result.details?.username}`);
-      console.log(`   Retailer: ${result.details?.retailerName}`);
-    } else {
-      console.error('❌ Connection test failed');
-      console.log(`Error: ${result.error}`);
-      console.log('Check:');
-      console.log('  1. Client ID and secret are correct');
-      console.log('  2. Username and password are valid');
-      console.log('  3. User has appropriate permissions');
-      console.log('  4. Retailer ID matches your account');
-    }
-  } catch (error) {
-    console.error('❌ Error during connection test:', error instanceof Error ? error.message : String(error));
-  }
-}
-```
-
-### Network Timeout Errors
-
-```typescript
-// Error: ETIMEDOUT
-// Cause: Network latency or service unavailability
-// Solution:
-
-async function diagnoseTimeout() {
-  console.log('Diagnosing timeout issues...');
-
-  const tester = new S3SDKTester({
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-    region: 'us-east-1'
-  });
-
-  console.log('Testing S3 connectivity...');
-  const results = await tester.testAll('test-bucket');
-
-  // Check if timeouts occurred
-  const timedOut = Object.entries(results.tests)
-    .filter(([_, r]) => r.error?.includes('timeout') || r.error?.includes('ETIMEDOUT'));
-
-  if (timedOut.length > 0) {
-    console.log('❌ Timeout errors detected:');
-    timedOut.forEach(([op, result]) => {
-      console.log(`  ${op}: ${result.error}`);
-      console.log(`  Duration: ${result.duration}ms`);
-    });
-    console.log('\nRecommendation: Network may be slow or service is unresponsive');
-  } else if (results.summary.totalDuration > 30000) {
-    console.log('⚠️ Tests completed but response is slow:');
-    console.log(`  Total duration: ${results.summary.totalDuration}ms`);
-    console.log(`  Average per test: ${results.summary.averageDuration.toFixed(0)}ms`);
-  } else {
-    console.log('✅ No timeout issues detected');
-    console.log(`  Total duration: ${results.summary.totalDuration}ms`);
-  }
-}
-```
-
-## Debugging Checklist
-
-Use this checklist when tests fail:
-
-```typescript
-async function runDiagnostics() {
-  console.log('=== Test Diagnostics Checklist ===\n');
-
-  // 1. Environment variables
-  console.log('1. Environment Variables:');
-  const requiredVars = [
-    'AWS_ACCESS_KEY_ID',
-    'AWS_SECRET_ACCESS_KEY',
-    'AWS_REGION',
-    'FLUENT_CLIENT_ID',
-    'FLUENT_CLIENT_SECRET'
-  ];
-
-  requiredVars.forEach(varName => {
-    const status = process.env[varName] ? '✅' : ';
-    console.log(`   ${status} ${varName}`);
-  });
-
-  // 2. Network connectivity
-  console.log('\n2. Network Connectivity:');
-  try {
-    const https = require('https');
-    await new Promise((resolve, reject) => {
-      https.get('https://api.fluentcommerce.com', (res) => {
-        console.log(`   ✅ Can reach Fluent API (status: ${res.statusCode})`);
-        resolve();
-      }).on('error', reject);
-    });
-  } catch (error) {
-    console.log(`   ❌ Cannot reach Fluent API: ${error.message}`);
-  }
-
-  // 3. S3 connectivity
-  console.log('\n3. S3 Connectivity:');
-  try {
-    const s3Tester = new S3SDKTester({
-      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-      region: process.env.AWS_REGION || 'us-east-1'
-    });
-
-    const results = await s3Tester.testAll(process.env.S3_BUCKET!);
-    const success = results.summary.successRate === 100;
-    console.log(`   ${success ? '✅' : '} S3 access (${results.summary.passed}/${results.summary.total} tests)`);
-  } catch (error) {
-    console.log(`   ❌ S3 error: ${error instanceof Error ? error.message : String(error)}`);
-  }
-
-  // 4. Fluent API connectivity
-  console.log('\n4. Fluent API Connectivity:');
-  try {
-    const client = await createClient({
-      config: {
-        baseUrl: process.env.FLUENT_BASE_URL!,
-        clientId: process.env.FLUENT_CLIENT_ID!,
-        clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-        username: process.env.FLUENT_USERNAME!,
-        password: process.env.FLUENT_PASSWORD!,
-        retailerId: process.env.FLUENT_RETAILER_ID!
-      }
-    });
-
-    const tester = new FluentConnectionTester(client, {
-      retailerId: process.env.FLUENT_RETAILER_ID!
-    });
-
-    const result = await tester.testConnection();
-    console.log(`   ${result.success ? '✅' : '} Fluent API access`);
-    if (result.success) {
-      console.log(`      User: ${result.details?.username}`);
-    }
-  } catch (error) {
-    console.log(`   ❌ Fluent API error: ${error instanceof Error ? error.message : String(error)}`);
-  }
-
-  console.log('\n=== Diagnostics Complete ===');
-}
-```
-
-## Key Takeaways
-
-- 🎯 Enable verbose logging to see detailed test execution
-- 🎯 Use error analysis functions to categorize failures
-- 🎯 Check authentication and permissions first
-- 🎯 Verify network connectivity and timeouts
-- 🎯 Use diagnostics checklist for systematic troubleshooting
-
-## Practice Exercise
-
-Create a diagnostic script for your environment:
-
-```typescript
-async function diagnoseMyEnvironment() {
-  // TODO: Check environment variables
-  // TODO: Test S3 connectivity
-  // TODO: Test Fluent API connectivity
-  // TODO: Analyze any errors
-}
-```
-
-## Next Steps
-
-Continue to [Module 6: CI/CD Integration →](./04-reference-testing-06-cicd-integration.md) to learn about automation.
-
----
-
-**Module Navigation:**
-- **Previous:** [Module 4 - Integration Testing](./04-reference-testing-04-integration-testing.md)
-- **Current:** Module 5 - Debugging
-- **Next:** [Module 6 - CI/CD Integration](./04-reference-testing-06-cicd-integration.md)
-- **Back to:** [Testing Guide Index](../testing-readme.md)
+# Module 5: Debugging
+
+**Level:** Intermediate
+**Estimated Time:** 20 minutes
+
+## Overview
+
+This module covers debugging techniques for test failures, error analysis patterns, and troubleshooting common issues.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Know how to enable verbose logging for detailed debugging
+- ✅ Understand how to analyze test errors systematically
+- ✅ Be able to categorize and diagnose common failure patterns
+- ✅ Know troubleshooting techniques for specific error types
+
+## Verbose Logging
+
+Enable detailed logging to understand what's happening during tests:
+
+```typescript
+import { S3SDKTester, createConsoleLogger } from '@fluentcommerce/fc-connect-sdk';
+
+// Create S3 tester with credentials
+const tester = new S3SDKTester({
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  region: 'us-east-1'
+});
+
+// Run all S3 tests with verbose output
+const results = await tester.testAll('test-bucket');
+
+// Display verbose results
+console.log('Test Results:');
+console.log(`  Total: ${results.summary.total}`);
+console.log(`  Passed: ${results.summary.passed}`);
+console.log(`  Failed: ${results.summary.failed}`);
+console.log(`  Success Rate: ${results.summary.successRate.toFixed(2)}%`);
+
+// Show each test result
+Object.entries(results.tests).forEach(([testName, result]) => {
+  console.log(`\n${testName}:`, result.success ? '✅' : ');
+  if (result.message) console.log(`  Message: ${result.message}`);
+  if (result.duration) console.log(`  Duration: ${result.duration}ms`);
+  if (result.error) console.log(`  Error: ${result.error}`);
+});
+```
+
+### Analyzing Test Results with Categories
+
+```typescript
+import { S3SDKTester } from '@fluentcommerce/fc-connect-sdk';
+
+async function analyzeTestResults() {
+  const tester = new S3SDKTester({
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    region: 'us-east-1'
+  });
+
+  const results = await tester.testAll('test-bucket');
+
+  // Categorize results
+  const passed = Object.entries(results.tests).filter(([_, r]) => r.success);
+  const failed = Object.entries(results.tests).filter(([_, r]) => !r.success);
+
+  console.log('TEST SUMMARY');
+  console.log('============');
+  console.log(`Total: ${results.summary.total}`);
+  console.log(`Passed: ${passed.length} (${results.summary.successRate.toFixed(1)}%)`);
+  console.log(`Failed: ${failed.length}`);
+  console.log(`Duration: ${results.summary.totalDuration}ms`);
+
+  if (failed.length > 0) {
+    console.log('\nFAILED TESTS');
+    console.log('============');
+    failed.forEach(([name, result]) => {
+      console.log(`${name}:`);
+      console.log(`  Message: ${result.message}`);
+      if (result.error) console.log(`  Error: ${result.error}`);
+    });
+  }
+
+  // Performance analysis
+  console.log('\nPERFORMANCE');
+  console.log('===========');
+  const avgDuration = results.summary.averageDuration;
+  console.log(`Average test duration: ${avgDuration.toFixed(0)}ms`);
+
+  const slowTests = Object.entries(results.tests)
+    .filter(([_, r]) => r.duration && r.duration > avgDuration * 2)
+    .sort((a, b) => (b[1].duration || 0) - (a[1].duration || 0));
+
+  if (slowTests.length > 0) {
+    console.log('Slow tests:');
+    slowTests.forEach(([name, result]) => {
+      console.log(`  ${name}: ${result.duration}ms`);
+    });
+  }
+}
+
+analyzeTestResults().catch(console.error);
+```
+
+## Categorizing Errors
+
+Systematically categorize and diagnose test failures:
+
+```typescript
+import { S3SDKTester } from '@fluentcommerce/fc-connect-sdk';
+
+async function categorizeErrors() {
+  const tester = new S3SDKTester({
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    region: 'us-east-1'
+  });
+
+  const results = await tester.testAll('test-bucket');
+
+  if (results.summary.successRate === 100) {
+    console.log('✅ All tests passed, no errors to analyze');
+    return;
+  }
+
+  console.log('ERROR ANALYSIS');
+  console.log('==============\n');
+
+  // Collect all errors
+  const errors = Object.entries(results.tests)
+    .filter(([_, result]) => !result.success)
+    .map(([name, result]) => ({
+      test: name,
+      message: result.message,
+      error: result.error
+    }));
+
+  // Categorize errors
+  const authErrors = errors.filter(e =>
+    e.error?.includes('401') || e.error?.includes('403') ||
+    e.error?.includes('Unauthorized') || e.error?.includes('Forbidden')
+  );
+
+  const permissionErrors = errors.filter(e =>
+    e.error?.includes('Access Denied') || e.error?.includes('NoSuchBucket')
+  );
+
+  const networkErrors = errors.filter(e =>
+    e.error?.includes('ENOTFOUND') || e.error?.includes('ETIMEDOUT') ||
+    e.error?.includes('ECONNREFUSED') || e.error?.includes('Network')
+  );
+
+  // Report by category
+  if (authErrors.length > 0) {
+    console.log('AUTHENTICATION ISSUES:');
+    authErrors.forEach(e => {
+      console.log(`  ${e.test}: ${e.error}`);
+    });
+    console.log('  Action: Verify AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY\n');
+  }
+
+  if (permissionErrors.length > 0) {
+    console.log('PERMISSION ISSUES:');
+    permissionErrors.forEach(e => {
+      console.log(`  ${e.test}: ${e.error}`);
+    });
+    console.log('  Action: Check IAM policy and bucket permissions\n');
+  }
+
+  if (networkErrors.length > 0) {
+    console.log('NETWORK ISSUES:');
+    networkErrors.forEach(e => {
+      console.log(`  ${e.test}: ${e.error}`);
+    });
+    console.log('  Action: Check network connectivity and firewall rules\n');
+  }
+
+  // Other errors
+  const otherErrors = errors.filter(e =>
+    !authErrors.includes(e) &&
+    !permissionErrors.includes(e) &&
+    !networkErrors.includes(e)
+  );
+
+  if (otherErrors.length > 0) {
+    console.log('OTHER ERRORS:');
+    otherErrors.forEach(e => {
+      console.log(`  ${e.test}: ${e.error}`);
+    });
+  }
+}
+
+categorizeErrors().catch(console.error);
+```
+
+## Common Error Patterns
+
+### S3 Access Denied
+
+```typescript
+// Error: AccessDenied
+// Cause: Insufficient IAM permissions
+// Solution:
+
+async function diagnoseS3AccessDenied() {
+  console.log('Diagnosing S3 Access Denied error...');
+
+  // Check if credentials are set
+  if (!process.env.AWS_ACCESS_KEY_ID) {
+    console.error('❌ AWS_ACCESS_KEY_ID not set');
+    return;
+  }
+  if (!process.env.AWS_SECRET_ACCESS_KEY) {
+    console.error('❌ AWS_SECRET_ACCESS_KEY not set');
+    return;
+  }
+
+  console.log('✅ Credentials are set');
+
+  // Check bucket access
+  console.log('Testing bucket access...');
+  const tester = new S3SDKTester({
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    region: 'us-east-1'
+  });
+
+  const results = await tester.testAll('test-bucket');
+
+  // Check which operations failed
+  const failedOps = Object.entries(results.tests)
+    .filter(([_, result]) => !result.success);
+
+  if (failedOps.length > 0) {
+    console.error('❌ Some operations failed:');
+    failedOps.forEach(([op, result]) => {
+      console.log(`  ${op}: ${result.error}`);
+    });
+
+    console.log('\nRequired IAM permissions:');
+    console.log('  - s3:ListBucket');
+    console.log('  - s3:GetObject');
+    console.log('  - s3:PutObject');
+    console.log('  - s3:DeleteObject');
+    console.log('  - s3:GetBucketLocation');
+  } else {
+    console.log('✅ All S3 operations successful');
+  }
+}
+```
+
+### Fluent Authentication Failed
+
+```typescript
+// Error: 401 Unauthorized
+// Cause: Invalid OAuth2 credentials
+// Solution:
+
+async function diagnoseFluentAuth() {
+  console.log('Diagnosing Fluent Authentication...');
+
+  // Verify credentials are set
+  const required = [
+    'FLUENT_BASE_URL',
+    'FLUENT_CLIENT_ID',
+    'FLUENT_CLIENT_SECRET',
+    'FLUENT_USERNAME',
+    'FLUENT_PASSWORD',
+    'FLUENT_RETAILER_ID'
+  ];
+
+  const missing = required.filter(key => !process.env[key]);
+
+  if (missing.length > 0) {
+    console.error('❌ Missing required environment variables:');
+    missing.forEach(key => console.error(`  - ${key}`));
+    return;
+  }
+
+  console.log('✅ All environment variables set');
+
+  // Test connection
+  try {
+    const client = await createClient({
+      config: {
+        baseUrl: process.env.FLUENT_BASE_URL!,
+        clientId: process.env.FLUENT_CLIENT_ID!,
+        clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+        username: process.env.FLUENT_USERNAME!,
+        password: process.env.FLUENT_PASSWORD!,
+        retailerId: process.env.FLUENT_RETAILER_ID!
+      }
+    });
+
+    const tester = new FluentConnectionTester(client, {
+      retailerId: process.env.FLUENT_RETAILER_ID!
+    });
+
+    const result = await tester.testConnection();
+
+    if (result.success) {
+      console.log('✅ Connection test successful');
+      console.log(`   User: ${result.details?.username}`);
+      console.log(`   Retailer: ${result.details?.retailerName}`);
+    } else {
+      console.error('❌ Connection test failed');
+      console.log(`Error: ${result.error}`);
+      console.log('Check:');
+      console.log('  1. Client ID and secret are correct');
+      console.log('  2. Username and password are valid');
+      console.log('  3. User has appropriate permissions');
+      console.log('  4. Retailer ID matches your account');
+    }
+  } catch (error) {
+    console.error('❌ Error during connection test:', error instanceof Error ? error.message : String(error));
+  }
+}
+```
+
+### Network Timeout Errors
+
+```typescript
+// Error: ETIMEDOUT
+// Cause: Network latency or service unavailability
+// Solution:
+
+async function diagnoseTimeout() {
+  console.log('Diagnosing timeout issues...');
+
+  const tester = new S3SDKTester({
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    region: 'us-east-1'
+  });
+
+  console.log('Testing S3 connectivity...');
+  const results = await tester.testAll('test-bucket');
+
+  // Check if timeouts occurred
+  const timedOut = Object.entries(results.tests)
+    .filter(([_, r]) => r.error?.includes('timeout') || r.error?.includes('ETIMEDOUT'));
+
+  if (timedOut.length > 0) {
+    console.log('❌ Timeout errors detected:');
+    timedOut.forEach(([op, result]) => {
+      console.log(`  ${op}: ${result.error}`);
+      console.log(`  Duration: ${result.duration}ms`);
+    });
+    console.log('\nRecommendation: Network may be slow or service is unresponsive');
+  } else if (results.summary.totalDuration > 30000) {
+    console.log('⚠️ Tests completed but response is slow:');
+    console.log(`  Total duration: ${results.summary.totalDuration}ms`);
+    console.log(`  Average per test: ${results.summary.averageDuration.toFixed(0)}ms`);
+  } else {
+    console.log('✅ No timeout issues detected');
+    console.log(`  Total duration: ${results.summary.totalDuration}ms`);
+  }
+}
+```
+
+## Debugging Checklist
+
+Use this checklist when tests fail:
+
+```typescript
+async function runDiagnostics() {
+  console.log('=== Test Diagnostics Checklist ===\n');
+
+  // 1. Environment variables
+  console.log('1. Environment Variables:');
+  const requiredVars = [
+    'AWS_ACCESS_KEY_ID',
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_REGION',
+    'FLUENT_CLIENT_ID',
+    'FLUENT_CLIENT_SECRET'
+  ];
+
+  requiredVars.forEach(varName => {
+    const status = process.env[varName] ? '✅' : ';
+    console.log(`   ${status} ${varName}`);
+  });
+
+  // 2. Network connectivity
+  console.log('\n2. Network Connectivity:');
+  try {
+    const https = require('https');
+    await new Promise((resolve, reject) => {
+      https.get('https://api.fluentcommerce.com', (res) => {
+        console.log(`   ✅ Can reach Fluent API (status: ${res.statusCode})`);
+        resolve();
+      }).on('error', reject);
+    });
+  } catch (error) {
+    console.log(`   ❌ Cannot reach Fluent API: ${error.message}`);
+  }
+
+  // 3. S3 connectivity
+  console.log('\n3. S3 Connectivity:');
+  try {
+    const s3Tester = new S3SDKTester({
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+      region: process.env.AWS_REGION || 'us-east-1'
+    });
+
+    const results = await s3Tester.testAll(process.env.S3_BUCKET!);
+    const success = results.summary.successRate === 100;
+    console.log(`   ${success ? '✅' : '} S3 access (${results.summary.passed}/${results.summary.total} tests)`);
+  } catch (error) {
+    console.log(`   ❌ S3 error: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  // 4. Fluent API connectivity
+  console.log('\n4. Fluent API Connectivity:');
+  try {
+    const client = await createClient({
+      config: {
+        baseUrl: process.env.FLUENT_BASE_URL!,
+        clientId: process.env.FLUENT_CLIENT_ID!,
+        clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+        username: process.env.FLUENT_USERNAME!,
+        password: process.env.FLUENT_PASSWORD!,
+        retailerId: process.env.FLUENT_RETAILER_ID!
+      }
+    });
+
+    const tester = new FluentConnectionTester(client, {
+      retailerId: process.env.FLUENT_RETAILER_ID!
+    });
+
+    const result = await tester.testConnection();
+    console.log(`   ${result.success ? '✅' : '} Fluent API access`);
+    if (result.success) {
+      console.log(`      User: ${result.details?.username}`);
+    }
+  } catch (error) {
+    console.log(`   ❌ Fluent API error: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  console.log('\n=== Diagnostics Complete ===');
+}
+```
+
+## Key Takeaways
+
+- 🎯 Enable verbose logging to see detailed test execution
+- 🎯 Use error analysis functions to categorize failures
+- 🎯 Check authentication and permissions first
+- 🎯 Verify network connectivity and timeouts
+- 🎯 Use diagnostics checklist for systematic troubleshooting
+
+## Practice Exercise
+
+Create a diagnostic script for your environment:
+
+```typescript
+async function diagnoseMyEnvironment() {
+  // TODO: Check environment variables
+  // TODO: Test S3 connectivity
+  // TODO: Test Fluent API connectivity
+  // TODO: Analyze any errors
+}
+```
+
+## Next Steps
+
+Continue to [Module 6: CI/CD Integration →](./04-reference-testing-06-cicd-integration.md) to learn about automation.
+
+---
+
+**Module Navigation:**
+- **Previous:** [Module 4 - Integration Testing](./04-reference-testing-04-integration-testing.md)
+- **Current:** Module 5 - Debugging
+- **Next:** [Module 6 - CI/CD Integration](./04-reference-testing-06-cicd-integration.md)
+- **Back to:** [Testing Guide Index](../testing-readme.md)