@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/04-REFERENCE/testing/testing-quick-reference.md

@@ -1,667 +1,667 @@
-# Testing Utilities Quick Reference
-
-> Complete reference for all SDK testing utilities with accurate APIs
-
-## S3SDKTester
-
-Tests S3 operations using the AWS SDK directly.
-
-### Constructor
-
-```typescript
-import { S3SDKTester } from '@fluentcommerce/fc-connect-sdk';
-
-const tester = new S3SDKTester({
-  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
-  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
-  region: 'us-east-1',
-  sessionToken?: string  // Optional
-});
-```
-
-### Methods
-
-**Single method - runs all tests:**
-
-```typescript
-// Run all 9 S3 operations tests
-const results = await tester.testAll('test-bucket-name');
-
-// Returns SDKTestResults
-interface SDKTestResults {
-  implementation: 'sdk';
-  timestamp: string;
-  tests: {
-    list: TestResult;
-    write: TestResult;
-    read: TestResult;
-    copy: TestResult;
-    head: TestResult;
-    move: TestResult;
-    delete: TestResult;
-    multipart: TestResult;
-    select: TestResult;
-  };
-  summary: {
-    total: number;
-    passed: number;
-    failed: number;
-    successRate: number;
-    totalDuration: number;
-    averageDuration: number;
-  };
-}
-```
-
-### Complete Example
-
-```typescript
-import { S3SDKTester } from '@fluentcommerce/fc-connect-sdk';
-
-async function testS3Connection() {
-  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('my-test-bucket');
-
-  console.log(`Tests: ${results.summary.passed}/${results.summary.total} passed`);
-  console.log(`Success rate: ${results.summary.successRate}%`);
-
-  // Check individual tests
-  if (!results.tests.write.success) {
-    console.error('Write test failed:', results.tests.write.error);
-  }
-
-  return results.summary.successRate === 100;
-}
-```
-
-## S3PresignedTester
-
-Tests S3 operations using presigned URLs.
-
-### Constructor
-
-```typescript
-import { S3PresignedTester } from '@fluentcommerce/fc-connect-sdk';
-
-const tester = new S3PresignedTester(
-  {
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
-    region: 'us-east-1',
-    sessionToken?: string  // Optional
-  },
-  fetch  // Provide fetch implementation
-);
-```
-
-### Methods
-
-**Single method - runs all tests:**
-
-```typescript
-// Run all 8 presigned URL tests
-const results = await tester.testAll('test-bucket-name');
-
-// Returns PresignedTestResults
-interface PresignedTestResults {
-  implementation: 'presigned';
-  timestamp: string;
-  tests: {
-    list: TestResult;
-    write: TestResult;
-    read: TestResult;
-    copy: TestResult;
-    head: TestResult;
-    move: TestResult;
-    delete: TestResult;
-    advancedFeatures: TestResult;
-  };
-  summary: {
-    total: number;
-    passed: number;
-    failed: number;
-    successRate: number;
-    totalDuration: number;
-    averageDuration: number;
-  };
-}
-```
-
-### Complete Example
-
-```typescript
-import { S3PresignedTester } from '@fluentcommerce/fc-connect-sdk';
-
-async function testPresignedUrls() {
-  const tester = new S3PresignedTester(
-    {
-      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-      region: 'us-east-1'
-    },
-    globalThis.fetch
-  );
-
-  const results = await tester.testAll('my-test-bucket');
-
-  console.log(`Presigned URL tests: ${results.summary.passed}/${results.summary.total} passed`);
-
-  // Check advanced features
-  if (results.tests.advancedFeatures.success) {
-    console.log('Advanced features supported');
-  }
-
-  return results.summary.successRate === 100;
-}
-```
-
-## S3ComparisonTester
-
-Compares SDK vs Presigned URL approaches.
-
-### Constructor
-
-```typescript
-import { S3ComparisonTester } from '@fluentcommerce/fc-connect-sdk';
-
-// NO PARAMETERS - instantiate empty
-const tester = new S3ComparisonTester();
-```
-
-### Methods
-
-**Single method - compares implementations:**
-
-```typescript
-// Compare SDK vs Presigned approaches
-const comparison = await tester.compareImplementations(
-  {
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
-    region: 'us-east-1'
-  },
-  'test-bucket-name',
-  globalThis.fetch  // Optional custom fetch
-);
-
-// Returns ComparisonResults
-interface ComparisonResults {
-  sdk: SDKTestResults;
-  presigned: PresignedTestResults;
-  comparison: {
-    totalTests: number;
-    sdkPassed: number;
-    presignedPassed: number;
-    bothPassed: number;
-    bothFailed: number;
-    onlySdkPassed: number;
-    onlyPresignedPassed: number;
-  };
-  recommendation: string;
-}
-```
-
-### Complete Example
-
-```typescript
-import { S3ComparisonTester } from '@fluentcommerce/fc-connect-sdk';
-
-async function compareS3Approaches() {
-  const tester = new S3ComparisonTester();
-
-  const results = await tester.compareImplementations(
-    {
-      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-      region: 'us-east-1'
-    },
-    'my-test-bucket',
-    globalThis.fetch
-  );
-
-  console.log('SDK approach:', results.sdk.summary);
-  console.log('Presigned approach:', results.presigned.summary);
-  console.log('Recommendation:', results.recommendation);
-
-  // Detailed comparison
-  const { comparison } = results;
-  console.log(`Both passed: ${comparison.bothPassed}`);
-  console.log(`Only SDK passed: ${comparison.onlySdkPassed}`);
-  console.log(`Only Presigned passed: ${comparison.onlyPresignedPassed}`);
-
-  return results;
-}
-```
-
-## FluentConnectionTester
-
-Tests Fluent Commerce API connectivity.
-
-### Constructor
-
-```typescript
-import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// Create Fluent client using universal factory (recommended)
-const client = await createClient({
-  config: {
-    baseUrl: 'https://api.fluentcommerce.com',
-    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
-  }
-});
-
-// Create tester
-const tester = new FluentConnectionTester(
-  client,
-  {
-    retailerId: '1',
-    testJobId?: string,     // Optional
-    testQuery?: string,     // Optional
-    testEvent?: any,        // Optional
-    testBatch?: any,        // Optional
-    logger?: Logger         // Optional
-  }
-);
-```
-
-### Methods
-
-**Single method - tests connection:**
-
-```typescript
-// Test Fluent API connection
-const result = await tester.testConnection();
-
-// Returns TestResult with connection details
-interface TestResult {
-  success: boolean;
-  message?: string;
-  operation?: string;
-  details?: {
-    userId: string;
-    username: string;
-    userType: string;
-    userStatus: string;
-    retailerId: string;
-    retailerRef: string;
-    retailerName: string;
-    locationId: string;
-    locationRef: string;
-    locationName: string;
-  };
-  errors?: any[];
-  error?: string;
-  timestamp?: string;
-  duration?: number;
-}
-```
-
-### Complete Example
-
-```typescript
-import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
-
-async function testFluentConnection() {
-  // Create client using universal factory (recommended)
-  const client = await createClient({
-    config: {
-      baseUrl: 'https://api.fluentcommerce.com',
-      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!
-    }
-  });
-
-  // Create tester
-  const tester = new FluentConnectionTester(client, {
-    retailerId: process.env.FLUENT_RETAILER_ID!
-  });
-
-  // Test connection
-  const result = await tester.testConnection();
-
-  if (result.success) {
-    console.log('Connected successfully!');
-    console.log('User:', result.details?.username);
-    console.log('Retailer:', result.details?.retailerName);
-    console.log('Location:', result.details?.locationName);
-  } else {
-    console.error('Connection failed:', result.error);
-  }
-
-  return result;
-}
-```
-
-## TestResult Interface
-
-Common interface returned by all test operations:
-
-```typescript
-interface TestResult {
-  success: boolean;        // Overall success/failure
-  message?: string;        // Success message
-  operation?: string;      // Operation name (e.g., 'list', 'write')
-  details?: any;          // Operation-specific details
-  errors?: any[];         // Array of errors (if multiple)
-  error?: string;         // Single error message
-  timestamp?: string;     // ISO timestamp
-  duration?: number;      // Duration in milliseconds
-}
-```
-
-## Common Patterns
-
-### Health Check Endpoint
-
-```typescript
-import { FluentConnectionTester, FluentClient } from '@fluentcommerce/fc-connect-sdk';
-
-async function healthCheck(): Promise<{
-  status: 'healthy' | 'unhealthy';
-  fluent: { connected: boolean; duration?: number };
-  timestamp: string;
-}> {
-  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: '1' });
-
-  const result = await tester.testConnection();
-
-  return {
-    status: result.success ? 'healthy' : 'unhealthy',
-    fluent: {
-      connected: result.success,
-      duration: result.duration
-    },
-    timestamp: new Date().toISOString()
-  };
-}
-```
-
-### Complete Integration Test
-
-```typescript
-import {
-  S3SDKTester,
-  FluentConnectionTester,
-  FluentClient
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function runIntegrationTests() {
-  // Test S3
-  const s3Tester = new S3SDKTester({
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-    region: 'us-east-1'
-  });
-
-  const s3Results = await s3Tester.testAll('test-bucket');
-
-  // Test Fluent
-  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 fluentTester = new FluentConnectionTester(client, { retailerId: '1' });
-  const fluentResults = await fluentTester.testConnection();
-
-  // Verify both passed
-  const allPassed =
-    s3Results.summary.successRate === 100 &&
-    fluentResults.success;
-
-  if (allPassed) {
-    console.log('✅ All systems operational');
-  } else {
-    console.error('❌ Some tests failed');
-    if (s3Results.summary.successRate < 100) {
-      console.error('S3 issues detected');
-    }
-    if (!fluentResults.success) {
-      console.error('Fluent connection failed');
-    }
-  }
-
-  return allPassed;
-}
-```
-
-### Error Analysis
-
-```typescript
-async function analyzeTestFailures(results: SDKTestResults) {
-  const failedTests = Object.entries(results.tests)
-    .filter(([_, result]) => !result.success)
-    .map(([name, result]) => ({ name, error: result.error }));
-
-  if (failedTests.length === 0) {
-    console.log('All tests passed!');
-    return;
-  }
-
-  console.log(`${failedTests.length} test(s) failed:`);
-
-  failedTests.forEach(({ name, error }) => {
-    console.error(`- ${name}: ${error}`);
-
-    // Categorize errors
-    if (error?.includes('Access Denied')) {
-      console.error('  → Check IAM permissions');
-    } else if (error?.includes('NoSuchBucket')) {
-      console.error('  → Verify bucket exists');
-    } else if (error?.includes('timeout')) {
-      console.error('  → Network or timeout issue');
-    }
-  });
-}
-```
-
-### Compare Implementations
-
-```typescript
-import { S3ComparisonTester } from '@fluentcommerce/fc-connect-sdk';
-
-async function findBestApproach() {
-  const tester = new S3ComparisonTester();
-
-  const results = await tester.compareImplementations(
-    {
-      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-      region: 'us-east-1'
-    },
-    'test-bucket'
-  );
-
-  console.log('Recommendation:', results.recommendation);
-
-  // Detailed analysis
-  const { comparison } = results;
-  console.log('\nComparison Results:');
-  console.log(`- Both passed: ${comparison.bothPassed} operations`);
-  console.log(`- SDK only: ${comparison.onlySdkPassed} operations`);
-  console.log(`- Presigned only: ${comparison.onlyPresignedPassed} operations`);
-  console.log(`- Both failed: ${comparison.bothFailed} operations`);
-
-  // Use recommendation for runtime decision
-  const usePresigned = results.recommendation.includes('presigned');
-  return { usePresigned, results };
-}
-```
-
-## Environment Variables
-
-```bash
-# AWS S3
-AWS_ACCESS_KEY_ID=xxx
-AWS_SECRET_ACCESS_KEY=yyy
-AWS_REGION=us-east-1
-TEST_BUCKET=my-test-bucket
-
-# Fluent Commerce
-FLUENT_BASE_URL=https://api.fluentcommerce.com
-FLUENT_CLIENT_ID=oauth-client-id
-FLUENT_CLIENT_SECRET=oauth-client-secret
-FLUENT_USERNAME=your-username
-FLUENT_PASSWORD=your-password
-FLUENT_RETAILER_ID=1
-```
-
-## Common Test Commands
-
-```bash
-# Run specific tests
-npm test -- s3-sdk-tester
-npm test -- s3-presigned-tester
-npm test -- fluent-connection-tester
-
-# Run all testing utilities
-npm test -- tests/unit/testing/
-
-# With coverage
-npm test -- --coverage tests/unit/testing/
-
-# Integration tests (requires live credentials)
-npm run test:integration:live
-```
-
-## Error Messages Quick Reference
-
-| Error | Meaning | Fix |
-|-------|---------|-----|
-| `AccessDenied` | No S3 permissions | Check IAM policy, verify credentials |
-| `NoSuchBucket` | Bucket doesn't exist | Verify bucket name and region |
-| `401 Unauthorized` | Invalid Fluent credentials | Check OAuth2 client ID/secret |
-| `403 Forbidden` | No API permissions | Check user role and permissions |
-| `ENOTFOUND` | DNS resolution failed | Check network connectivity |
-| `ETIMEDOUT` | Request timeout | Increase timeout or check network |
-| `InvalidAccessKeyId` | Wrong AWS credentials | Verify AWS_ACCESS_KEY_ID |
-| `SignatureDoesNotMatch` | Wrong AWS secret | Verify AWS_SECRET_ACCESS_KEY |
-
-## When to Use Which Tester
-
-| Need | Use | Method |
-|------|-----|--------|
-| Test S3 SDK access | `S3SDKTester` | `testAll(bucket)` |
-| Test presigned URLs | `S3PresignedTester` | `testAll(bucket)` |
-| Compare approaches | `S3ComparisonTester` | `compareImplementations(config, bucket)` |
-| Test Fluent API | `FluentConnectionTester` | `testConnection()` |
-| Health check | `FluentConnectionTester` | `testConnection()` |
-| Integration test | All testers | Use all three |
-
-## Quick Troubleshooting
-
-### 1. Check Environment Variables
-
-```typescript
-const required = [
-  'AWS_ACCESS_KEY_ID',
-  'AWS_SECRET_ACCESS_KEY',
-  'AWS_REGION',
-  'FLUENT_CLIENT_ID',
-  'FLUENT_CLIENT_SECRET'
-];
-
-required.forEach(key => {
-  console.log(`${key}: ${process.env[key] ? '✅' : '}`);
-});
-```
-
-### 2. Test with Minimal Config
-
-```typescript
-// Start simple - just list operation
-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');
-console.log('List operation:', results.tests.list.success ? '✅' : ');
-```
-
-### 3. Test Each Component Separately
-
-```typescript
-// Test S3 first
-const s3Results = await s3Tester.testAll('bucket');
-if (s3Results.summary.successRate < 100) {
-  console.error('Fix S3 issues first');
-  return;
-}
-
-// Then test Fluent
-const fluentResult = await fluentTester.testConnection();
-if (!fluentResult.success) {
-  console.error('Fix Fluent connection');
-  return;
-}
-
-console.log('All systems ready!');
-```
-
-### 4. Enable Verbose Logging
-
-```typescript
-// Create logger
-const logger = {
-  debug: (msg: string, meta?: any) => console.log('[DEBUG]', msg, meta),
-  info: (msg: string, meta?: any) => console.log('[INFO]', msg, meta),
-  warn: (msg: string, meta?: any) => console.warn('[WARN]', msg, meta),
-  error: (msg: string, err?: any, meta?: any) => console.error('[ERROR]', msg, err, meta)
-};
-
-// Use with FluentConnectionTester
-const tester = new FluentConnectionTester(client, {
-  retailerId: '1',
-  logger
-});
-```
-
-## Best Practices Checklist
-
-- [ ] Use test environments (never production)
-- [ ] Set appropriate timeouts for network operations
-- [ ] Always cleanup test data after tests
-- [ ] Check both `success` flag and `errors` array
-- [ ] Test error scenarios (invalid credentials, missing buckets)
-- [ ] Document test results for debugging
-- [ ] Automate tests in CI/CD pipeline
-- [ ] Monitor performance trends over time
-- [ ] Use health checks in production monitoring
-- [ ] Separate unit tests from integration tests
-
----
-
-**See Full Documentation:**
-- [Testing Guide Index](./testing-readme.md)
-- [Module 1: Foundations](../../02-CORE-GUIDES/auto-pagination/modules/auto-pagination-01-foundations.md)
-- [Module 8: API Reference](../../03-PATTERN-GUIDES/error-handling/modules/error-handling-08-api-reference.md)
-- [Examples](./examples/)
+# Testing Utilities Quick Reference
+
+> Complete reference for all SDK testing utilities with accurate APIs
+
+## S3SDKTester
+
+Tests S3 operations using the AWS SDK directly.
+
+### Constructor
+
+```typescript
+import { S3SDKTester } from '@fluentcommerce/fc-connect-sdk';
+
+const tester = new S3SDKTester({
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  region: 'us-east-1',
+  sessionToken?: string  // Optional
+});
+```
+
+### Methods
+
+**Single method - runs all tests:**
+
+```typescript
+// Run all 9 S3 operations tests
+const results = await tester.testAll('test-bucket-name');
+
+// Returns SDKTestResults
+interface SDKTestResults {
+  implementation: 'sdk';
+  timestamp: string;
+  tests: {
+    list: TestResult;
+    write: TestResult;
+    read: TestResult;
+    copy: TestResult;
+    head: TestResult;
+    move: TestResult;
+    delete: TestResult;
+    multipart: TestResult;
+    select: TestResult;
+  };
+  summary: {
+    total: number;
+    passed: number;
+    failed: number;
+    successRate: number;
+    totalDuration: number;
+    averageDuration: number;
+  };
+}
+```
+
+### Complete Example
+
+```typescript
+import { S3SDKTester } from '@fluentcommerce/fc-connect-sdk';
+
+async function testS3Connection() {
+  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('my-test-bucket');
+
+  console.log(`Tests: ${results.summary.passed}/${results.summary.total} passed`);
+  console.log(`Success rate: ${results.summary.successRate}%`);
+
+  // Check individual tests
+  if (!results.tests.write.success) {
+    console.error('Write test failed:', results.tests.write.error);
+  }
+
+  return results.summary.successRate === 100;
+}
+```
+
+## S3PresignedTester
+
+Tests S3 operations using presigned URLs.
+
+### Constructor
+
+```typescript
+import { S3PresignedTester } from '@fluentcommerce/fc-connect-sdk';
+
+const tester = new S3PresignedTester(
+  {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    region: 'us-east-1',
+    sessionToken?: string  // Optional
+  },
+  fetch  // Provide fetch implementation
+);
+```
+
+### Methods
+
+**Single method - runs all tests:**
+
+```typescript
+// Run all 8 presigned URL tests
+const results = await tester.testAll('test-bucket-name');
+
+// Returns PresignedTestResults
+interface PresignedTestResults {
+  implementation: 'presigned';
+  timestamp: string;
+  tests: {
+    list: TestResult;
+    write: TestResult;
+    read: TestResult;
+    copy: TestResult;
+    head: TestResult;
+    move: TestResult;
+    delete: TestResult;
+    advancedFeatures: TestResult;
+  };
+  summary: {
+    total: number;
+    passed: number;
+    failed: number;
+    successRate: number;
+    totalDuration: number;
+    averageDuration: number;
+  };
+}
+```
+
+### Complete Example
+
+```typescript
+import { S3PresignedTester } from '@fluentcommerce/fc-connect-sdk';
+
+async function testPresignedUrls() {
+  const tester = new S3PresignedTester(
+    {
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+      region: 'us-east-1'
+    },
+    globalThis.fetch
+  );
+
+  const results = await tester.testAll('my-test-bucket');
+
+  console.log(`Presigned URL tests: ${results.summary.passed}/${results.summary.total} passed`);
+
+  // Check advanced features
+  if (results.tests.advancedFeatures.success) {
+    console.log('Advanced features supported');
+  }
+
+  return results.summary.successRate === 100;
+}
+```
+
+## S3ComparisonTester
+
+Compares SDK vs Presigned URL approaches.
+
+### Constructor
+
+```typescript
+import { S3ComparisonTester } from '@fluentcommerce/fc-connect-sdk';
+
+// NO PARAMETERS - instantiate empty
+const tester = new S3ComparisonTester();
+```
+
+### Methods
+
+**Single method - compares implementations:**
+
+```typescript
+// Compare SDK vs Presigned approaches
+const comparison = await tester.compareImplementations(
+  {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    region: 'us-east-1'
+  },
+  'test-bucket-name',
+  globalThis.fetch  // Optional custom fetch
+);
+
+// Returns ComparisonResults
+interface ComparisonResults {
+  sdk: SDKTestResults;
+  presigned: PresignedTestResults;
+  comparison: {
+    totalTests: number;
+    sdkPassed: number;
+    presignedPassed: number;
+    bothPassed: number;
+    bothFailed: number;
+    onlySdkPassed: number;
+    onlyPresignedPassed: number;
+  };
+  recommendation: string;
+}
+```
+
+### Complete Example
+
+```typescript
+import { S3ComparisonTester } from '@fluentcommerce/fc-connect-sdk';
+
+async function compareS3Approaches() {
+  const tester = new S3ComparisonTester();
+
+  const results = await tester.compareImplementations(
+    {
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+      region: 'us-east-1'
+    },
+    'my-test-bucket',
+    globalThis.fetch
+  );
+
+  console.log('SDK approach:', results.sdk.summary);
+  console.log('Presigned approach:', results.presigned.summary);
+  console.log('Recommendation:', results.recommendation);
+
+  // Detailed comparison
+  const { comparison } = results;
+  console.log(`Both passed: ${comparison.bothPassed}`);
+  console.log(`Only SDK passed: ${comparison.onlySdkPassed}`);
+  console.log(`Only Presigned passed: ${comparison.onlyPresignedPassed}`);
+
+  return results;
+}
+```
+
+## FluentConnectionTester
+
+Tests Fluent Commerce API connectivity.
+
+### Constructor
+
+```typescript
+import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Create Fluent client using universal factory (recommended)
+const client = await createClient({
+  config: {
+    baseUrl: 'https://api.fluentcommerce.com',
+    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
+  }
+});
+
+// Create tester
+const tester = new FluentConnectionTester(
+  client,
+  {
+    retailerId: '1',
+    testJobId?: string,     // Optional
+    testQuery?: string,     // Optional
+    testEvent?: any,        // Optional
+    testBatch?: any,        // Optional
+    logger?: Logger         // Optional
+  }
+);
+```
+
+### Methods
+
+**Single method - tests connection:**
+
+```typescript
+// Test Fluent API connection
+const result = await tester.testConnection();
+
+// Returns TestResult with connection details
+interface TestResult {
+  success: boolean;
+  message?: string;
+  operation?: string;
+  details?: {
+    userId: string;
+    username: string;
+    userType: string;
+    userStatus: string;
+    retailerId: string;
+    retailerRef: string;
+    retailerName: string;
+    locationId: string;
+    locationRef: string;
+    locationName: string;
+  };
+  errors?: any[];
+  error?: string;
+  timestamp?: string;
+  duration?: number;
+}
+```
+
+### Complete Example
+
+```typescript
+import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
+
+async function testFluentConnection() {
+  // Create client using universal factory (recommended)
+  const client = await createClient({
+    config: {
+      baseUrl: 'https://api.fluentcommerce.com',
+      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!
+    }
+  });
+
+  // Create tester
+  const tester = new FluentConnectionTester(client, {
+    retailerId: process.env.FLUENT_RETAILER_ID!
+  });
+
+  // Test connection
+  const result = await tester.testConnection();
+
+  if (result.success) {
+    console.log('Connected successfully!');
+    console.log('User:', result.details?.username);
+    console.log('Retailer:', result.details?.retailerName);
+    console.log('Location:', result.details?.locationName);
+  } else {
+    console.error('Connection failed:', result.error);
+  }
+
+  return result;
+}
+```
+
+## TestResult Interface
+
+Common interface returned by all test operations:
+
+```typescript
+interface TestResult {
+  success: boolean;        // Overall success/failure
+  message?: string;        // Success message
+  operation?: string;      // Operation name (e.g., 'list', 'write')
+  details?: any;          // Operation-specific details
+  errors?: any[];         // Array of errors (if multiple)
+  error?: string;         // Single error message
+  timestamp?: string;     // ISO timestamp
+  duration?: number;      // Duration in milliseconds
+}
+```
+
+## Common Patterns
+
+### Health Check Endpoint
+
+```typescript
+import { FluentConnectionTester, FluentClient } from '@fluentcommerce/fc-connect-sdk';
+
+async function healthCheck(): Promise<{
+  status: 'healthy' | 'unhealthy';
+  fluent: { connected: boolean; duration?: number };
+  timestamp: string;
+}> {
+  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: '1' });
+
+  const result = await tester.testConnection();
+
+  return {
+    status: result.success ? 'healthy' : 'unhealthy',
+    fluent: {
+      connected: result.success,
+      duration: result.duration
+    },
+    timestamp: new Date().toISOString()
+  };
+}
+```
+
+### Complete Integration Test
+
+```typescript
+import {
+  S3SDKTester,
+  FluentConnectionTester,
+  FluentClient
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function runIntegrationTests() {
+  // Test S3
+  const s3Tester = new S3SDKTester({
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    region: 'us-east-1'
+  });
+
+  const s3Results = await s3Tester.testAll('test-bucket');
+
+  // Test Fluent
+  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 fluentTester = new FluentConnectionTester(client, { retailerId: '1' });
+  const fluentResults = await fluentTester.testConnection();
+
+  // Verify both passed
+  const allPassed =
+    s3Results.summary.successRate === 100 &&
+    fluentResults.success;
+
+  if (allPassed) {
+    console.log('✅ All systems operational');
+  } else {
+    console.error('❌ Some tests failed');
+    if (s3Results.summary.successRate < 100) {
+      console.error('S3 issues detected');
+    }
+    if (!fluentResults.success) {
+      console.error('Fluent connection failed');
+    }
+  }
+
+  return allPassed;
+}
+```
+
+### Error Analysis
+
+```typescript
+async function analyzeTestFailures(results: SDKTestResults) {
+  const failedTests = Object.entries(results.tests)
+    .filter(([_, result]) => !result.success)
+    .map(([name, result]) => ({ name, error: result.error }));
+
+  if (failedTests.length === 0) {
+    console.log('All tests passed!');
+    return;
+  }
+
+  console.log(`${failedTests.length} test(s) failed:`);
+
+  failedTests.forEach(({ name, error }) => {
+    console.error(`- ${name}: ${error}`);
+
+    // Categorize errors
+    if (error?.includes('Access Denied')) {
+      console.error('  → Check IAM permissions');
+    } else if (error?.includes('NoSuchBucket')) {
+      console.error('  → Verify bucket exists');
+    } else if (error?.includes('timeout')) {
+      console.error('  → Network or timeout issue');
+    }
+  });
+}
+```
+
+### Compare Implementations
+
+```typescript
+import { S3ComparisonTester } from '@fluentcommerce/fc-connect-sdk';
+
+async function findBestApproach() {
+  const tester = new S3ComparisonTester();
+
+  const results = await tester.compareImplementations(
+    {
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+      region: 'us-east-1'
+    },
+    'test-bucket'
+  );
+
+  console.log('Recommendation:', results.recommendation);
+
+  // Detailed analysis
+  const { comparison } = results;
+  console.log('\nComparison Results:');
+  console.log(`- Both passed: ${comparison.bothPassed} operations`);
+  console.log(`- SDK only: ${comparison.onlySdkPassed} operations`);
+  console.log(`- Presigned only: ${comparison.onlyPresignedPassed} operations`);
+  console.log(`- Both failed: ${comparison.bothFailed} operations`);
+
+  // Use recommendation for runtime decision
+  const usePresigned = results.recommendation.includes('presigned');
+  return { usePresigned, results };
+}
+```
+
+## Environment Variables
+
+```bash
+# AWS S3
+AWS_ACCESS_KEY_ID=xxx
+AWS_SECRET_ACCESS_KEY=yyy
+AWS_REGION=us-east-1
+TEST_BUCKET=my-test-bucket
+
+# Fluent Commerce
+FLUENT_BASE_URL=https://api.fluentcommerce.com
+FLUENT_CLIENT_ID=oauth-client-id
+FLUENT_CLIENT_SECRET=oauth-client-secret
+FLUENT_USERNAME=your-username
+FLUENT_PASSWORD=your-password
+FLUENT_RETAILER_ID=1
+```
+
+## Common Test Commands
+
+```bash
+# Run specific tests
+npm test -- s3-sdk-tester
+npm test -- s3-presigned-tester
+npm test -- fluent-connection-tester
+
+# Run all testing utilities
+npm test -- tests/unit/testing/
+
+# With coverage
+npm test -- --coverage tests/unit/testing/
+
+# Integration tests (requires live credentials)
+npm run test:integration:live
+```
+
+## Error Messages Quick Reference
+
+| Error | Meaning | Fix |
+|-------|---------|-----|
+| `AccessDenied` | No S3 permissions | Check IAM policy, verify credentials |
+| `NoSuchBucket` | Bucket doesn't exist | Verify bucket name and region |
+| `401 Unauthorized` | Invalid Fluent credentials | Check OAuth2 client ID/secret |
+| `403 Forbidden` | No API permissions | Check user role and permissions |
+| `ENOTFOUND` | DNS resolution failed | Check network connectivity |
+| `ETIMEDOUT` | Request timeout | Increase timeout or check network |
+| `InvalidAccessKeyId` | Wrong AWS credentials | Verify AWS_ACCESS_KEY_ID |
+| `SignatureDoesNotMatch` | Wrong AWS secret | Verify AWS_SECRET_ACCESS_KEY |
+
+## When to Use Which Tester
+
+| Need | Use | Method |
+|------|-----|--------|
+| Test S3 SDK access | `S3SDKTester` | `testAll(bucket)` |
+| Test presigned URLs | `S3PresignedTester` | `testAll(bucket)` |
+| Compare approaches | `S3ComparisonTester` | `compareImplementations(config, bucket)` |
+| Test Fluent API | `FluentConnectionTester` | `testConnection()` |
+| Health check | `FluentConnectionTester` | `testConnection()` |
+| Integration test | All testers | Use all three |
+
+## Quick Troubleshooting
+
+### 1. Check Environment Variables
+
+```typescript
+const required = [
+  'AWS_ACCESS_KEY_ID',
+  'AWS_SECRET_ACCESS_KEY',
+  'AWS_REGION',
+  'FLUENT_CLIENT_ID',
+  'FLUENT_CLIENT_SECRET'
+];
+
+required.forEach(key => {
+  console.log(`${key}: ${process.env[key] ? '✅' : '}`);
+});
+```
+
+### 2. Test with Minimal Config
+
+```typescript
+// Start simple - just list operation
+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');
+console.log('List operation:', results.tests.list.success ? '✅' : ');
+```
+
+### 3. Test Each Component Separately
+
+```typescript
+// Test S3 first
+const s3Results = await s3Tester.testAll('bucket');
+if (s3Results.summary.successRate < 100) {
+  console.error('Fix S3 issues first');
+  return;
+}
+
+// Then test Fluent
+const fluentResult = await fluentTester.testConnection();
+if (!fluentResult.success) {
+  console.error('Fix Fluent connection');
+  return;
+}
+
+console.log('All systems ready!');
+```
+
+### 4. Enable Verbose Logging
+
+```typescript
+// Create logger
+const logger = {
+  debug: (msg: string, meta?: any) => console.log('[DEBUG]', msg, meta),
+  info: (msg: string, meta?: any) => console.log('[INFO]', msg, meta),
+  warn: (msg: string, meta?: any) => console.warn('[WARN]', msg, meta),
+  error: (msg: string, err?: any, meta?: any) => console.error('[ERROR]', msg, err, meta)
+};
+
+// Use with FluentConnectionTester
+const tester = new FluentConnectionTester(client, {
+  retailerId: '1',
+  logger
+});
+```
+
+## Best Practices Checklist
+
+- [ ] Use test environments (never production)
+- [ ] Set appropriate timeouts for network operations
+- [ ] Always cleanup test data after tests
+- [ ] Check both `success` flag and `errors` array
+- [ ] Test error scenarios (invalid credentials, missing buckets)
+- [ ] Document test results for debugging
+- [ ] Automate tests in CI/CD pipeline
+- [ ] Monitor performance trends over time
+- [ ] Use health checks in production monitoring
+- [ ] Separate unit tests from integration tests
+
+---
+
+**See Full Documentation:**
+- [Testing Guide Index](./testing-readme.md)
+- [Module 1: Foundations](../../02-CORE-GUIDES/auto-pagination/modules/auto-pagination-01-foundations.md)
+- [Module 8: API Reference](../../03-PATTERN-GUIDES/error-handling/modules/error-handling-08-api-reference.md)
+- [Examples](./examples/)