Add comprehensive documentation to test suites with detailed comments and README files

src/test-suites/complex-entity-call/README.md

@@ -0,0 +1,89 @@
+# Complex Entity Call
+
+## Overview
+This test suite validates the most sophisticated entity resolution scenarios in Apollo Federation, testing complex multi-entity graphs with circular references, nested relationships, and intricate data dependencies that represent real-world federated architectures.
+
+## Apollo Federation Concepts Tested
+- **Complex entity graphs**: Multiple entities with interconnected relationships
+- **Circular references**: Entities that reference back to themselves or each other
+- **Nested entity resolution**: Multi-level entity resolution chains
+- **Object wrapper patterns**: Using object types to wrap scalar values
+- **Multi-subgraph coordination**: Coordinating data across multiple federated subgraphs
+- **Query planning optimization**: Efficient resolution of complex entity graphs
+
+## Test Scenario
+The test involves a sophisticated e-commerce data model:
+
+1. **Product Entity**:
+   - Has `id`, `pid` fields
+   - Contains a `price` object (not scalar)
+   - References a `category` entity
+
+2. **Category Entity**:
+   - Has `id`, `tag` fields  
+   - Contains a `mainProduct` reference back to Product (circular)
+
+3. **Price Object**:
+   - Wraps the actual price value in an object structure
+   - Demonstrates object-type field resolution
+
+4. **TopProducts Query Result**:
+   - Returns products array with complex nested data
+   - Includes `selected` and `first` product references
+   - Demonstrates multiple access patterns to the same entity types
+
+## Test Case
+
+### Complex Multi-Entity Resolution with Circular References
+The single test validates an extremely complex query that:
+- Fetches an array of products with nested category and price data
+- Resolves circular references (Product → Category → mainProduct → Product)
+- Handles object-wrapped scalar values (price.price)
+- Resolves additional product references (selected, first)
+- Coordinates data from multiple subgraphs seamlessly
+
+## What's Being Tested
+
+### Advanced Entity Patterns
+1. **Circular Reference Handling**: Properly resolving entities that reference each other
+2. **Object Type Resolution**: Resolving complex object types, not just scalars
+3. **Multi-Path Access**: Accessing the same entity types through different query paths
+
+### Performance and Optimization
+1. **Query Planning**: Efficient planning for complex, nested entity graphs
+2. **Deduplication**: Avoiding duplicate entity resolutions when the same entities are accessed multiple times
+3. **Batching**: Efficiently batching entity resolution requests
+
+### Real-World Complexity
+1. **Production Patterns**: Testing patterns commonly found in production systems
+2. **Data Relationships**: Complex business relationships between entities
+3. **Scalability**: Ensuring federation scales to complex data models
+
+## Why This Matters
+Complex entity resolution is critical for:
+- **Real-World Applications**: Production systems often have sophisticated entity relationships
+- **Performance**: Complex queries need to be resolved efficiently
+- **Data Integrity**: Ensuring circular references don't cause infinite loops
+- **Developer Experience**: Complex patterns should work intuitively
+
+## Common Real-World Scenarios
+This pattern represents scenarios like:
+- **E-commerce**: Products with categories that have featured products
+- **Social Networks**: Users with friends who have mutual connections
+- **Content Management**: Articles with authors who have featured articles
+- **Organizational Charts**: Employees with managers who have direct reports
+
+## Implementation Challenges
+Gateways must handle:
+- **Cycle Detection**: Preventing infinite loops in circular references
+- **Query Optimization**: Minimizing round trips for complex entity graphs
+- **Memory Management**: Efficiently handling large, interconnected entity graphs
+- **Error Propagation**: Gracefully handling failures in complex resolution chains
+
+## Performance Considerations
+- **Entity Deduplication**: Same entities accessed multiple times should be resolved once
+- **Batching Strategies**: Related entities should be resolved in batches when possible
+- **Query Planning**: Complex queries need sophisticated planning for optimal execution
+- **Caching**: Entity resolution results should be cached to avoid redundant work
+
+This test ensures that federated gateways can handle the most complex entity resolution scenarios that production applications require, validating both correctness and performance of sophisticated federation patterns.

src/test-suites/complex-entity-call/test.ts

