DEV Community

Kurt Frey
Kurt Frey

Posted on

Using fastlane as a solo dev

For years now, my approach to screenshots for the App Store page was easy: Launch the app in the simulator, navigate to the screens you want to show, make a screenshot.

But recently I had to make 5 screenshots across 4 devices in two languages. That’s 40 screenshots. And I had to upload those via App Store Connect. That’s where I drew the line. I knew I had to automate this. After some research, it was clear: fastlane is the way to go.

Now, let’s be honest. Automating the publishing is more than just installing fastlane. It involves getting an App Store Connect API key, UI Tests and some other new code depending on what you want to showcase. Let’s get into it.

I decided to use fastlane for creating the screenshots and automating the publishing of a new app version to the App Store. fastlane (e.g. via Homebrew) and the Xcode command line tools must be installed.

What to show

I wanted to show five features:

  1. the initial screen of the app
  2. the first question of a questionnaire that results in a record of a dataset that includes location data
  3. the conclusion of the questionnaire
  4. the detail view of that record
  5. a map view that shows all records

I needed a way to walk through the app and add a record to the dataset while doing so, but I also needed a way to add the other records (I decided to use 10 in total) to the database.

Setup

  1. Initialize fastlane with fastlane init. That gives us the required SnapshotHelper.swift file (and many more) to actually make screenshots while walking through the app (if we enable that in the interactive setup in „Automate screenshots“).
  2. Create a new target in the Xcode project: a UI Testing Bundle is used for UI Tests but also to use the Helper functions from SnapshotHelper.swift to create the screenshots.
  3. Add SnapshotHelper.swift to the new target.

fastlane configuration

You configure different tasks for fastlane by defining lanes. One lane can be publishing your app to the App Store, another one could be just creating new screenshots and yet another one could be publishing a new TestFlight build.

The lanes are defined in a Fastfile. Here’s the basic structure:

default_platform(:ios)

platform :ios do
  before_all do
    app_store_connect_api_key(path: File.expand_path("~/.appstoreconnect/api_key.json"))
  end

  # For reusability purposes 
  desc "Build app and increase build number"
  lane :build do
    build_num = latest_testflight_build_number() + 1
    build_app(
      project: "your-project.xcodeproj",
      scheme: "your-scheme",
      export_method: "app-store",
      output_directory: "./build",
      xcargs: "-allowProvisioningUpdates CURRENT_PROJECT_VERSION=#{build_num}"
    )
  end
end
Enter fullscreen mode Exit fullscreen mode

The build lane is handy in many ways. First, it’s reusable and gets called before every TestFlight and App Store upload. It increases the build number automatically (latest_testflight_build_number() counts every uploaded build, not just TestFlight builds as the function implies...). You still have to increase the version number yourself. Caution: Build and version number in Xcode are untouched. If you decide to use Xcode’s Archive, you’ll have to set that meta data manually.

Connecting to App Store Connect

To be able to publish to App Store Connect, fastlane needs an API key. Create one for an „App Manager“ in App Store Connect. Download the key (a .p8 file) and place it in a local folder outside the repo like ~/.appstoreconnect. Create a .json:

{
  "key_id": "your-key-id",
  "issuer_id": "your-issuer-id",
  "key": "contents-of-your-p8-file",
  "in_house": false
}
Enter fullscreen mode Exit fullscreen mode

The contents of your .p8 file has line breaks, escape them with \n.

fastlane will use the JSON to upload to App Store Connect. fastlane will also use what’s in fastlane/Appfile:

app_identifier("com.your.app")
team_id("your-team-id")
Enter fullscreen mode Exit fullscreen mode

(Optional) Get your current metadata

Run fastlane deliver download_metadata --api_key_path ~/.appstoreconnect/api_key.json to download your current metadata. This post assumes you already have the App set up in App Store Connect. If not, fastlane could do that, if you used another authentication method than we did. We’ll see that limitation later again.

Screenshots

By using fastlane snapshot init the program creates two files: Snapfile, SnapshotHelper.swift.

We used fastlane init, so it created more files than those two.

The Snapfile contains instructions about the screenshots you want.

  1. the devices
  2. the languages
  3. which project and scheme to screenshot
  4. where the UI Test is that guides fastlane through the app
  5. the output directory
  6. what to do with the screenshots of the previous run, what to do with the simulator and the app installed in the simulator, what to do when errors occur, and more
# Define Devices to screenshot
devices([
  "iPhone 18 Pro Max",
  "iPhone 18 Pro",
  "iPhone Duo",
  "iPad Pro 13-inch (M5)"
])

# Define languages to screenshot
languages([
  "de-DE",
  "en-US"
])

# point to your UI test
project("./your-app.xcodeproj")
scheme("your-app-scheme")
only_testing(["target/class/function"])

# further instructions
output_directory("./fastlane/screenshots")

