Enhance case conversion documentation and testing

- Add comprehensive README documentation with configuration and examples
- Add tests for nested structures, arrays, and mixed data types
- Add test fixture for complex nested GraphQL responses
- Cover edge cases like empty arrays and nil values

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-authored-by: Kirill Platonov <kirillplatonov@users.noreply.github.com>

Author: claude[bot]

README.md

@@ -36,6 +36,119 @@ shop.with_shopify_session do
 end
 ```
 
+## Configuration
+
+### Case Conversion
+
+The gem supports automatic case conversion between Ruby's snake_case conventions and GraphQL's camelCase conventions. This feature is disabled by default to maintain backward compatibility.
+
+To enable case conversion, configure it in your initializer:
+
+```rb
+# config/initializers/shopify_graphql.rb
+ShopifyGraphql.configure do |config|
+  config.convert_case = true
+end
+```
+
+When enabled, the gem will:
+- Convert snake_case variables to camelCase when sending GraphQL requests
+- Convert camelCase response keys to snake_case for easier access in Ruby
+
+<details><summary>Example: Request Variable Conversion</summary>
+
+```rb
+# With convert_case = true
+class GetProduct
+  include ShopifyGraphql::Query
+
+  QUERY = <<~GRAPHQL
+    query($product_id: ID!, $include_variants: Boolean!) {
+      product(id: $product_id) {
+        title
+        variants(first: 10) @include(if: $include_variants) {
+          edges {
+            node {
+              displayName
+            }
+          }
+        }
+      }
+    }
+  GRAPHQL
+
+  def call(product_id:, include_variants: false)
+    # Variables are automatically converted: product_id → productId, include_variants → includeVariants
+    response = execute(QUERY, product_id: product_id, include_variants: include_variants)
+    response.data.product
+  end
+end
+
+# Usage
+product = GetProduct.call(
+  product_id: "gid://shopify/Product/12345",
+  include_variants: true
+)
+```
+
+</details>
+
+<details><summary>Example: Response Key Conversion</summary>
+
+```rb
+# With convert_case = true
+class GetProduct
+  include ShopifyGraphql::Query
+
+  QUERY = <<~GRAPHQL
+    query($id: ID!) {
+      product(id: $id) {
+        title
+        featuredImage {
+          originalSrc
+          altText
+        }
+        variants(first: 5) {
+          edges {
+            node {
+              displayName
+              selectedOptions {
+                name
+                value
+              }
+            }
+          }
+        }
+      }
+    }
+  GRAPHQL
+
+  def call(id:)
+    response = execute(QUERY, id: id)
+    response.data.product
+  end
+end
+
+# Usage - all keys are automatically converted to snake_case
+product = GetProduct.call(id: "gid://shopify/Product/12345")
+
+puts product.title
+puts product.featured_image.original_src    # originalSrc → original_src
+puts product.featured_image.alt_text        # altText → alt_text
+
+product.variants.edges.each do |edge|
+  puts edge.node.display_name               # displayName → display_name
+  
+  edge.node.selected_options.each do |option|
+    puts "#{option.name}: #{option.value}"  # Keys converted automatically
+  end
+end
+```
+
+</details>
+
+**Note:** Case conversion adds a small performance overhead due to key transformation. Enable it only if you prefer Ruby naming conventions over GraphQL's camelCase.
+
 ## Conventions
 
 To better organize your Graphql code use the following conventions:

test/configuration_test.rb

@@ -65,4 +65,219 @@ class ConfigurationTest < ActiveSupport::TestCase
     assert_equal "Graphql Gem Test", response.data.shop.name
     assert_equal "graphql-gem-test.myshopify.com", response.data.shop.myshopifyDomain
   end
+
+  test "nested structures are converted to snake_case when enabled" do
+    ShopifyGraphql.configure { |config| config.convert_case = true }
+
+    query = <<~GRAPHQL
+      query($id: ID!) {
+        product(id: $id) {
+          title
+          featuredImage {
+            originalSrc
+            altText
+            transformedSrc
+          }
+          variants(first: 5) {
+            edges {
+              node {
+                displayName
+                selectedOptions {
+                  name
+                  value
+                }
+                price {
+                  amount
+                  currencyCode
+                }
+              }
+            }
+          }
+          metafields(first: 10) {
+            edges {
+              node {
+                namespace
+                key
+                value
+                createdAt
+                updatedAt
+              }
+            }
+          }
+          seo {
+            title
+            description
+          }
+        }
+      }
+    GRAPHQL
+
+    fake("queries/nested_product.json", query, id: "gid://shopify/Product/12345")
+
+    client = ShopifyGraphql::Client.new
+    response = client.execute(query, id: "gid://shopify/Product/12345")
+    product = response.data.product
+
+    # Test top-level object
+    assert_equal "Complex Product", product.title
+
+    # Test nested object keys converted to snake_case
+    assert_equal "https://example.com/image.jpg", product.featured_image.original_src
+    assert_equal "Product image", product.featured_image.alt_text
+    assert_equal "https://example.com/image_400x400.jpg", product.featured_image.transformed_src
+
+    # Test array of nested objects
+    assert_equal 2, product.variants.edges.length
+    
+    first_variant = product.variants.edges.first.node
+    assert_equal "Small / Red", first_variant.display_name
+    assert_equal "29.99", first_variant.price.amount
+    assert_equal "USD", first_variant.price.currency_code
+
+    # Test deeply nested arrays
+    assert_equal 2, first_variant.selected_options.length
+    assert_equal "Size", first_variant.selected_options.first.name
+    assert_equal "Small", first_variant.selected_options.first.value
+
+    # Test multiple levels of nesting
+    second_variant = product.variants.edges.last.node
+    assert_equal "Large / Blue", second_variant.display_name
+    assert_equal "https://example.com/variant2.jpg", second_variant.image.original_src
+    assert_equal "Blue variant", second_variant.image.alt_text
+
+    # Test metafields array conversion
+    assert_equal 2, product.metafields.edges.length
+    first_metafield = product.metafields.edges.first.node
+    assert_equal "care_instructions", first_metafield.key
+    assert_equal "Machine wash cold", first_metafield.value
+    assert_equal "2024-01-01T00:00:00Z", first_metafield.created_at
+    assert_equal "2024-01-02T00:00:00Z", product.metafields.edges.last.node.updated_at
+
+    # Test simple nested object
+    assert_equal "SEO Title", product.seo.title
+    assert_equal "SEO Description", product.seo.description
+  end
+
+  test "nested structures maintain camelCase when convert_case is disabled" do
+    ShopifyGraphql.configure { |config| config.convert_case = false }
+
+    query = <<~GRAPHQL
+      query($id: ID!) {
+        product(id: $id) {
+          title
+          featuredImage {
+            originalSrc
+            altText
+          }
+          variants(first: 5) {
+            edges {
+              node {
+                displayName
+                selectedOptions {
+                  name
+                  value
+                }
+              }
+            }
+          }
+        }
+      }
+    GRAPHQL
+
+    fake("queries/nested_product.json", query, id: "gid://shopify/Product/12345")
+
+    client = ShopifyGraphql::Client.new
+    response = client.execute(query, id: "gid://shopify/Product/12345")
+    product = response.data.product
+
+    # Keys should maintain original camelCase
+    assert_equal "https://example.com/image.jpg", product.featuredImage.originalSrc
+    assert_equal "Product image", product.featuredImage.altText
+    assert_equal "Small / Red", product.variants.edges.first.node.displayName
+    assert_equal "Size", product.variants.edges.first.node.selectedOptions.first.name
+  end
+
+  test "empty arrays and nil values handled correctly with case conversion" do
+    ShopifyGraphql.configure { |config| config.convert_case = true }
+
+    # Create a fixture with empty/nil values
+    empty_response = {
+      data: {
+        product: {
+          title: "Empty Product",
+          featuredImage: nil,
+          variants: {
+            edges: []
+          },
+          metafields: {
+            edges: []
+          }
+        }
+      }
+    }
+
+    query = "{ product { title featuredImage variants { edges } metafields { edges } } }"
+    stub_request(:post, "https://test-shop.myshopify.com/admin/api/2024-07/graphql.json")
+      .with(body: { query: query, variables: {} })
+      .to_return(body: empty_response.to_json)
+
+    client = ShopifyGraphql::Client.new
+    response = client.execute(query)
+    product = response.data.product
+
+    assert_equal "Empty Product", product.title
+    assert_nil product.featured_image
+    assert_equal [], product.variants.edges
+    assert_equal [], product.metafields.edges
+  end
+
+  test "mixed data types preserved with case conversion" do
+    ShopifyGraphql.configure { |config| config.convert_case = true }
+
+    mixed_response = {
+      data: {
+        product: {
+          title: "Mixed Product",
+          isActive: true,
+          priceRange: {
+            minVariantPrice: {
+              amount: "10.50",
+              currencyCode: "USD"
+            },
+            maxVariantPrice: {
+              amount: "25.99",  
+              currencyCode: "USD"
+            }
+          },
+          tags: ["summer", "sale", "new-arrival"],
+          productType: "Clothing",
+          totalInventory: 100
+        }
+      }
+    }
+
+    query = "{ product { title isActive priceRange { minVariantPrice { amount currencyCode } maxVariantPrice { amount currencyCode } } tags productType totalInventory } }"
+    stub_request(:post, "https://test-shop.myshopify.com/admin/api/2024-07/graphql.json")
+      .with(body: { query: query, variables: {} })
+      .to_return(body: mixed_response.to_json)
+
+    client = ShopifyGraphql::Client.new
+    response = client.execute(query)
+    product = response.data.product
+
+    # Boolean preserved
+    assert_equal true, product.is_active
+    
+    # Nested objects converted
+    assert_equal "10.50", product.price_range.min_variant_price.amount
+    assert_equal "USD", product.price_range.min_variant_price.currency_code
+    assert_equal "25.99", product.price_range.max_variant_price.amount
+    
+    # Arrays preserved
+    assert_equal ["summer", "sale", "new-arrival"], product.tags
+    
+    # String and numbers preserved  
+    assert_equal "Clothing", product.product_type
+    assert_equal 100, product.total_inventory
+  end
 end