@@ -1,6 +1,14 @@
 import { createTest } from "../../testkit.js";
 
 export default [
+  // Test complex multi-entity resolution with nested relationships
+  // Verifies that complex entity graphs can be resolved across multiple subgraphs
+  // - topProducts query involves multiple entity types: Product, Category, Price
+  // - Tests circular relationships: Category -> mainProduct -> Category
+  // - Validates that nested entity resolution works correctly
+  // - price field uses object wrapper pattern
+  // - category.mainProduct creates a circular reference back to Product
+  // This represents real-world complex data relationships in federated systems
   createTest(
     /* GraphQL */ `
       query {

src/test-suites/fed1-external-extends-resolvable/README.md

@@ -0,0 +1,65 @@
+# Fed1 External Extends Resolvable
+
+## Overview
+This test suite validates compatibility with Apollo Federation v1 syntax, specifically testing the combination of `@external` and `@extends` directives that were used in Federation v1 to extend types across subgraphs.
+
+## Apollo Federation Concepts Tested
+- **Federation v1 compatibility**: Support for legacy Federation v1 directive syntax
+- **@extends directive**: Federation v1 method for extending types defined in other subgraphs
+- **@external directive**: Marking fields as owned by other subgraphs (same in v1 and v2)
+- **Entity resolution**: How v1-style type extensions work with entity resolution
+- **Migration support**: Ensuring v1 schemas can work with modern gateways
+
+## Test Scenario
+The test involves a Product entity that is distributed across subgraphs using Federation v1 patterns:
+
+1. **Base Product Definition**: One subgraph defines the core Product type
+2. **Product Extension**: Another subgraph extends the Product type using `@extends`
+3. **Field Dependencies**: Extended fields depend on `@external` fields from the base definition
+
+## Test Case
+
+### Federation v1 Type Extension Resolution
+- Tests that a Product entity can be successfully resolved across multiple subgraphs
+- Verifies that `@extends` directive correctly extends types from other subgraphs
+- Validates that `@external` fields are properly used for entity resolution
+- Ensures all fields (id, pid, price, upc, name) are correctly resolved from their respective subgraphs
+
+## What's Being Tested
+
+### Legacy Syntax Support
+1. **@extends Directive**: The Federation v1 syntax for type extension still works
+2. **@external Fields**: v1-style external field declarations are properly handled
+3. **Entity Resolution**: v1 extension patterns work with modern entity resolution
+
+### Migration Compatibility
+1. **Schema Evolution**: v1 schemas can be gradually migrated to v2 without breaking
+2. **Gateway Support**: Modern gateways support legacy Federation v1 syntax
+3. **Interoperability**: v1 and v2 syntax can potentially coexist in the same federation
+
+### Functional Equivalence
+1. **Feature Parity**: v1 extension patterns provide the same functionality as v2
+2. **Resolution Consistency**: Entity resolution works the same way regardless of syntax version
+3. **Performance**: No performance degradation when using v1 syntax
+
+## Why This Matters
+Federation v1 compatibility is important for:
+- **Migration Paths**: Organizations can upgrade gateways without rewriting schemas
+- **Legacy Support**: Existing Federation v1 deployments continue to work
+- **Gradual Adoption**: Teams can migrate to v2 syntax incrementally
+- **Investment Protection**: Existing Federation v1 investments remain valuable
+
+## Federation v1 vs v2 Differences
+- **v1**: Uses `@extends` to extend types defined in other subgraphs
+- **v2**: Uses `@key` directives and type redefinition to achieve the same result
+- **v1**: Requires explicit `@extends` for any type extension
+- **v2**: More flexible syntax with better composition capabilities
+
+## Migration Considerations
+When migrating from v1 to v2:
+1. Replace `@extends` with `@key` directives on redefined types
+2. Update import statements to use v2 directive URLs
+3. Consider using v2-specific features like `@shareable` and `@override`
+4. Test thoroughly to ensure functional equivalence
+
+This test ensures that organizations using Federation v1 can confidently upgrade their gateway infrastructure while maintaining their existing schema patterns.

src/test-suites/fed1-external-extends-resolvable/test.ts

@@ -1,6 +1,12 @@
 import { createTest } from "../../testkit.js";
 
 export default [
+  // Test Federation v1 @external and @extends directives working together
+  // Verifies that a type can be extended using @extends and resolve fields
+  // that depend on @external fields from the original definition
+  // - productInA query returns a Product that spans multiple subgraphs
+  // - Tests that Federation v1 patterns still work correctly
+  // - Validates that @external fields can be used for entity resolution
   createTest(
     /* GraphQL */ `
       query {

src/test-suites/fed2-external-extends/README.md

@@ -0,0 +1,82 @@
+# Fed2 External Extends
+
+## Overview  
+This test suite validates Apollo Federation v2 syntax and patterns, specifically testing the modern approach to type extension and external field handling that replaced Federation v1's `@extends` directive.
+
+## Apollo Federation Concepts Tested
+- **Federation v2 syntax**: Modern approach to type extension using `@key` directives
+- **@external directive**: v2 usage of external fields (same concept as v1 but improved syntax)
+- **@provides directive**: v2 optimization for providing external fields
+- **Entity redefinition**: v2 pattern of redefining types instead of extending them
+- **Type composition**: How v2 composes types across subgraphs
+
+## Test Scenario
+The test demonstrates Federation v2 patterns for user entity management:
+
+1. **User Entity Distribution**: User type is defined across multiple subgraphs using v2 patterns
+2. **External Field Handling**: Fields like `rid` are marked as external and properly resolved
+3. **Provides Optimization**: One subgraph uses `@provides` to optimize field resolution
+4. **Modern Syntax**: Uses v2 directive imports and patterns throughout
+
+## Test Cases
+
+### 1. Multi-Query Entity Resolution
+- Tests multiple user queries in a single request
+- Verifies that different entry points (randomUser, userById) work correctly
+- Validates that entity resolution works with v2 `@key` patterns
+
+### 2. External Field Resolution
+- Tests that `@external` fields can be properly resolved in v2
+- Verifies that `rid` field (marked as external) is correctly fetched
+- Ensures v2 external field patterns work efficiently
+
+### 3. Combined Field Resolution
+- Tests resolving both local and external fields together
+- Verifies that v2 entity composition works for complex field sets
+- Ensures optimal query planning for mixed field types
+
+### 4. Provides Directive Optimization
+- Tests the `@provides` directive functionality in v2
+- Verifies that provided fields reduce necessary subgraph calls
+- Validates that v2 provides patterns work correctly
+
+## What's Being Tested
+
+### Federation v2 Features
+1. **Modern Syntax**: v2 directive syntax and import patterns
+2. **Type Redefinition**: v2 approach to extending types without `@extends`
+3. **Improved Composition**: Better type composition capabilities in v2
+
+### Performance Optimizations
+1. **@provides Usage**: Reducing round trips through field provision
+2. **Query Planning**: Efficient query planning with v2 patterns
+3. **Entity Resolution**: Optimized entity resolution strategies
+
+### Syntax Evolution
+1. **v1 to v2 Migration**: How v2 improves upon v1 patterns
+2. **Directive Improvements**: Enhanced directive capabilities in v2
+3. **Schema Composition**: Better schema merging in v2
+
+## Why This Matters
+Federation v2 is important because it:
+- **Improved Developer Experience**: Cleaner, more intuitive syntax
+- **Better Performance**: More optimization opportunities
+- **Enhanced Features**: New directives like `@shareable`, `@override`, `@inaccessible`
+- **Future-Proofing**: Foundation for future federation enhancements
+
+## Federation v2 Advantages
+Compared to v1, Federation v2 offers:
+- **No @extends Required**: Types can be redefined directly with `@key`
+- **Better Composition**: More flexible type composition patterns
+- **New Directives**: Additional directives for advanced use cases
+- **Improved Validation**: Better schema validation and error reporting
+- **Performance**: Better query planning and execution
+
+## Migration Considerations
+When migrating from v1 to v2:
+1. **Update Imports**: Change to v2 directive URLs
+2. **Replace @extends**: Use `@key` on redefined types instead
+3. **New Features**: Consider using new v2-specific directives
+4. **Testing**: Ensure functional equivalence after migration
+
+This test validates that modern federation gateways properly support Federation v2 syntax and can efficiently execute v2-style federated schemas.

src/test-suites/fed2-external-extends/test.ts

@@ -1,6 +1,11 @@
 import { createTest } from "../../testkit.js";
 
 export default [
+  // Test Federation v2 type extension and entity resolution patterns  
+  // Verifies that Federation v2 syntax works correctly for extending types
+  // - Multiple queries test different aspects of v2 entity resolution
+  // - userById query tests entity resolution with multiple fields
+  // - Tests that v2 @key directive and type redefinition work properly
   createTest(
     /* GraphQL */ `
       query {
@@ -29,6 +34,10 @@ export default [
       },
     },
   ),
+  // Test entity resolution with Federation v2 external field patterns
+  // Verifies that external fields in v2 can be properly resolved
+  // - rid field demonstrates v2 external field handling
+  // - Tests that @external directive works with v2 syntax
   createTest(
     /* GraphQL */ `
       query {
@@ -47,6 +56,10 @@ export default [
       },
     },
   ),
+  // Test complex field resolution combining v2 patterns
+  // Verifies that multiple fields can be resolved together in v2
+  // - Combines both local and external fields in single query
+  // - Tests efficiency of v2 entity resolution patterns
   createTest(
     /* GraphQL */ `
       query {
@@ -67,6 +80,11 @@ export default [
       },
     },
   ),
+  // Test Federation v2 provides directive functionality
+  // Verifies that @provides works correctly with v2 syntax
+  // - providedRandomUser query uses @provides optimization
+  // - Tests that v2 @provides directive reduces round trips
+  // - Validates that provided fields are correctly included
   createTest(
     /* GraphQL */ `
       query {

src/test-suites/include-skip/README.md

@@ -0,0 +1,72 @@
+# Include Skip
+
+## Overview
+This test suite validates that the standard GraphQL `@include` and `@skip` directives work correctly in Apollo Federation, ensuring that conditional field inclusion and exclusion behave as expected in federated queries.
+
+## Apollo Federation Concepts Tested
+- **@include directive**: Conditionally including fields based on variable values
+- **@skip directive**: Conditionally excluding fields based on variable values
+- **Query variable handling**: How federated gateways process GraphQL variables
+- **Conditional field resolution**: Ensuring resolvers are only called for included fields
+- **Query optimization**: Skipping unnecessary field resolution in federated environments
+
+## Test Scenario
+The test involves a Product entity with various fields that can be conditionally included or excluded:
+
+1. **Standard Fields**: Always present fields like `price`
+2. **Conditional Fields**: Fields controlled by `@include` and `@skip` directives
+3. **Variable Control**: Using GraphQL variables to control directive behavior
+
+## Test Cases
+
+### 1. @include Directive with False Condition
+- Tests that fields with `@include(if: false)` are completely omitted from the response
+- Verifies that the gateway doesn't call resolvers for excluded fields
+- Ensures query optimization by avoiding unnecessary field resolution
+
+### 2. @skip Directive with True Condition  
+- Tests that fields with `@skip(if: true)` are completely omitted from the response
+- Verifies that skipped fields don't appear in the final result
+- Validates that the gateway respects skip conditions during query execution
+
+### 3. @include Directive with True Condition
+- Tests that fields with `@include(if: true)` are included in the response
+- Verifies that included fields are properly resolved and return their values
+- Ensures that conditional inclusion works correctly when the condition is met
+
+### 4. @skip Directive with False Condition
+- Tests that fields with `@skip(if: false)` are included in the response  
+- Verifies that non-skipped fields are properly resolved and return their values
+- Validates that skip directives only exclude fields when the condition is true
+
+## What's Being Tested
+
+### Directive Processing
+1. **Condition Evaluation**: The gateway correctly evaluates boolean conditions for directives
+2. **Field Filtering**: Fields are properly included or excluded based on directive conditions
+3. **Variable Resolution**: GraphQL variables are correctly passed to and evaluated by directives
+
+### Federation Integration
+1. **Cross-Subgraph Directives**: `@include` and `@skip` work correctly across federated subgraphs
+2. **Query Planning**: The gateway optimizes query plans by excluding skipped fields
+3. **Resolver Optimization**: Resolvers are not called for fields that will be excluded
+
+### Standard Compliance
+1. **GraphQL Specification**: `@include` and `@skip` behave according to GraphQL standards
+2. **Variable Handling**: Default values and variable passing work correctly
+3. **Response Format**: Conditional fields are properly omitted from responses
+
+## Why This Matters
+Conditional field directives are important for:
+- **Performance Optimization**: Avoiding unnecessary data fetching and computation
+- **Dynamic UIs**: Frontend applications that conditionally render based on user state
+- **API Efficiency**: Reducing payload size by excluding unneeded data
+- **Bandwidth Optimization**: Especially important for mobile applications
+
+## Implementation Notes
+These directives should be processed during query planning, not during execution:
+- **Query Planning**: The gateway should exclude skipped fields from subgraph queries
+- **Network Optimization**: Subgraphs shouldn't be asked to resolve excluded fields
+- **Response Shaping**: Final response should naturally omit conditional fields
+
+This test ensures that federated gateways maintain the same conditional field behavior as monolithic GraphQL servers, preserving client expectations and optimization opportunities.