clear_previous_screenshots(true)
override_status_bar(true)
erase_simulator(true)
localize_simulator(true)
reinstall_app(true)
app_identifier("com.your.app")

stop_after_first_error(true)
number_of_retries(1)
Enter fullscreen mode Exit fullscreen mode

Capturing screenshots is actually so common, it’s built into fastlane and just requires a Snapfile, a UI Test and the SnapshotHelper.swift. We don’t need to modify (or even create) a Fastfile for that. We make fastlane capture the screenshots with fastlane snapshot. To make fastlane capture screenshots in a lane, we call the action called capture_screenshots.

TestFlight publishing

For TestFlight publishing, we create a lane because it does two things: Build the app and upload it to App Store Connect and release it on TestFlight.

  desc "Build and upload to TestFlight"
  lane :beta do
    build
    upload_to_testflight(skip_waiting_for_build_processing: true)
  end
Enter fullscreen mode Exit fullscreen mode

It uses the build lane we created and a built-in action called upload_to_testflight. I set skip_waiting_for_build_processing to true. Why? With false, fastlane waits until Apple has processed the build (5–30 minutes) and can then set the changelog and distribute to external groups. With true, it finishes right after the upload. Internal testers get the build automatically, but the changelog and external groups are up to you in App Store Connect.

Run fastlane beta to run this lane.

App Store publishing

Let’s add a lane to the Fastfile that publishes to the App Store:

  desc "Build, upload metadata and submit for review"
  lane :release do |options|
    capture_screenshots if options[:screenshots]
    build
    upload_to_app_store(
      force: true,
      skip_screenshots: !options[:screenshots],
      overwrite_screenshots: true,
      submit_for_review: true,
      automatic_release: true,
      precheck_include_in_app_purchases: false,
      submission_information: {
        add_id_info_uses_idfa: false,
        content_rights_contains_third_party_content: false
      }
    )
  end
Enter fullscreen mode Exit fullscreen mode

The first line (capture_screenshots if options[:screenshots]) runs the capture_screenshots action before submitting. This ensures that the App Store always has the most recent screenshots if :screenshots is true.

Then, the lane reuses the build lane again. And then it uses the built-in action upload_to_app_store. The force parameter disables an HTML preview.

overwrite_screenshots: true deletes the existing screenshots in App Store Connect before uploading the new ones. It only matters with screenshots:true.

We want the app to be released as soon as it’s approved, so automatic_release is true.

Note that the release lane has to wait for Apple to process the build, because only a processed build can be submitted for review. In the beta lane I skip that wait. A TestFlight build can go out later that day, but when I release to the App Store, I want to get it done, so I keep my Mac awake.

The precheck_include_in_app_purchases must be false because we authenticate via API key. You’d have to use a different authentication method to be able to use its default value true.

The submission_information depends on your app. For my app the settings are correct. It neither uses the Advertising Identifier (add_id_info_uses_idfa), nor does it contain 3rd party content like texts and images (content_rights_contains_third_party_content). You could also set export_compliance_uses_encryption here, but I already did that in my Info.plist.

Use fastlane release screenshots:true to release and make new screenshots beforehand. Use fastlane release screenshots:false to skip making screenshots. (Don’t forget to change the metadata.)

Preparing the app

Firstly: This is only relevant if you want fastlane to make screenshots of some pre-defined data. If you want to insert dummy data in the database you need to have a way to add it in the app. Adding it via the UI Test adds it in a place the app cannot access, so it never shows up. My solution is to create a hidden Developer menu that is only available in a debug build (#if DEBUG) which can be used by the UI test like a human would.

Secondly, add a new target: UI Test Bundle. fastlane uses that bundle to make screenshots.

Writing the UI Test

Write a function that moves through the app and takes screenshots. only_testing(["target/class/function"]) in your Snapfile points to this function and skips Unit Tests and other UI Tests you may have set up.

final class ScreenshotTests: XCTestCase {
    @MainActor
    func testScreenshots() throws {
        let app = XCUIApplication()
        setupSnapshot(app)
        app.launch()

        // navigate thru the app
        snapshot("screenshot-name")
    }
}
Enter fullscreen mode Exit fullscreen mode

See that you call functions defined in SnapshotHelper.swift, so you need to add it to the target.

Workflow

  1. finish your app (or your update, or your TestFlight release)
  2. Increase your version number (build number is done by fastlane)
  3. Update metadata
  4. run fastlane beta
  5. finish your TestFlight release in App Store Connect
  6. wait for and incorporate feedback
  7. fastlane release screenshots:true (or :false)
  8. repeat

Conclusion

It’s quite some work to get it all running but once it’s done, the next App Store Connect submission is just one fastlane release (or whatever you called your lane) away, including all new screenshots (if your lane includes that), new promo text and much more.

Top comments (0)