iOS TestFlight Testing (EAS)

Overview

This guide outlines the process for creating and distributing builds of specific feature branches of the Peregrine application for testing on iOS devices using Apple’s TestFlight platform, facilitated by Expo Application Services (EAS). This allows developers and testers to evaluate new features or bug fixes in isolation before they are merged into the main codebase.

Prerequisites

Before you begin, ensure you have the following:

1. Apple Developer Account: Access to an active Apple Developer Program account is required.
2. App Store Connect Access: Appropriate roles (App Manager, Admin, or Developer) in App Store Connect for the Phenom app.
3. Expo Account & Project Setup: The Peregrine project must be configured on Expo.dev.
4. EAS CLI: The Expo Application Services Command Line Interface installed and configured (npm install -g eas-cli, eas login).
5. EAS Build Configuration: The eas.json file should be configured in the project root, potentially with specific profiles for feature branch testing. See EAS Build Configuration.
6. Apple Credentials Managed by EAS: Ensure your Apple Developer account credentials (certificates, provisioning profiles) are set up and managed through EAS. See EAS Credentials.
7. TestFlight App: Testers must have the TestFlight app installed on their iOS devices.

Workflow

The general workflow involves creating a feature branch, building it using EAS Build, submitting it to TestFlight via EAS Submit, and managing testers in App Store Connect.

Step 1: Create and Push Your Feature Branch

Work on your feature or bug fix in a dedicated Git branch. Ensure your branch is pushed to the remote repository (e.g., GitHub).

# Example: Create a new feature branch
git checkout main
git pull origin main
git checkout -b feat/my-cool-feature

# ... make your code changes ...

git add .
git commit -m "feat: Implement cool feature"
git push -u origin feat/my-cool-feature

Step 2: Configure EAS Build Profile (If Necessary)

Review the eas.json file. You might use an existing profile (e.g., preview or production if configured for internal distribution) or create a specific profile for feature branches.

Example eas.json snippet for a feature profile:

{
  "cli": {
    "version": ">= 3.0.0"
  },
  "build": {
    "feature-test": {
      "extends": "production",
      "distribution": "internal",
      "channel": "feature-test",
      "ios": {
        "buildConfiguration": "Release"
      }
    },
    "production": {
    }
  },
  "submit": {
    "production": {
    }
  }
}

• distribution: "internal": This is key for TestFlight builds via EAS.
• channel: Using channels helps organize builds on Expo.dev and can be used with expo-updates.
• extends: Allows inheriting settings from a base profile.

Reference: EAS Build Configuration (eas.json)

Step 3: Start EAS Build

Initiate a build for your feature branch using the appropriate profile. Make sure you are checked out to your feature branch locally.

# Ensure you are on your feature branch
git checkout feat/my-cool-feature

# Start the iOS build using the 'feature-test' profile
eas build --platform ios --profile feature-test

• EAS CLI will prompt you for details if needed (like confirming credentials).
• The build process runs on Expo’s servers. You can monitor its progress via the link provided in the terminal output or on the Expo.dev builds dashboard.
• Build times can vary depending on the queue and project complexity.

Reference: EAS Build Command

Step 4: Submit Build to TestFlight via EAS Submit

Once the EAS build successfully completes, you can submit the .ipa artifact directly to App Store Connect for TestFlight processing using EAS Submit.

# Submit the latest successful build for the 'feature-test' profile
eas submit --platform ios --profile feature-test --latest

# OR submit a specific build ID or URL
# eas submit --platform ios --profile feature-test --id <BUILD_ID>
# eas submit --platform ios --profile feature-test --url <BUILD_URL>

• EAS Submit handles the upload and initial processing steps with App Store Connect.
• You may be prompted to log in with your Apple Developer credentials if EAS doesn’t have them stored securely.

Reference: EAS Submit Command

Step 5: App Store Connect Processing & Test Information

1. Processing: After EAS Submit completes, log in to App Store Connect. Navigate to “My Apps” -> “Your App” -> “TestFlight”. You should see your build listed, likely in a “Processing” state initially. This can take some time (minutes to hours).
2. Add Test Information: Once processed, Apple may require you to provide compliance information (e.g., regarding encryption) and details about what to test in this build. Fill this out under the build’s details in TestFlight.

Reference: App Store Connect - TestFlight Overview

Step 6: Invite Internal Testers in App Store Connect

For feature branch testing, we primarily use Internal Testers. These are users who have roles within your App Store Connect team (Admin, App Manager, Developer, Marketer, etc.).

1. Navigate to Internal Testing: In App Store Connect, go to “My Apps” -> “Your App” -> “TestFlight”.
2. Manage Testers: Select the “Internal Testing” group (usually named “App Store Connect Users”). Ensure the team members who need to test this feature branch are included in this group. You can manage members under the “Users and Access” section of App Store Connect if needed.
3. Select Build: Find the build you submitted in Step 5 (it should be processed by now).
4. Enable Testing: Click the build number and then click “Manage” or “Add Testers”. Select the “Internal Testing” group and save.
5. Notification: Testers in the group will receive an email notification from TestFlight and/or see the new build available directly within their TestFlight app.
6. Limit: You can have up to 100 internal testers per app.

Reference: Managing Internal Testers

Step 7: Tester Installation & Testing

• Internal testers will see the app update available in their TestFlight app.
• They open the invitation/TestFlight app and tap “Install” or “Update”.
• Testers use the app, focusing on the changes introduced in the feature branch.

Step 8: Feedback Collection

• TestFlight Feedback: Testers can submit feedback, including screenshots and crash reports, directly through the TestFlight app. This feedback appears in App Store Connect under the “Feedback” section.
• Other Channels: Encourage feedback through established project channels like GitHub Issues, Slack, or specific feedback forms.

Reference: Collecting Feedback with TestFlight

Conclusion

Using EAS Build and Submit streamlines the process of getting feature branch builds onto tester devices via TestFlight. Remember to manage tester groups and review feedback effectively in App Store Connect to iterate on your features before merging.