Build an iOS IPv6-only Compatibility Gate on a Cloud Mac

When a mobile network, enterprise Wi-Fi, or carrier test environment switches to IPv6-only, the most common failures are not complete outages. A user may sign in successfully but fail to upload an image; the first request may work while a reconnect times out; or a legacy endpoint may still have an IPv4 address hard-coded in its configuration. A cloud Mac can turn these intermittent issues into a consistent gate: every merge scans for address literals, verifies DNS64 resolution conditions, runs network tests, and archives diagnostic evidence when a failure occurs.

Define the Gate Boundaries First

IPv6-only compatibility does not mean the server must publish only AAAA records. As long as the test network provides DNS64/NAT64, a client that uses domain names and relies on the system resolver can still reach an IPv4-only service. The real risk is a client that bypasses the system resolution path—for example, by caching a resolved IPv4 address, forcing AF_INET, or placing an address such as 192.0.2.10 in application configuration.

A practical gate should have three layers:

Do not treat a successful ping as application acceptance. The app actually uses HTTPS, WebSocket, or file uploads, and differences in request paths, timeout policies, and connection reuse can produce different results.

Scan the Repository for IPv4 Assumptions

Start with a conservative scan in the CI workspace. The expression below only identifies candidates. Not every match should be treated as a defect, because test fixtures, documentation, and loopback addresses may be legitimate.

set -euo pipefail

mkdir -p artifacts/ipv6
rg -n \
  --glob '*.{swift,m,mm,h,plist,json,yaml,yml,xcconfig}' \
  '([0-9]{1,3}\.){3}[0-9]{1,3}|AF_INET([^6]|$)|sockaddr_in([^6]|$)' \
  . | tee artifacts/ipv6/ipv4-candidates.txt

if rg -n \
  --glob 'Sources/**' \
  --glob 'Config/**' \
  'https?://([0-9]{1,3}\.){3}[0-9]{1,3}' .; then
  echo "Production configuration contains an IPv4 URL" >&2
  exit 1
fi

Classify the candidate list manually once, then add permitted matches to a documented allowlist. Do not exclude the entire Tests directory, because test helpers can also be copied into the production networking layer. For C or Objective-C wrappers, pay particular attention to whether getaddrinfo uses AF_UNSPEC for ai_family. Fix it to a single address family only when that behavior is explicitly required.

Avoid Incorrect Fixes

Do not mechanically convert IPv4 addresses to IPv4-mapped IPv6 addresses, and do not construct a NAT64 prefix yourself. The prefix depends on the current network, so hard-coding it will fail when the network changes. The correct approach is to retain the hostname and let the system resolver return the addresses available when the connection is made.

Make DNS64 Conditions a Preflight Check

Record the network state before testing so that an unsuitable environment does not generate a wave of false positives. Cloud Mac runners should use a controlled DNS64/NAT64 network prepared by the team. The CI script should only verify the required conditions, not temporarily change the system network configuration during the job.

set -euo pipefail

OUT="artifacts/ipv6"
mkdir -p "$OUT"

scutil --dns > "$OUT/scutil-dns.txt"
route -n get default > "$OUT/default-route.txt" 2>&1 || true
dscacheutil -q host -a name api.test.example \
  > "$OUT/target-resolution.txt"

if ! grep -Eq 'ipv6_address|ip_address' "$OUT/target-resolution.txt"; then
  echo "Target hostname did not resolve in the test environment" >&2
  exit 2
fi

The test domain should belong to an environment controlled by the team and return a stable health-check response with no sensitive information. Do not use a public website as a gate dependency. External rate limits, certificate changes, or regional policies would make build results nondeterministic.

Validate Real Behavior with URLSession

Network tests should cover both a successful initial request and recovery after a failure. Requests must use finite timeouts, and the base URL should be supplied through dependency injection so that the test code does not hard-code an address again.

import XCTest

final class IPv6ReadinessTests: XCTestCase {
    func testHealthEndpointReturnsExpectedStatus() async throws {
        let value = try XCTUnwrap(
            ProcessInfo.processInfo.environment["TEST_BASE_URL"]
        )
        let baseURL = try XCTUnwrap(URL(string: value))
        let url = baseURL.appending(path: "health")

        let configuration = URLSessionConfiguration.ephemeral
        configuration.timeoutIntervalForRequest = 15
        configuration.timeoutIntervalForResource = 30

        let session = URLSession(configuration: configuration)
        let (_, response) = try await session.data(from: url)
        let http = try XCTUnwrap(response as? HTTPURLResponse)

        XCTAssertEqual(http.statusCode, 200)
    }
}

Use a fixed test plan, simulator model, and result directory when running the tests:

set -o pipefail

xcodebuild test \
  -workspace App.xcworkspace \
  -scheme AppNetworkTests \
  -testPlan IPv6Readiness \
  -destination 'platform=iOS Simulator,name=iPhone 16' \
  -resultBundlePath artifacts/ipv6/IPv6Readiness.xcresult \
  TEST_BASE_URL='https://api.test.example/' \
  | tee artifacts/ipv6/xcodebuild.log

If the application supports uploads and persistent connections, add tests for a small-file upload, exponential backoff after a connection interruption, and recovery after foreground-background transitions. Assertions should focus on application outcomes rather than localized error messages.

Preserve Diagnostic Evidence on Failure

When the gate fails, retain at least the static-analysis results, DNS state, target resolution results, the xcodebuild log, and the xcresult. Logs must not contain tokens, request bodies, or complete authorization headers. If request details must be logged, record only the method, a redacted path, the status code, the retry count, and the error domain.

Use a consistent troubleshooting sequence:

1. Confirm that the environment preflight passed and that the target hostname was resolved by the system.
2. Check whether the failed request used a hostname rather than a cached address from an earlier resolution.
3. Check whether a low-level library restricts connections to AF_INET or creates IPv4 sockets directly.
4. Compare the initial connection and reconnection paths to confirm that both use the same resolution strategy.
5. Revalidate critical flows on a physical device connected to the controlled DNS64/NAT64 network.

The simulator gate handles frequent regression testing, while physical devices provide pre-release confirmation. Separating these responsibilities keeps routine builds independent of manual operations and gives the network team enough archived evidence to determine whether a failure belongs to the resolution, connection, or application retry layer. On VPSGit, runners only need consistent toolchains, test plans, and environment variables to keep these checks repeatable instead of rebuilding the test setup after users report a problem.

Frequently asked questions