Add comprehensive integration tests using faraday-live approach

[iMacTia]

Add Comprehensive Integration Tests (Prerequisite)

Phase: Prerequisite
Release Target: None (must complete before refactoring begins)
Tracking Issue: #1647
RFC: docs/options-detach-plan.md

Overview

Before we begin the Options architecture refactoring, we need a comprehensive integration test suite that exercises all Options classes in real HTTP scenarios. This ensures we can validate backward compatibility at each refactoring step.

Background

The faraday-live repository contains an approach for testing Faraday against real HTTP endpoints. We should build upon this work to create integration tests that can be run in CI.

Tasks

Research Phase

• Review the faraday-live repository and approach
• Identify what aspects can be integrated into Faraday's CI pipeline
• Determine test endpoints/services to use (consider httpbin.org or similar)
• Evaluate if we need to run local test servers or use external services

Implementation Phase

• Create spec/integration/ directory structure
• Implement integration tests covering:
  • ProxyOptions (proxy configuration in real requests)
  • RequestOptions (timeouts, params_encoder, boundary in real scenarios)
  • SSLOptions (SSL verification, certificates, client certs)
  • ConnectionOptions (headers, params, builder usage)
  • Env (middleware interaction, request/response cycle)
• Set up CI configuration to run integration tests
• Add documentation for running integration tests locally
• Ensure tests can detect breaking changes in Options behavior

Coverage Requirements

Each Options class should have integration tests that:

1. Exercise all major configuration options
2. Test nested options (e.g., ConnectionOptions with nested request/ssl)
3. Validate deep merging behavior in real request scenarios
4. Test coercion of raw hashes into Options objects
5. Verify middleware can access and modify options correctly

Acceptance Criteria

• Integration test suite runs in CI
• All Options classes have comprehensive real-world test coverage
• Tests catch regressions in Options behavior
• Documentation exists for running tests locally
• Test suite passes consistently

Files to Create/Modify

• spec/integration/ (new directory)
• spec/integration/proxy_options_integration_spec.rb (new)
• spec/integration/request_options_integration_spec.rb (new)
• spec/integration/ssl_options_integration_spec.rb (new)
• spec/integration/connection_options_integration_spec.rb (new)
• spec/integration/env_integration_spec.rb (new)
• .github/workflows/ci.yml (update to run integration tests)
• README.md or CONTRIBUTING.md (document integration test approach)

Dependencies

None - this is the prerequisite for all other work.

Notes

• Consider using Docker for consistent test environments
• May need to handle flaky network tests gracefully
• Should balance thoroughness with CI runtime
• Integration tests complement (not replace) existing unit tests