ToolsAndDebugging.md

Tooling and Debugging

For detailed instructions on how to get started with contributing to fastlane, first check out YourFirstPR.md and Testing.md. This guide will focus on more advanced instructions on how to debug fastlane and spaceship issues and work on patches.

Debug using pry

Before you’re able to use pry, make sure to have completed the YourFirstPR.md setup part, as this will install all required development dependencies.

To add a breakpoint anywhere in the fastlane codebase, add the following 2 lines wherever you want to jump in

require 'pry'
binding.pry

As debugging with pry requires the development dependencies, make sure to execute fastlane using bundle exec after running bundle install in the project- or fastlane directory.

bundle exec fastlane beta --verbose

If you need the breakpoint when running tests, make sure to have the DEBUG environment variable set, as the default test runner will remove all output from stdout, and therefore not showing the output of pry:

DEBUG=1 bundle exec rspec

You will then jump into an interactive debugger that allows you to print out variables, call methods and much more. To continue running the original script use control + d

Debugging and patching spaceship issues

Introduction to spaceship

spaceship uses Faraday to interact with multiple Apple API endpoints:

• https://idmsa.apple.com: Used to authenticate to get a valid session
• https://developerservices2.apple.com: For provisioning profiles and devices
  • List provisioning profiles
  • Register new devices
• https://developer.apple.com:
  • List all devices, certificates, apps and app groups
  • Create new certificates, provisioning profiles and apps
  • Disable/enable services on apps and assign them to app groups
  • Delete certificates and apps
  • Repair provisioning profiles
  • Download provisioning profiles
  • Team selection
• https://itunesconnect.apple.com:
  • Managing apps
  • Managing beta testers
  • Submitting updates to review
  • Managing app metadata
• https://du-itc.itunesconnect.apple.com:
  • Upload icons, screenshots, trailers ...

spaceship is split into 3 layers:

• client.rb which is the client superclass that contains all shared code between iTunes Connect the Developer Portal
• tunes_client.rb and portal_client.rb which are the implementations for both iTunes Connect and Developer Portal. Those classes include the actual HTTP requests that are being sent:

def app_version_data(app_id, version_platform: nil, version_id: nil)
  r = request(:get, "ra/apps/#{app_id}/platforms/#{version_platform}/versions/#{version_id}")
  parse_response(r, 'data')
end

• spaceship classes, e.g. app_version.rb which contain the API the user works with. These classes usually have some logic on how to handle responses.

Don’t use any custom HTML parsing in spaceship, instead try to only use JSON and XML APIs.

Verify the website works

If spaceship doesn’t work, it’s best to first find out if the actual website (Developer Portal or iTunes Connect) is currently working. Sometimes this might be a temporary server issue that gets resolved quickly. To gather information, make sure to check if other people are having the same issue on GitHub. If it is a server issue, it’s best to file a radar or call the iTunes Connect hotline.

Setting up Charles Web Proxy

This section explains how you can set up Charles Proxy to track local https traffic and inspect the requests and their responses. Charles is a paid application with a free option that’s usually good enough for a quick debugging session limited to 15 minutes. If you prefer a free open source alternative, check out mitmproxy.

First, download and install the latest version of Charles Proxy. After the first launch, you’ll have to install its Root Certificate.

In Charles go to the Help menu and choose "SSL Proxying > Install Charles Root Certificate". Keychain Access will open, and prompt you about the certificate. Click the "Always Trust" button. You will then be prompted for your Administrator password to update the system trust settings.

You might have to restart your Mac for the changes to be applied. To see if it works, relaunch Charles and Chrome/Safari and try opening iTunes Connect.

If everything worked, you’ll already see a list of requests in the sidebar of Charles. Take a look at the above list of used API endpoints, and enable SSL Proxying and Focus on all endpoints you are interested in. After doing so, refresh the iTunes Connect page. You should be able to see all web requests with their responses.

We’re not using the built-in network tracker of your browser, since we also need a proxy for our local fastlane install, which will be covered in the next section of this document.

Compare the API requests

They key is to do the same action you want to test on both the website, and in spaceship, so you can see how the requests are different.

To pipe spaceship requests through your local proxy, you need to set an environment variable:

SPACESHIP_DEBUG=1 bundle exec fastlane spaceship

To make it easier to run the same script again, you can temporarily edit the Rakefile to look like this:

# leave existing code, and append the following

task :debug do
  require 'spaceship'

  # first login
  Spaceship::Tunes.login("apple@fastlane.tools") # use your own test account
  # or
  Spaceship::Portal.login("apple@fastlane.tools") # use your own test account

  # then add code to test whatever part of _spaceship_ needs to be tested
  # e.g.
  apps = Spaceship::Tunes::Application.all
  require 'pry'
  binding.pry
end

To run the newly created script, run

SPACESHIP_DEBUG=1 bundle exec rake debug