While Apple doesn’t provide an “official” way to launch an app in the iOS Simulator from the command line, there’s a few private tricks we can employ. First, the iOS Simulator app itself is located in:
/Developer/Platforms/iPhoneSimulator.platform/Developer/Applications
But running that will only bring up the simulator in the last state it was in. How do we install an application in there and then run it automatically like Xcode does?
The trick is in the private iPhoneSimulatorRemoteClient.framework
.
Now before you freak out, don’t worry! This isn’t something you compile your app against and submit to the store. This is a framework that we can use on our local machines to control the simulator just like Xcode does. The best part is, all the work of hooking
into it has been done for us!
There are two command line utilities I’ve seen that do this best. I used to useiphonesim and
it works great. But I recently switched to WaxSim since
it also records video of the simulator in motion. They both are functionally equivalent and small enough to understand. It’s your call, but I recommend the later.1
THE RECIPE
First, we need to pull down the WaxSim source and install it. Run the following:
git clone https://github.com/square/WaxSim
cd WaxSim
xcodebuild install DSTROOT=/
Now, you have the waxsim
binary in /usr/local/bin
which
should already be on your path. You can now invoke your application in the simulator like this:
waxsim [application path]
So, where is your application path? That depends on how you build it! First, we’ll need to do a quick walkthrough about building Xcode projects from the command line.
cd
into your iOS application’s project directory (the one with the
Xcode project file). Then, invoke the xcodebuild
command like so:
xcodebuild -sdk iphonesimulator5.0 \
-arch i386 \
install DSTROOT=/tmp/MyApp
For most projects, this command will work just fine. However, if you have an explicit workspace set up, you’ll need to use man
to learn how to teach the
xcodebuildxcodebuild
binary to interpret
your setup. There’s a lot of good stuff in there about how to specify whether to build for the simulator or device, too.
The DSTROOT
environment variable on the command above is the most important
part. DSTROOT
is used by Xcode when run with the “install” build action
to figure out where to put the results. We’re specifying /tmp/MyApp
explicitly
so that we know where the resulting application bundle will be to hand in to waxsim
.
Once the xcodebuild
command completes, you should now have an *.app
bundle in /tmp/MyApp/Applications/[YourAppName].app
. Of course, subtitute
your own application name in the path. Invoke waxsim
and you’re up
and running:
waxsim /tmp/MyApp/Applications/[YourAppName].app
This runs the iPhone simulator with the latest SDK that waxsim
is aware
of. Usewaxsim -h
to find out other options like running the iPad simulator
or other using other available SDKs.
You can also record a low resolution video of the simulator like so
waxsim -v myvideo.mov /tmp/MyApp/Applications/[YourAppName].app
And now you’ll have myvideo.mov
in the current directory. It’s a pretty
low res and stuttery video, probably not something you’d use for a promotional demo, but it’s a nice feature if you need to review results of automated testing workflows.
SCRIPT IT
So, for completeness sake, here’s a shell script that you can modify to build and run your application:
#!/bin/bash
# Tell bash to abort the script if any error happens
set -e
APPNAME=MyApp
DSTROOT=/tmp/MyApp
xcodebuild -sdk iphonesimulator5.0 \
-arch i386 \
install DSTROOT="$DSTROOT"
waxsim "$DSTROOT"/Applications/"$APPNAME".app
Drop this in your project directory and tweak to taste.
THE END!
So, there you have it. We’ve built the waxsim
binary, learned briefly
how to build with xcodebuild
, and learned how to launch your application
in the iOS simulator on demand and from the command line. Vive la Unix!