@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/04-REFERENCE/testing/testing-readme.md

@@ -1,286 +1,286 @@
-# Testing Learning Path
-
-> **Complete guide to testing utilities in the Fluent Connect SDK**
-> Progressive learning modules with real examples and production-ready patterns
-
-## 📚 What You'll Learn
-
-This guide teaches you how to validate integrations, test connectivity, and ensure reliability using the SDK's comprehensive testing utilities. By the end, you'll understand:
-
-- ✅ How to test S3 connectivity using SDK and presigned URL approaches
-- ✅ How to validate Fluent Commerce API connections
-- ✅ How to compare SDK vs presigned URL performance
-- ✅ How to implement health check endpoints
-- ✅ How to debug and troubleshoot test failures
-- ✅ How to integrate tests into CI/CD pipelines
-
-## 🎯 Learning Path Overview
-
-This guide is organized into **8 progressive modules**. Follow them in order for the best learning experience:
-
-| Module | Topic | Level |
-|--------|-------|-------|
-| [Module 1](../../02-CORE-GUIDES/auto-pagination/modules/auto-pagination-01-foundations.md) | **Foundations** - Overview of testing utilities and test result types | Beginner |
-| [Module 2](./modules/04-reference-testing-02-s3-testing.md) | **S3 Testing** - S3SDKTester, S3PresignedTester, S3ComparisonTester | Beginner |
-| [Module 3](./modules/04-reference-testing-03-fluent-testing.md) | **Fluent Testing** - FluentConnectionTester and health checks | Beginner |
-| [Module 4](./modules/04-reference-testing-04-integration-testing.md) | **Integration Testing** - End-to-end ingestion tests, performance testing | Intermediate |
-| [Module 5](./modules/04-reference-testing-05-debugging.md) | **Debugging** - Verbose logging, error analysis, troubleshooting | Intermediate |
-| [Module 6](./modules/04-reference-testing-06-cicd-integration.md) | **CI/CD Integration** - GitHub Actions, test scripts, automation | Intermediate |
-| [Module 7](./modules/04-reference-testing-07-best-practices.md) | **Best Practices** - Testing strategies, common issues, tips | Intermediate |
-| [Module 8](../../03-PATTERN-GUIDES/error-handling/modules/error-handling-08-api-reference.md) | **API Reference** - Complete API documentation for all testers | Reference |
-
-## 🚀 Quick Navigation
-
-### By Use Case
-
-- **First time testing connectivity?** → Start with [Module 1: Foundations](../../02-CORE-GUIDES/auto-pagination/modules/auto-pagination-01-foundations.md)
-- **Need to test S3 access?** → Jump to [Module 2: S3 Testing](./modules/04-reference-testing-02-s3-testing.md)
-- **Testing Fluent API connection?** → See [Module 3: Fluent Testing](./modules/04-reference-testing-03-fluent-testing.md)
-- **Building integration tests?** → Check [Module 4: Integration Testing](./modules/04-reference-testing-04-integration-testing.md)
-- **Experiencing test failures?** → See [Module 5: Debugging](./modules/04-reference-testing-05-debugging.md)
-- **Want code examples?** → Browse [Examples Directory](./examples/)
-
-### By Testing Scenario
-
-Different testing scenarios require different testers:
-
-| Testing Need | Tester | Complexity | Example |
-|-------------|--------|------------|---------|
-| S3 SDK connectivity | `S3SDKTester` | Simple | [Example](./examples/s3-testing.ts) |
-| S3 presigned URLs | `S3PresignedTester` | Simple | [Example](./examples/s3-testing.ts) |
-| Compare S3 approaches | `S3ComparisonTester` | Medium | [Example](./examples/s3-testing.ts) |
-| Fluent API connectivity | `FluentConnectionTester` | Simple | [Example](./examples/fluent-testing.ts) |
-| Health check endpoint | `FluentConnectionTester` | Medium | [Example](./examples/health-check.ts) |
-| End-to-end ingestion | Multiple testers | Complex | [Example](./examples/integration-test.ts) |
-
-## 📖 Quick Reference
-
-For quick lookups, see:
-- [Quick Reference Cheat Sheet](../../02-CORE-GUIDES/advanced-services/advanced-services-quick-reference.md) - All testers and methods on one page
-- [Common Patterns](./examples/04-REFERENCE-testing-readme.md) - Copy-paste ready snippets
-- [Debugging Guide](./modules/04-reference-testing-05-debugging.md) - Error messages and fixes
-
-## 🎓 Prerequisites
-
-Before starting this guide, you should:
-
-1. ✅ Have the SDK installed: `npm install @fluentcommerce/fc-connect-sdk^0.1.23`
-2. ✅ Have AWS credentials for S3 testing (accessKeyId, secretAccessKey)
-3. ✅ Have Fluent API credentials for API testing (clientId, clientSecret, username, password)
-4. ✅ Be familiar with basic SDK usage (`createClient`, basic operations)
-
-**New to the SDK?** Start with the [Getting Started Guide](../../00-START-HERE/getting-started.md) first.
-
-## 🔍 Key Concepts at a Glance
-
-### What Are Testing Utilities?
-
-The SDK provides specialized testing utilities to validate connectivity and operations:
-
-```typescript
-// ❌ WITHOUT testing utilities: Manual curl/aws cli commands, unclear results
-// $ aws s3 ls s3://my-bucket
-// $ curl -X POST https://api.fluentcommerce.com/graphql ...
-// Hard to automate, inconsistent error handling, no structured results
-
-// ✅ WITH testing utilities: Programmatic, standardized results, easy automation
-import { S3SDKTester, FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// Test S3 connectivity
-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');
-console.log(`S3 Tests: ${s3Results.summary.passed}/${s3Results.summary.total} passed`);
-console.log(`Success rate: ${s3Results.summary.successRate}%`);
-
-// Test Fluent API connectivity
-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: process.env.FLUENT_RETAILER_ID!,
-  logger: console
-});
-
-const fluentResult = await fluentTester.testConnection();
-console.log(`Fluent API: ${fluentResult.success ? '✅ CONNECTED' : '❌ FAILED'}`);
-```
-
-### When to Use Each Tester
-
-| Tester | Use When | Best For |
-|--------|---------|---------|
-| **S3SDKTester** | Testing AWS SDK approach | Node.js/server-side S3 access |
-| **S3PresignedTester** | Testing presigned URL approach | Browser/client-side S3 access |
-| **S3ComparisonTester** | Deciding between approaches | Performance benchmarking |
-| **FluentConnectionTester** | Testing Fluent API | API connectivity, health checks |
-
-### Benefits of Testing Utilities
-
-| Aspect | Manual Testing | SDK Testing Utilities |
-|--------|----------------|---------------------|
-| **Consistency** | Varies by developer | Standardized approach |
-| **Automation** | Difficult | Easy CI/CD integration |
-| **Error Reporting** | Generic errors | Detailed, categorized errors |
-| **Performance Metrics** | Manual timing | Built-in duration tracking |
-| **Result Structure** | Unstructured | Typed TestResult interface |
-| **Debugging** | Manual analysis | Built-in error categorization |
-
-## 🛠️ Complete Example
-
-Here's a real-world example testing both S3 and Fluent connectivity:
-
-```typescript
-import {
-  S3SDKTester,
-  FluentConnectionTester,
-  createClient
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function validateConnectivity() {
-  // Step 1: Test S3 connectivity
-  const s3Tester = new S3SDKTester({
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-    region: process.env.AWS_REGION!
-  });
-
-  console.log('Testing S3 connectivity...');
-  const s3Results = await s3Tester.testAll(process.env.S3_BUCKET!);
-
-  if (s3Results.summary.failed > 0) {
-    console.error(`❌ S3 tests failed: ${s3Results.summary.failed}/${s3Results.summary.total}`);
-    console.error('Failed tests:',
-      Object.entries(s3Results.tests)
-        .filter(([_, result]) => !result.success)
-        .map(([name]) => name)
-    );
-    return false;
-  }
-
-  console.log(`✅ S3 tests passed: ${s3Results.summary.passed}/${s3Results.summary.total}`);
-  console.log(`   Success rate: ${s3Results.summary.successRate.toFixed(1)}%`);
-  console.log(`   Total duration: ${s3Results.summary.totalDuration}ms`);
-  console.log(`   Average duration: ${s3Results.summary.averageDuration.toFixed(0)}ms`);
-
-  // Step 2: Test Fluent API connectivity
-  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: process.env.FLUENT_RETAILER_ID!,
-    logger: console
-  });
-
-  console.log('Testing Fluent API connectivity...');
-  const fluentResult = await fluentTester.testConnection();
-
-  if (!fluentResult.success) {
-    console.error('❌ Fluent tests failed:', fluentResult.error);
-    return false;
-  }
-
-  console.log(`✅ Fluent test passed (${fluentResult.duration}ms)`);
-  console.log(`   User: ${fluentResult.details.username} (${fluentResult.details.userType})`);
-  console.log(`   Retailer: ${fluentResult.details.retailerName} (${fluentResult.details.retailerRef})`);
-  if (fluentResult.details.locationName) {
-    console.log(`   Location: ${fluentResult.details.locationName} (${fluentResult.details.locationRef})`);
-  }
-
-  return true;
-}
-
-// Run validation
-validateConnectivity()
-  .then(success => {
-    if (success) {
-      console.log('🎉 All connectivity tests passed!');
-      process.exit(0);
-    } else {
-      console.error('💥 Connectivity validation failed');
-      process.exit(1);
-    }
-  })
-  .catch(error => {
-    console.error('💥 Unexpected error:', error);
-    process.exit(1);
-  });
-```
-
-**What this does:**
-1. Tests S3 connectivity with 9 operations (list, write, read, copy, head, move, delete, multipart, select)
-2. Tests Fluent API connectivity with the 'me' query
-3. Returns structured results with detailed error information
-4. Provides duration metrics and success rates for monitoring
-
-## 📂 Repository Structure
-
-```
-docs/04-REFERENCE/testing/
-├── readme.md                          # This file - main index
-├── quick-reference.md                 # Cheat sheet for quick lookups
-│
-├── modules/                           # Learning modules
-│   ├── 01-foundations.md              # Overview and test result types
-│   ├── 02-s3-testing.md               # S3 testing utilities
-│   ├── 03-fluent-testing.md           # Fluent API testing utilities
-│   ├── 04-integration-testing.md      # End-to-end tests
-│   ├── 05-debugging.md                # Debugging and troubleshooting
-│   ├── 06-cicd-integration.md         # CI/CD automation
-│   ├── 07-best-practices.md           # Testing best practices
-│   └── 08-api-reference.md            # Complete API docs
-│
-└── examples/                          # Verified code examples
-    ├── readme.md                      # Examples index
-    ├── s3-testing.ts                  # S3 testing examples
-    ├── fluent-testing.ts              # Fluent API testing examples
-    ├── integration-test.ts            # End-to-end test example
-    └── health-check.ts                # Health check endpoint
-```
-
-## 🔗 Related Documentation
-
-- [Getting Started Guide](../../00-START-HERE/getting-started.md) - SDK installation and setup
-- [Data Sources Guide](../../02-CORE-GUIDES/data-sources/) - S3 and SFTP operations
-- [API Reference](../../02-CORE-GUIDES/api-reference/) - Complete SDK API
-- [Error Handling Guide](../../03-PATTERN-GUIDES/error-handling/) - Error handling strategies
-
-## 💡 Tips for Best Results
-
-1. **Test early and often** - Run connectivity tests before starting development
-2. **Use test environments** - Never test against production data
-3. **Clean up test data** - Testers automatically clean up (but verify)
-4. **Monitor performance** - Track test duration trends
-5. **Automate tests** - Include in CI/CD pipeline
-6. **Test error scenarios** - Validate error handling works correctly
-
-## 🚦 Getting Started
-
-Ready to begin? Start with [Module 1: Foundations →](../../02-CORE-GUIDES/auto-pagination/modules/auto-pagination-01-foundations.md)
-
----
-
-**Need Help?**
-- 📖 Browse [Examples](./examples/)
-- 🔍 Check [Debugging Module](./modules/04-reference-testing-05-debugging.md)
-- 🐛 Report issues at GitHub
+# Testing Learning Path
+
+> **Complete guide to testing utilities in the Fluent Connect SDK**
+> Progressive learning modules with real examples and production-ready patterns
+
+## 📚 What You'll Learn
+
+This guide teaches you how to validate integrations, test connectivity, and ensure reliability using the SDK's comprehensive testing utilities. By the end, you'll understand:
+
+- ✅ How to test S3 connectivity using SDK and presigned URL approaches
+- ✅ How to validate Fluent Commerce API connections
+- ✅ How to compare SDK vs presigned URL performance
+- ✅ How to implement health check endpoints
+- ✅ How to debug and troubleshoot test failures
+- ✅ How to integrate tests into CI/CD pipelines
+
+## 🎯 Learning Path Overview
+
+This guide is organized into **8 progressive modules**. Follow them in order for the best learning experience:
+
+| Module | Topic | Level |
+|--------|-------|-------|
+| [Module 1](../../02-CORE-GUIDES/auto-pagination/modules/auto-pagination-01-foundations.md) | **Foundations** - Overview of testing utilities and test result types | Beginner |
+| [Module 2](./modules/04-reference-testing-02-s3-testing.md) | **S3 Testing** - S3SDKTester, S3PresignedTester, S3ComparisonTester | Beginner |
+| [Module 3](./modules/04-reference-testing-03-fluent-testing.md) | **Fluent Testing** - FluentConnectionTester and health checks | Beginner |
+| [Module 4](./modules/04-reference-testing-04-integration-testing.md) | **Integration Testing** - End-to-end ingestion tests, performance testing | Intermediate |
+| [Module 5](./modules/04-reference-testing-05-debugging.md) | **Debugging** - Verbose logging, error analysis, troubleshooting | Intermediate |
+| [Module 6](./modules/04-reference-testing-06-cicd-integration.md) | **CI/CD Integration** - GitHub Actions, test scripts, automation | Intermediate |
+| [Module 7](./modules/04-reference-testing-07-best-practices.md) | **Best Practices** - Testing strategies, common issues, tips | Intermediate |
+| [Module 8](../../03-PATTERN-GUIDES/error-handling/modules/error-handling-08-api-reference.md) | **API Reference** - Complete API documentation for all testers | Reference |
+
+## 🚀 Quick Navigation
+
+### By Use Case
+
+- **First time testing connectivity?** → Start with [Module 1: Foundations](../../02-CORE-GUIDES/auto-pagination/modules/auto-pagination-01-foundations.md)
+- **Need to test S3 access?** → Jump to [Module 2: S3 Testing](./modules/04-reference-testing-02-s3-testing.md)
+- **Testing Fluent API connection?** → See [Module 3: Fluent Testing](./modules/04-reference-testing-03-fluent-testing.md)
+- **Building integration tests?** → Check [Module 4: Integration Testing](./modules/04-reference-testing-04-integration-testing.md)
+- **Experiencing test failures?** → See [Module 5: Debugging](./modules/04-reference-testing-05-debugging.md)
+- **Want code examples?** → Browse [Examples Directory](./examples/)
+
+### By Testing Scenario
+
+Different testing scenarios require different testers:
+
+| Testing Need | Tester | Complexity | Example |
+|-------------|--------|------------|---------|
+| S3 SDK connectivity | `S3SDKTester` | Simple | [Example](./examples/s3-testing.ts) |
+| S3 presigned URLs | `S3PresignedTester` | Simple | [Example](./examples/s3-testing.ts) |
+| Compare S3 approaches | `S3ComparisonTester` | Medium | [Example](./examples/s3-testing.ts) |
+| Fluent API connectivity | `FluentConnectionTester` | Simple | [Example](./examples/fluent-testing.ts) |
+| Health check endpoint | `FluentConnectionTester` | Medium | [Example](./examples/health-check.ts) |
+| End-to-end ingestion | Multiple testers | Complex | [Example](./examples/integration-test.ts) |
+
+## 📖 Quick Reference
+
+For quick lookups, see:
+- [Quick Reference Cheat Sheet](../../02-CORE-GUIDES/advanced-services/advanced-services-quick-reference.md) - All testers and methods on one page
+- [Common Patterns](./examples/04-REFERENCE-testing-readme.md) - Copy-paste ready snippets
+- [Debugging Guide](./modules/04-reference-testing-05-debugging.md) - Error messages and fixes
+
+## 🎓 Prerequisites
+
+Before starting this guide, you should:
+
+1. ✅ Have the SDK installed: `npm install @fluentcommerce/fc-connect-sdk^0.1.23`
+2. ✅ Have AWS credentials for S3 testing (accessKeyId, secretAccessKey)
+3. ✅ Have Fluent API credentials for API testing (clientId, clientSecret, username, password)
+4. ✅ Be familiar with basic SDK usage (`createClient`, basic operations)
+
+**New to the SDK?** Start with the [Getting Started Guide](../../00-START-HERE/getting-started.md) first.
+
+## 🔍 Key Concepts at a Glance
+
+### What Are Testing Utilities?
+
+The SDK provides specialized testing utilities to validate connectivity and operations:
+
+```typescript
+// ❌ WITHOUT testing utilities: Manual curl/aws cli commands, unclear results
+// $ aws s3 ls s3://my-bucket
+// $ curl -X POST https://api.fluentcommerce.com/graphql ...
+// Hard to automate, inconsistent error handling, no structured results
+
+// ✅ WITH testing utilities: Programmatic, standardized results, easy automation
+import { S3SDKTester, FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Test S3 connectivity
+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');
+console.log(`S3 Tests: ${s3Results.summary.passed}/${s3Results.summary.total} passed`);
+console.log(`Success rate: ${s3Results.summary.successRate}%`);
+
+// Test Fluent API connectivity
+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: process.env.FLUENT_RETAILER_ID!,
+  logger: console
+});
+
+const fluentResult = await fluentTester.testConnection();
+console.log(`Fluent API: ${fluentResult.success ? '✅ CONNECTED' : '❌ FAILED'}`);
+```
+
+### When to Use Each Tester
+
+| Tester | Use When | Best For |
+|--------|---------|---------|
+| **S3SDKTester** | Testing AWS SDK approach | Node.js/server-side S3 access |
+| **S3PresignedTester** | Testing presigned URL approach | Browser/client-side S3 access |
+| **S3ComparisonTester** | Deciding between approaches | Performance benchmarking |
+| **FluentConnectionTester** | Testing Fluent API | API connectivity, health checks |
+
+### Benefits of Testing Utilities
+
+| Aspect | Manual Testing | SDK Testing Utilities |
+|--------|----------------|---------------------|
+| **Consistency** | Varies by developer | Standardized approach |
+| **Automation** | Difficult | Easy CI/CD integration |
+| **Error Reporting** | Generic errors | Detailed, categorized errors |
+| **Performance Metrics** | Manual timing | Built-in duration tracking |
+| **Result Structure** | Unstructured | Typed TestResult interface |
+| **Debugging** | Manual analysis | Built-in error categorization |
+
+## 🛠️ Complete Example
+
+Here's a real-world example testing both S3 and Fluent connectivity:
+
+```typescript
+import {
+  S3SDKTester,
+  FluentConnectionTester,
+  createClient
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function validateConnectivity() {
+  // Step 1: Test S3 connectivity
+  const s3Tester = new S3SDKTester({
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    region: process.env.AWS_REGION!
+  });
+
+  console.log('Testing S3 connectivity...');
+  const s3Results = await s3Tester.testAll(process.env.S3_BUCKET!);
+
+  if (s3Results.summary.failed > 0) {
+    console.error(`❌ S3 tests failed: ${s3Results.summary.failed}/${s3Results.summary.total}`);
+    console.error('Failed tests:',
+      Object.entries(s3Results.tests)
+        .filter(([_, result]) => !result.success)
+        .map(([name]) => name)
+    );
+    return false;
+  }
+
+  console.log(`✅ S3 tests passed: ${s3Results.summary.passed}/${s3Results.summary.total}`);
+  console.log(`   Success rate: ${s3Results.summary.successRate.toFixed(1)}%`);
+  console.log(`   Total duration: ${s3Results.summary.totalDuration}ms`);
+  console.log(`   Average duration: ${s3Results.summary.averageDuration.toFixed(0)}ms`);
+
+  // Step 2: Test Fluent API connectivity
+  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: process.env.FLUENT_RETAILER_ID!,
+    logger: console
+  });
+
+  console.log('Testing Fluent API connectivity...');
+  const fluentResult = await fluentTester.testConnection();
+
+  if (!fluentResult.success) {
+    console.error('❌ Fluent tests failed:', fluentResult.error);
+    return false;
+  }
+
+  console.log(`✅ Fluent test passed (${fluentResult.duration}ms)`);
+  console.log(`   User: ${fluentResult.details.username} (${fluentResult.details.userType})`);
+  console.log(`   Retailer: ${fluentResult.details.retailerName} (${fluentResult.details.retailerRef})`);
+  if (fluentResult.details.locationName) {
+    console.log(`   Location: ${fluentResult.details.locationName} (${fluentResult.details.locationRef})`);
+  }
+
+  return true;
+}
+
+// Run validation
+validateConnectivity()
+  .then(success => {
+    if (success) {
+      console.log('🎉 All connectivity tests passed!');
+      process.exit(0);
+    } else {
+      console.error('💥 Connectivity validation failed');
+      process.exit(1);
+    }
+  })
+  .catch(error => {
+    console.error('💥 Unexpected error:', error);
+    process.exit(1);
+  });
+```
+
+**What this does:**
+1. Tests S3 connectivity with 9 operations (list, write, read, copy, head, move, delete, multipart, select)
+2. Tests Fluent API connectivity with the 'me' query
+3. Returns structured results with detailed error information
+4. Provides duration metrics and success rates for monitoring
+
+## 📂 Repository Structure
+
+```
+docs/04-REFERENCE/testing/
+├── readme.md                          # This file - main index
+├── quick-reference.md                 # Cheat sheet for quick lookups
+│
+├── modules/                           # Learning modules
+│   ├── 01-foundations.md              # Overview and test result types
+│   ├── 02-s3-testing.md               # S3 testing utilities
+│   ├── 03-fluent-testing.md           # Fluent API testing utilities
+│   ├── 04-integration-testing.md      # End-to-end tests
+│   ├── 05-debugging.md                # Debugging and troubleshooting
+│   ├── 06-cicd-integration.md         # CI/CD automation
+│   ├── 07-best-practices.md           # Testing best practices
+│   └── 08-api-reference.md            # Complete API docs
+│
+└── examples/                          # Verified code examples
+    ├── readme.md                      # Examples index
+    ├── s3-testing.ts                  # S3 testing examples
+    ├── fluent-testing.ts              # Fluent API testing examples
+    ├── integration-test.ts            # End-to-end test example
+    └── health-check.ts                # Health check endpoint
+```
+
+## 🔗 Related Documentation
+
+- [Getting Started Guide](../../00-START-HERE/getting-started.md) - SDK installation and setup
+- [Data Sources Guide](../../02-CORE-GUIDES/data-sources/) - S3 and SFTP operations
+- [API Reference](../../02-CORE-GUIDES/api-reference/) - Complete SDK API
+- [Error Handling Guide](../../03-PATTERN-GUIDES/error-handling/) - Error handling strategies
+
+## 💡 Tips for Best Results
+
+1. **Test early and often** - Run connectivity tests before starting development
+2. **Use test environments** - Never test against production data
+3. **Clean up test data** - Testers automatically clean up (but verify)
+4. **Monitor performance** - Track test duration trends
+5. **Automate tests** - Include in CI/CD pipeline
+6. **Test error scenarios** - Validate error handling works correctly
+
+## 🚦 Getting Started
+
+Ready to begin? Start with [Module 1: Foundations →](../../02-CORE-GUIDES/auto-pagination/modules/auto-pagination-01-foundations.md)
+
+---
+
+**Need Help?**
+- 📖 Browse [Examples](./examples/)
+- 🔍 Check [Debugging Module](./modules/04-reference-testing-05-debugging.md)
+- 🐛 Report issues at GitHub