@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/04-REFERENCE/testing/modules/04-reference-testing-02-s3-testing.md

@@ -1,599 +1,599 @@
-# Module 2: S3 Testing
-
-**Level:** Beginner
-**Estimated Time:** 30 minutes
-
-## Overview
-
-This module covers the three S3 testing utilities provided by the SDK: `S3SDKTester` for AWS SDK testing, `S3PresignedTester` for presigned URL testing, and `S3ComparisonTester` for comparing both approaches.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Understand how to use S3SDKTester for testing AWS SDK operations
-- ✅ Know how to use S3PresignedTester for testing presigned URL access
-- ✅ Be able to compare both approaches with S3ComparisonTester
-- ✅ Understand when to use each tester
-
-## S3SDKTester
-
-Validates S3 connectivity using AWS SDK credentials (server-side approach).
-
-### Basic Usage
-
-```typescript
-import { S3SDKTester } from '@fluentcommerce/fc-connect-sdk';
-
-// Configure tester
-const tester = new S3SDKTester({
-  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-  region: 'us-east-1'
-});
-
-// Run all tests
-const results = await tester.testAll('test-bucket');
-
-// Check results
-console.log('SDK Tests Summary:');
-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)}%`);
-console.log(`  Total Duration: ${results.summary.totalDuration}ms`);
-
-// Check individual test results
-if (results.tests.list.success) {
-  console.log('✅ List operation passed');
-}
-if (!results.tests.write.success) {
-  console.error('❌ Write operation failed:', results.tests.write.message);
-}
-```
-
-### Constructor
-
-```typescript
-new S3SDKTester(config: S3ServiceConfig)
-```
-
-**Configuration:**
-
-```typescript
-interface S3ServiceConfig {
-  accessKeyId: string;           // AWS access key ID
-  secretAccessKey: string;       // AWS secret access key
-  region: string;                // AWS region (e.g., 'us-east-1')
-  sessionToken?: string;         // Optional for temporary credentials
-}
-```
-
-### Methods
-
-#### testAll(bucket: string)
-
-Runs all S3 tests including SDK-specific features.
-
-```typescript
-const results = await tester.testAll('my-bucket');
-```
-
-**Tests performed:**
-- List objects
-- Write (put object)
-- Read (get object)
-- Copy object
-- Head object
-- Move object
-- Delete object
-- Multipart upload (SDK-only)
-- S3 Select queries (SDK-only)
-
-**Returns:**
-
-```typescript
-interface SDKTestResults {
-  implementation: 'sdk';
-  timestamp: string;
-  tests: Record<string, TestResult>;
-  summary?: {
-    total: number;
-    passed: number;
-    failed: number;
-    successRate: number;
-    totalDuration: number;
-    averageDuration: number;
-  };
-}
-
-interface TestResult {
-  success: boolean;
-  message: string;
-  details?: any;
-  errors?: any[];
-  duration?: number;
-}
-```
-
-## S3PresignedTester
-
-Tests S3 operations using presigned URLs (useful for browser-based or restricted environments).
-
-### Basic Usage
-
-```typescript
-import { S3PresignedTester } from '@fluentcommerce/fc-connect-sdk';
-
-// Configure tester with fetch function
-const tester = new S3PresignedTester(
-  {
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-    region: 'us-east-1'
-  },
-  fetch  // or ctx.fetch in Versori
-);
-
-// Run all tests
-const results = await tester.testAll('test-bucket');
-
-// Check results
-console.log('Presigned Tests Summary:');
-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)}%`);
-
-// Check individual test results
-if (results.tests.read.success) {
-  console.log('✅ Presigned read operation passed');
-  console.log('   Implementation:', results.tests.read.details.implementation);
-}
-```
-
-### Constructor
-
-```typescript
-new S3PresignedTester(config: S3ServiceConfig, fetch: typeof globalThis.fetch)
-```
-
-**Parameters:**
-- `config`: S3 service configuration (same as S3SDKTester)
-- `fetch`: Fetch function (global `fetch` or `ctx.fetch` in Versori)
-
-**Configuration:**
-
-```typescript
-interface S3ServiceConfig {
-  accessKeyId: string;           // AWS access key ID
-  secretAccessKey: string;       // AWS secret access key
-  region: string;                // AWS region (e.g., 'us-east-1')
-  sessionToken?: string;         // Optional for temporary credentials
-}
-```
-
-### Methods
-
-#### testAll(bucket: string)
-
-Runs all S3 tests available with presigned URLs.
-
-```typescript
-const results = await tester.testAll('my-bucket');
-```
-
-**Tests performed:**
-- List objects (via presigned URL)
-- Write (put object via presigned URL)
-- Read (get object via presigned URL)
-- Copy object (via presigned URL)
-- Head object (via presigned URL)
-- Move object (via presigned URL)
-- Delete object (via presigned URL)
-- Advanced features check (validates SDK-only features are unavailable)
-
-**Returns:**
-
-```typescript
-interface PresignedTestResults {
-  implementation: 'presigned';
-  timestamp: string;
-  tests: Record<string, TestResult>;
-  summary?: {
-    total: number;
-    passed: number;
-    failed: number;
-    successRate: number;
-    totalDuration: number;
-    averageDuration: number;
-  };
-}
-```
-
-## S3ComparisonTester
-
-Compares SDK and presigned URL approaches to determine optimal method for your use case.
-
-### Basic Usage
-
-```typescript
-import { S3ComparisonTester } from '@fluentcommerce/fc-connect-sdk';
-
-// No configuration needed in constructor
-const tester = new S3ComparisonTester();
-
-// Compare both implementations
-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',
-  fetch  // Optional custom fetch
-);
-
-// View results
-console.log('Comparison Results:');
-console.log('SDK Implementation:');
-console.log(`  Total Tests: ${comparison.sdk.summary.total}`);
-console.log(`  Passed: ${comparison.sdk.summary.passed}`);
-console.log(`  Duration: ${comparison.duration}ms`);
-
-console.log('\nPresigned Implementation:');
-console.log(`  Total Tests: ${comparison.presigned.summary.total}`);
-console.log(`  Passed: ${comparison.presigned.summary.passed}`);
-
-console.log('\nComparison Summary:');
-console.log(`  Common Operations: ${comparison.summary.commonOperations}`);
-console.log(`  Matching Results: ${comparison.summary.matchingResults}`);
-console.log(`  Match Rate: ${comparison.summary.matchRate.toFixed(2)}%`);
-console.log(`  Avg Performance Ratio: ${comparison.summary.avgPerformanceRatio.toFixed(2)}x`);
-console.log(`  Analysis: ${comparison.summary.performanceAnalysis}`);
-
-// Check for discrepancies
-if (comparison.comparison.discrepancies.length > 0) {
-  console.log('\n⚠️ Discrepancies found:');
-  comparison.comparison.discrepancies.forEach(disc => {
-    console.log(`  - ${disc.operation}: ${disc.issue}`);
-  });
-}
-```
-
-### Constructor
-
-```typescript
-new S3ComparisonTester()
-```
-
-No configuration required - takes config as parameter to methods.
-
-### Methods
-
-#### compareImplementations(config, bucket, fetch?)
-
-Runs tests with both SDK and presigned implementations and compares results.
-
-```typescript
-const results = await tester.compareImplementations(
-  config,
-  'my-bucket',
-  fetch  // Optional
-);
-```
-
-**Parameters:**
-- `config`: S3ServiceConfig (same as tester configs)
-- `testBucket`: Bucket name for testing
-- `customFetch?`: Optional custom fetch function
-
-**Returns:**
-
-```typescript
-interface ComparisonResults {
-  timestamp: string;
-  duration: number;                        // Total comparison duration
-  sdk: SDKTestResults;                    // Full SDK test results
-  presigned: PresignedTestResults;        // Full presigned test results
-  comparison: ComparisonDetails;          // Detailed comparison
-  summary: ComparisonSummary;             // Summary statistics
-}
-
-interface ComparisonSummary {
-  totalOperations: number;
-  commonOperations: number;
-  matchingResults: number;
-  mismatchingResults: number;
-  matchRate: number;
-  discrepancyCount: number;
-  avgPerformanceRatio: number;
-  performanceAnalysis: string;
-}
-```
-
-#### compareSpecificOperation(config, bucket, operation, fetch?)
-
-Compare a single operation between both implementations.
-
-```typescript
-const result = await tester.compareSpecificOperation(
-  config,
-  'my-bucket',
-  'read',  // 'list' | 'read' | 'write' | 'copy' | 'delete'
-  fetch
-);
-
-console.log(`Operation: ${result.operation}`);
-console.log(`SDK Duration: ${result.sdk.duration}ms`);
-console.log(`Presigned Duration: ${result.presigned.duration}ms`);
-console.log(`Performance Ratio: ${result.performanceRatio.toFixed(2)}x`);
-console.log(`Results Match: ${result.matches}`);
-```
-
-**Returns:**
-
-```typescript
-interface OperationComparison {
-  operation: string;
-  sdk: {
-    success: boolean;
-    result?: any;
-    error?: any;
-    duration: number;
-  };
-  presigned: {
-    success: boolean;
-    result?: any;
-    error?: any;
-    duration: number;
-  };
-  matches: boolean;
-  performanceRatio: number;
-}
-```
-
-### Analyzing Comparison Results
-
-```typescript
-function analyzeComparison(comparison: ComparisonResults) {
-  const { summary, comparison: details } = comparison;
-
-  // Check match rate
-  if (summary.matchRate === 100) {
-    console.log('✅ Both implementations produce identical results');
-  } else {
-    console.log(`⚠️ Match rate: ${summary.matchRate.toFixed(2)}%`);
-  }
-
-  // Performance analysis
-  console.log(`\n${summary.performanceAnalysis}`);
-
-  // Check specific operations
-  Object.entries(details.operations).forEach(([op, result]) => {
-    if (result.note) {
-      console.log(`  ${op}: ${result.note}`);
-    } else if (result.matches) {
-      const ratio = result.performanceRatio?.toFixed(2) || 'N/A';
-      console.log(`  ${op}: ✅ Match (presigned ${ratio}x speed)`);
-    } else {
-      console.log(`  ${op}: ❌ Mismatch`);
-    }
-  });
-
-  // Discrepancies
-  if (details.discrepancies.length > 0) {
-    console.log('\n⚠️ Issues found:');
-    details.discrepancies.forEach(d => {
-      console.log(`  - ${d.operation}: ${d.issue}`);
-    });
-  }
-}
-```
-
-## Choosing the Right Approach
-
-### When to Use SDK Approach
-
-✅ **Use S3SDKTester and SDK approach when:**
-- Server-side applications (Node.js, backend services)
-- You have AWS credentials available
-- Need full S3 operation support (list, copy, head, etc.)
-- Building internal tools with IAM permissions
-- Direct S3 access is secure and acceptable
-
-### When to Use Presigned URL Approach
-
-✅ **Use S3PresignedTester and presigned URL approach when:**
-- Client-side applications (browser, mobile)
-- Cannot expose AWS credentials
-- Need temporary, limited access
-- Only need read/write operations
-- Building public-facing applications
-
-### Decision Matrix
-
-| Requirement | SDK Approach | Presigned URL |
-|------------|--------------|---------------|
-| Server-side access | ✅ Optimal | ⚠️ Possible |
-| Client-side access | ❌ Insecure | ✅ Optimal |
-| AWS credentials available | ✅ Required | ✅ Required (backend) |
-| Expose credentials to client | ❌ Never | ✅ Safe (URLs only) |
-| All S3 operations | ✅ Full support | ⚠️ Limited (read/write) |
-| Temporary access | ⚠️ Possible | ✅ Built-in expiry |
-| Performance | ✅ Faster (direct) | ⚠️ Slightly slower |
-
-## Complete Example: Testing Both Approaches
-
-```typescript
-import {
-  S3SDKTester,
-  S3PresignedTester,
-  S3ComparisonTester
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function testS3Connectivity() {
-  const config = {
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-    region: 'us-east-1'
-  };
-
-  const bucket = 'test-bucket';
-
-  // Test 1: SDK approach
-  console.log('Testing SDK approach...');
-  const sdkTester = new S3SDKTester(config);
-  const sdkResults = await sdkTester.testAll(bucket);
-
-  console.log(`SDK: ${sdkResults.summary.passed}/${sdkResults.summary.total} tests passed`);
-  console.log(`  Success Rate: ${sdkResults.summary.successRate.toFixed(2)}%`);
-  console.log(`  Duration: ${sdkResults.summary.totalDuration}ms`);
-
-  // Test 2: Presigned URL approach
-  console.log('\nTesting presigned URL approach...');
-  const presignedTester = new S3PresignedTester(config, fetch);
-  const presignedResults = await presignedTester.testAll(bucket);
-
-  console.log(`Presigned: ${presignedResults.summary.passed}/${presignedResults.summary.total} tests passed`);
-  console.log(`  Success Rate: ${presignedResults.summary.successRate.toFixed(2)}%`);
-  console.log(`  Duration: ${presignedResults.summary.totalDuration}ms`);
-
-  // Test 3: Compare approaches
-  console.log('\nComparing approaches...');
-  const comparisonTester = new S3ComparisonTester();
-  const comparison = await comparisonTester.compareImplementations(
-    config,
-    bucket,
-    fetch
-  );
-
-  console.log('\nComparison Summary:');
-  console.log(`  Match Rate: ${comparison.summary.matchRate.toFixed(2)}%`);
-  console.log(`  Performance Ratio: ${comparison.summary.avgPerformanceRatio.toFixed(2)}x`);
-  console.log(`  ${comparison.summary.performanceAnalysis}`);
-
-  if (comparison.comparison.discrepancies.length > 0) {
-    console.log('\n⚠️ Discrepancies found:');
-    comparison.comparison.discrepancies.forEach(d => {
-      console.log(`  - ${d.operation}: ${d.issue}`);
-    });
-  }
-
-  return {
-    sdk: sdkResults,
-    presigned: presignedResults,
-    comparison
-  };
-}
-
-// Run tests
-testS3Connectivity()
-  .then(results => {
-    console.log('\n✅ All S3 tests completed!');
-
-    // Determine recommendation
-    const sdkSuccess = results.sdk.summary.successRate === 100;
-    const presignedSuccess = results.presigned.summary.successRate === 100;
-
-    if (sdkSuccess && presignedSuccess) {
-      console.log('\n✅ Both implementations working correctly');
-      console.log(results.comparison.summary.performanceAnalysis);
-    } else if (sdkSuccess) {
-      console.log('\n⚠️ SDK approach more reliable');
-    } else if (presignedSuccess) {
-      console.log('\n⚠️ Presigned URL approach more reliable');
-    } else {
-      console.log('\n❌ Both approaches have issues - check configuration');
-    }
-  })
-  .catch(error => {
-    console.error('❌ S3 testing failed:', error);
-    process.exit(1);
-  });
-```
-
-## Key Takeaways
-
-- 🎯 S3SDKTester validates AWS SDK operations (server-side)
-- 🎯 S3PresignedTester validates presigned URL operations (client-side)
-- 🎯 S3ComparisonTester helps you choose the optimal approach
-- 🎯 Use SDK approach for server-side, presigned URLs for client-side
-- 🎯 Always clean up test files after testing
-
-## Practice Exercise
-
-Create a test script that validates S3 connectivity for your project:
-
-```typescript
-import {
-  S3SDKTester,
-  S3PresignedTester,
-  S3ComparisonTester
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function validateS3() {
-  const config = {
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-    region: process.env.AWS_REGION || 'us-east-1'
-  };
-  const bucket = process.env.S3_BUCKET!;
-
-  // Step 1: Test SDK approach
-  console.log('Step 1: Testing SDK approach...');
-  const sdkTester = new S3SDKTester(config);
-  const sdkResults = await sdkTester.testAll(bucket);
-
-  console.log(`SDK Results: ${sdkResults.summary.passed}/${sdkResults.summary.total} passed`);
-
-  // Step 2: Test presigned approach
-  console.log('\nStep 2: Testing presigned approach...');
-  const presignedTester = new S3PresignedTester(config, fetch);
-  const presignedResults = await presignedTester.testAll(bucket);
-
-  console.log(`Presigned Results: ${presignedResults.summary.passed}/${presignedResults.summary.total} passed`);
-
-  // Step 3: Compare if both passed
-  if (sdkResults.summary.successRate === 100 && presignedResults.summary.successRate === 100) {
-    console.log('\nStep 3: Comparing implementations...');
-    const comparisonTester = new S3ComparisonTester();
-    const comparison = await comparisonTester.compareImplementations(config, bucket, fetch);
-
-    console.log(`Match Rate: ${comparison.summary.matchRate.toFixed(2)}%`);
-    console.log(`Performance: ${comparison.summary.performanceAnalysis}`);
-
-    return { success: true, comparison };
-  } else {
-    console.log('\n⚠️ Skipping comparison - not all tests passed');
-    return { success: false };
-  }
-}
-
-validateS3()
-  .then(result => {
-    if (result.success) {
-      console.log('\n✅ S3 validation complete!');
-    } else {
-      console.log('\n❌ S3 validation incomplete - check errors above');
-      process.exit(1);
-    }
-  })
-  .catch(error => {
-    console.error('Validation error:', error);
-    process.exit(1);
-  });
-```
-
-**Challenge:** Extend this to test specific operations only or compare performance across different file sizes.
-
-## Next Steps
-
-Continue to [Module 3: Fluent Testing →](./04-reference-testing-03-fluent-testing.md) to learn about testing Fluent API connectivity.
-
----
-
-**Module Navigation:**
-- **Previous:** [Module 1 - Foundations](../../../02-CORE-GUIDES/auto-pagination/modules/auto-pagination-01-foundations.md)
-- **Current:** Module 2 - S3 Testing
-- **Next:** [Module 3 - Fluent Testing](./04-reference-testing-03-fluent-testing.md)
-- **Back to:** [Testing Guide Index](../testing-readme.md)
+# Module 2: S3 Testing
+
+**Level:** Beginner
+**Estimated Time:** 30 minutes
+
+## Overview
+
+This module covers the three S3 testing utilities provided by the SDK: `S3SDKTester` for AWS SDK testing, `S3PresignedTester` for presigned URL testing, and `S3ComparisonTester` for comparing both approaches.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Understand how to use S3SDKTester for testing AWS SDK operations
+- ✅ Know how to use S3PresignedTester for testing presigned URL access
+- ✅ Be able to compare both approaches with S3ComparisonTester
+- ✅ Understand when to use each tester
+
+## S3SDKTester
+
+Validates S3 connectivity using AWS SDK credentials (server-side approach).
+
+### Basic Usage
+
+```typescript
+import { S3SDKTester } from '@fluentcommerce/fc-connect-sdk';
+
+// Configure tester
+const tester = new S3SDKTester({
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  region: 'us-east-1'
+});
+
+// Run all tests
+const results = await tester.testAll('test-bucket');
+
+// Check results
+console.log('SDK Tests Summary:');
+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)}%`);
+console.log(`  Total Duration: ${results.summary.totalDuration}ms`);
+
+// Check individual test results
+if (results.tests.list.success) {
+  console.log('✅ List operation passed');
+}
+if (!results.tests.write.success) {
+  console.error('❌ Write operation failed:', results.tests.write.message);
+}
+```
+
+### Constructor
+
+```typescript
+new S3SDKTester(config: S3ServiceConfig)
+```
+
+**Configuration:**
+
+```typescript
+interface S3ServiceConfig {
+  accessKeyId: string;           // AWS access key ID
+  secretAccessKey: string;       // AWS secret access key
+  region: string;                // AWS region (e.g., 'us-east-1')
+  sessionToken?: string;         // Optional for temporary credentials
+}
+```
+
+### Methods
+
+#### testAll(bucket: string)
+
+Runs all S3 tests including SDK-specific features.
+
+```typescript
+const results = await tester.testAll('my-bucket');
+```
+
+**Tests performed:**
+- List objects
+- Write (put object)
+- Read (get object)
+- Copy object
+- Head object
+- Move object
+- Delete object
+- Multipart upload (SDK-only)
+- S3 Select queries (SDK-only)
+
+**Returns:**
+
+```typescript
+interface SDKTestResults {
+  implementation: 'sdk';
+  timestamp: string;
+  tests: Record<string, TestResult>;
+  summary?: {
+    total: number;
+    passed: number;
+    failed: number;
+    successRate: number;
+    totalDuration: number;
+    averageDuration: number;
+  };
+}
+
+interface TestResult {
+  success: boolean;
+  message: string;
+  details?: any;
+  errors?: any[];
+  duration?: number;
+}
+```
+
+## S3PresignedTester
+
+Tests S3 operations using presigned URLs (useful for browser-based or restricted environments).
+
+### Basic Usage
+
+```typescript
+import { S3PresignedTester } from '@fluentcommerce/fc-connect-sdk';
+
+// Configure tester with fetch function
+const tester = new S3PresignedTester(
+  {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    region: 'us-east-1'
+  },
+  fetch  // or ctx.fetch in Versori
+);
+
+// Run all tests
+const results = await tester.testAll('test-bucket');
+
+// Check results
+console.log('Presigned Tests Summary:');
+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)}%`);
+
+// Check individual test results
+if (results.tests.read.success) {
+  console.log('✅ Presigned read operation passed');
+  console.log('   Implementation:', results.tests.read.details.implementation);
+}
+```
+
+### Constructor
+
+```typescript
+new S3PresignedTester(config: S3ServiceConfig, fetch: typeof globalThis.fetch)
+```
+
+**Parameters:**
+- `config`: S3 service configuration (same as S3SDKTester)
+- `fetch`: Fetch function (global `fetch` or `ctx.fetch` in Versori)
+
+**Configuration:**
+
+```typescript
+interface S3ServiceConfig {
+  accessKeyId: string;           // AWS access key ID
+  secretAccessKey: string;       // AWS secret access key
+  region: string;                // AWS region (e.g., 'us-east-1')
+  sessionToken?: string;         // Optional for temporary credentials
+}
+```
+
+### Methods
+
+#### testAll(bucket: string)
+
+Runs all S3 tests available with presigned URLs.
+
+```typescript
+const results = await tester.testAll('my-bucket');
+```
+
+**Tests performed:**
+- List objects (via presigned URL)
+- Write (put object via presigned URL)
+- Read (get object via presigned URL)
+- Copy object (via presigned URL)
+- Head object (via presigned URL)
+- Move object (via presigned URL)
+- Delete object (via presigned URL)
+- Advanced features check (validates SDK-only features are unavailable)
+
+**Returns:**
+
+```typescript
+interface PresignedTestResults {
+  implementation: 'presigned';
+  timestamp: string;
+  tests: Record<string, TestResult>;
+  summary?: {
+    total: number;
+    passed: number;
+    failed: number;
+    successRate: number;
+    totalDuration: number;
+    averageDuration: number;
+  };
+}
+```
+
+## S3ComparisonTester
+
+Compares SDK and presigned URL approaches to determine optimal method for your use case.
+
+### Basic Usage
+
+```typescript
+import { S3ComparisonTester } from '@fluentcommerce/fc-connect-sdk';
+
+// No configuration needed in constructor
+const tester = new S3ComparisonTester();
+
+// Compare both implementations
+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',
+  fetch  // Optional custom fetch
+);
+
+// View results
+console.log('Comparison Results:');
+console.log('SDK Implementation:');
+console.log(`  Total Tests: ${comparison.sdk.summary.total}`);
+console.log(`  Passed: ${comparison.sdk.summary.passed}`);
+console.log(`  Duration: ${comparison.duration}ms`);
+
+console.log('\nPresigned Implementation:');
+console.log(`  Total Tests: ${comparison.presigned.summary.total}`);
+console.log(`  Passed: ${comparison.presigned.summary.passed}`);
+
+console.log('\nComparison Summary:');
+console.log(`  Common Operations: ${comparison.summary.commonOperations}`);
+console.log(`  Matching Results: ${comparison.summary.matchingResults}`);
+console.log(`  Match Rate: ${comparison.summary.matchRate.toFixed(2)}%`);
+console.log(`  Avg Performance Ratio: ${comparison.summary.avgPerformanceRatio.toFixed(2)}x`);
+console.log(`  Analysis: ${comparison.summary.performanceAnalysis}`);
+
+// Check for discrepancies
+if (comparison.comparison.discrepancies.length > 0) {
+  console.log('\n⚠️ Discrepancies found:');
+  comparison.comparison.discrepancies.forEach(disc => {
+    console.log(`  - ${disc.operation}: ${disc.issue}`);
+  });
+}
+```
+
+### Constructor
+
+```typescript
+new S3ComparisonTester()
+```
+
+No configuration required - takes config as parameter to methods.
+
+### Methods
+
+#### compareImplementations(config, bucket, fetch?)
+
+Runs tests with both SDK and presigned implementations and compares results.
+
+```typescript
+const results = await tester.compareImplementations(
+  config,
+  'my-bucket',
+  fetch  // Optional
+);
+```
+
+**Parameters:**
+- `config`: S3ServiceConfig (same as tester configs)
+- `testBucket`: Bucket name for testing
+- `customFetch?`: Optional custom fetch function
+
+**Returns:**
+
+```typescript
+interface ComparisonResults {
+  timestamp: string;
+  duration: number;                        // Total comparison duration
+  sdk: SDKTestResults;                    // Full SDK test results
+  presigned: PresignedTestResults;        // Full presigned test results
+  comparison: ComparisonDetails;          // Detailed comparison
+  summary: ComparisonSummary;             // Summary statistics
+}
+
+interface ComparisonSummary {
+  totalOperations: number;
+  commonOperations: number;
+  matchingResults: number;
+  mismatchingResults: number;
+  matchRate: number;
+  discrepancyCount: number;
+  avgPerformanceRatio: number;
+  performanceAnalysis: string;
+}
+```
+
+#### compareSpecificOperation(config, bucket, operation, fetch?)
+
+Compare a single operation between both implementations.
+
+```typescript
+const result = await tester.compareSpecificOperation(
+  config,
+  'my-bucket',
+  'read',  // 'list' | 'read' | 'write' | 'copy' | 'delete'
+  fetch
+);
+
+console.log(`Operation: ${result.operation}`);
+console.log(`SDK Duration: ${result.sdk.duration}ms`);
+console.log(`Presigned Duration: ${result.presigned.duration}ms`);
+console.log(`Performance Ratio: ${result.performanceRatio.toFixed(2)}x`);
+console.log(`Results Match: ${result.matches}`);
+```
+
+**Returns:**
+
+```typescript
+interface OperationComparison {
+  operation: string;
+  sdk: {
+    success: boolean;
+    result?: any;
+    error?: any;
+    duration: number;
+  };
+  presigned: {
+    success: boolean;
+    result?: any;
+    error?: any;
+    duration: number;
+  };
+  matches: boolean;
+  performanceRatio: number;
+}
+```
+
+### Analyzing Comparison Results
+
+```typescript
+function analyzeComparison(comparison: ComparisonResults) {
+  const { summary, comparison: details } = comparison;
+
+  // Check match rate
+  if (summary.matchRate === 100) {
+    console.log('✅ Both implementations produce identical results');
+  } else {
+    console.log(`⚠️ Match rate: ${summary.matchRate.toFixed(2)}%`);
+  }
+
+  // Performance analysis
+  console.log(`\n${summary.performanceAnalysis}`);
+
+  // Check specific operations
+  Object.entries(details.operations).forEach(([op, result]) => {
+    if (result.note) {
+      console.log(`  ${op}: ${result.note}`);
+    } else if (result.matches) {
+      const ratio = result.performanceRatio?.toFixed(2) || 'N/A';
+      console.log(`  ${op}: ✅ Match (presigned ${ratio}x speed)`);
+    } else {
+      console.log(`  ${op}: ❌ Mismatch`);
+    }
+  });
+
+  // Discrepancies
+  if (details.discrepancies.length > 0) {
+    console.log('\n⚠️ Issues found:');
+    details.discrepancies.forEach(d => {
+      console.log(`  - ${d.operation}: ${d.issue}`);
+    });
+  }
+}
+```
+
+## Choosing the Right Approach
+
+### When to Use SDK Approach
+
+✅ **Use S3SDKTester and SDK approach when:**
+- Server-side applications (Node.js, backend services)
+- You have AWS credentials available
+- Need full S3 operation support (list, copy, head, etc.)
+- Building internal tools with IAM permissions
+- Direct S3 access is secure and acceptable
+
+### When to Use Presigned URL Approach
+
+✅ **Use S3PresignedTester and presigned URL approach when:**
+- Client-side applications (browser, mobile)
+- Cannot expose AWS credentials
+- Need temporary, limited access
+- Only need read/write operations
+- Building public-facing applications
+
+### Decision Matrix
+
+| Requirement | SDK Approach | Presigned URL |
+|------------|--------------|---------------|
+| Server-side access | ✅ Optimal | ⚠️ Possible |
+| Client-side access | ❌ Insecure | ✅ Optimal |
+| AWS credentials available | ✅ Required | ✅ Required (backend) |
+| Expose credentials to client | ❌ Never | ✅ Safe (URLs only) |
+| All S3 operations | ✅ Full support | ⚠️ Limited (read/write) |
+| Temporary access | ⚠️ Possible | ✅ Built-in expiry |
+| Performance | ✅ Faster (direct) | ⚠️ Slightly slower |
+
+## Complete Example: Testing Both Approaches
+
+```typescript
+import {
+  S3SDKTester,
+  S3PresignedTester,
+  S3ComparisonTester
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function testS3Connectivity() {
+  const config = {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    region: 'us-east-1'
+  };
+
+  const bucket = 'test-bucket';
+
+  // Test 1: SDK approach
+  console.log('Testing SDK approach...');
+  const sdkTester = new S3SDKTester(config);
+  const sdkResults = await sdkTester.testAll(bucket);
+
+  console.log(`SDK: ${sdkResults.summary.passed}/${sdkResults.summary.total} tests passed`);
+  console.log(`  Success Rate: ${sdkResults.summary.successRate.toFixed(2)}%`);
+  console.log(`  Duration: ${sdkResults.summary.totalDuration}ms`);
+
+  // Test 2: Presigned URL approach
+  console.log('\nTesting presigned URL approach...');
+  const presignedTester = new S3PresignedTester(config, fetch);
+  const presignedResults = await presignedTester.testAll(bucket);
+
+  console.log(`Presigned: ${presignedResults.summary.passed}/${presignedResults.summary.total} tests passed`);
+  console.log(`  Success Rate: ${presignedResults.summary.successRate.toFixed(2)}%`);
+  console.log(`  Duration: ${presignedResults.summary.totalDuration}ms`);
+
+  // Test 3: Compare approaches
+  console.log('\nComparing approaches...');
+  const comparisonTester = new S3ComparisonTester();
+  const comparison = await comparisonTester.compareImplementations(
+    config,
+    bucket,
+    fetch
+  );
+
+  console.log('\nComparison Summary:');
+  console.log(`  Match Rate: ${comparison.summary.matchRate.toFixed(2)}%`);
+  console.log(`  Performance Ratio: ${comparison.summary.avgPerformanceRatio.toFixed(2)}x`);
+  console.log(`  ${comparison.summary.performanceAnalysis}`);
+
+  if (comparison.comparison.discrepancies.length > 0) {
+    console.log('\n⚠️ Discrepancies found:');
+    comparison.comparison.discrepancies.forEach(d => {
+      console.log(`  - ${d.operation}: ${d.issue}`);
+    });
+  }
+
+  return {
+    sdk: sdkResults,
+    presigned: presignedResults,
+    comparison
+  };
+}
+
+// Run tests
+testS3Connectivity()
+  .then(results => {
+    console.log('\n✅ All S3 tests completed!');
+
+    // Determine recommendation
+    const sdkSuccess = results.sdk.summary.successRate === 100;
+    const presignedSuccess = results.presigned.summary.successRate === 100;
+
+    if (sdkSuccess && presignedSuccess) {
+      console.log('\n✅ Both implementations working correctly');
+      console.log(results.comparison.summary.performanceAnalysis);
+    } else if (sdkSuccess) {
+      console.log('\n⚠️ SDK approach more reliable');
+    } else if (presignedSuccess) {
+      console.log('\n⚠️ Presigned URL approach more reliable');
+    } else {
+      console.log('\n❌ Both approaches have issues - check configuration');
+    }
+  })
+  .catch(error => {
+    console.error('❌ S3 testing failed:', error);
+    process.exit(1);
+  });
+```
+
+## Key Takeaways
+
+- 🎯 S3SDKTester validates AWS SDK operations (server-side)
+- 🎯 S3PresignedTester validates presigned URL operations (client-side)
+- 🎯 S3ComparisonTester helps you choose the optimal approach
+- 🎯 Use SDK approach for server-side, presigned URLs for client-side
+- 🎯 Always clean up test files after testing
+
+## Practice Exercise
+
+Create a test script that validates S3 connectivity for your project:
+
+```typescript
+import {
+  S3SDKTester,
+  S3PresignedTester,
+  S3ComparisonTester
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function validateS3() {
+  const config = {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    region: process.env.AWS_REGION || 'us-east-1'
+  };
+  const bucket = process.env.S3_BUCKET!;
+
+  // Step 1: Test SDK approach
+  console.log('Step 1: Testing SDK approach...');
+  const sdkTester = new S3SDKTester(config);
+  const sdkResults = await sdkTester.testAll(bucket);
+
+  console.log(`SDK Results: ${sdkResults.summary.passed}/${sdkResults.summary.total} passed`);
+
+  // Step 2: Test presigned approach
+  console.log('\nStep 2: Testing presigned approach...');
+  const presignedTester = new S3PresignedTester(config, fetch);
+  const presignedResults = await presignedTester.testAll(bucket);
+
+  console.log(`Presigned Results: ${presignedResults.summary.passed}/${presignedResults.summary.total} passed`);
+
+  // Step 3: Compare if both passed
+  if (sdkResults.summary.successRate === 100 && presignedResults.summary.successRate === 100) {
+    console.log('\nStep 3: Comparing implementations...');
+    const comparisonTester = new S3ComparisonTester();
+    const comparison = await comparisonTester.compareImplementations(config, bucket, fetch);
+
+    console.log(`Match Rate: ${comparison.summary.matchRate.toFixed(2)}%`);
+    console.log(`Performance: ${comparison.summary.performanceAnalysis}`);
+
+    return { success: true, comparison };
+  } else {
+    console.log('\n⚠️ Skipping comparison - not all tests passed');
+    return { success: false };
+  }
+}
+
+validateS3()
+  .then(result => {
+    if (result.success) {
+      console.log('\n✅ S3 validation complete!');
+    } else {
+      console.log('\n❌ S3 validation incomplete - check errors above');
+      process.exit(1);
+    }
+  })
+  .catch(error => {
+    console.error('Validation error:', error);
+    process.exit(1);
+  });
+```
+
+**Challenge:** Extend this to test specific operations only or compare performance across different file sizes.
+
+## Next Steps
+
+Continue to [Module 3: Fluent Testing →](./04-reference-testing-03-fluent-testing.md) to learn about testing Fluent API connectivity.
+
+---
+
+**Module Navigation:**
+- **Previous:** [Module 1 - Foundations](../../../02-CORE-GUIDES/auto-pagination/modules/auto-pagination-01-foundations.md)
+- **Current:** Module 2 - S3 Testing
+- **Next:** [Module 3 - Fluent Testing](./04-reference-testing-03-fluent-testing.md)
+- **Back to:** [Testing Guide Index](../testing-readme.md)