Class: Calabash::Cucumber::Launcher

Inherits:
Object
  • Object
show all
Defined in:
lib/calabash-cucumber/launcher.rb

Overview

Launch apps on iOS Simulators and physical devices.

Accessing the current launcher from ruby.

If you need a reference to the current launcher in your ruby code.

Calabash::Cucumber::Launcher.launcher

This is usually not required, but might be useful in support/01_launch.rb.

Attaching to the current launcher in a console

If Calabash already running and you want to attach to the current launcher, use console_attach. This is useful when a cucumber Scenario has failed and you want to query the current state of the app.

  • Pro Tip: Set the QUIT_APP_AFTER_SCENARIO=0 env variable so calabash does not quit your application after a failed Scenario.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.instruments?Boolean

Are we running using instruments?

Returns:

  • (Boolean)

    true if we're using instruments to launch



228
229
230
231
232
233
234
235
# File 'lib/calabash-cucumber/launcher.rb', line 228

def self.instruments?
  launcher = Launcher::launcher_if_used
  if !launcher
    false
  else
    launcher.instruments?
  end
end

.launcherCalabash::Cucumber::Launcher

A reference to the current launcher (instantiates a new one if needed).

Returns:



257
258
259
# File 'lib/calabash-cucumber/launcher.rb', line 257

def self.launcher
  @@launcher ||= Calabash::Cucumber::Launcher.new
end

.launcher_if_usedCalabash::Cucumber::Launcher

Get a reference to the current launcher (does not instantiate a new one if unset).

Returns:



263
264
265
# File 'lib/calabash-cucumber/launcher.rb', line 263

def self.launcher_if_used
  @@launcher
end

Instance Method Details

#device_target?(options = {}) ⇒ Boolean

Is the current device under test a physical device?

Can be used before or after the application has been launched.

Maintainers, please do not call this method.

Parameters:

  • options (Hash) (defaults to: {})

    This argument is deprecated since 0.19.0.

Returns:

  • (Boolean)

    True if the device under test a physical device.



276
277
278
279
280
281
282
283
284
# File 'lib/calabash-cucumber/launcher.rb', line 276

def device_target?(options={})
  if Calabash::Cucumber::Environment.xtc?
    true
  elsif @device
    @device.device?
  else
    detect_device(options).physical_device?
  end
end

#quit_app_after_scenario?Boolean

Should Calabash quit the app under test after a Scenario?

Control this behavior using the QUIT_APP_AFTER_SCENARIO variable.

The default behavior is to quit after every Scenario.

Returns:

  • (Boolean)


449
450
451
# File 'lib/calabash-cucumber/launcher.rb', line 449

def quit_app_after_scenario?
  Calabash::Cucumber::Environment.quit_app_after_scenario?
end

#relaunch(launch_options = {}) ⇒ Object

Launches your app on the connected device or simulator.

relaunch does a lot of error detection and handling to reliably start the app and test. Instruments (particularly the cli) has stability issues which we workaround by restarting the simulator process and checking that UIAutomation is correctly attaching to your application.

Use the args parameter to to control:

  • :app - which app to launch.

  • :device - simulator or device to target.

  • `:reset_app_sandbox - reset the app's data (sandbox) before testing

and many other behaviors.

Many of these behaviors can be be controlled by environment variables. The most important environment variables are APP, DEVICE_TARGET, and DEVICE_ENDPOINT.

Parameters:

  • launch_options (Hash) (defaults to: {})

    optional arguments to control the how the app is launched



355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
# File 'lib/calabash-cucumber/launcher.rb', line 355

def relaunch(launch_options={})
  simctl = launch_options[:simctl] || launch_options[:sim_control]
  instruments = launch_options[:instruments]
  xcode = launch_options[:xcode]

  options = launch_options.clone

  # Reusing Simctl, Instruments, and Xcode can speed up launches.
  options[:simctl] = simctl || Calabash::Cucumber::Environment.simctl
  options[:instruments] = instruments || Calabash::Cucumber::Environment.instruments
  options[:xcode] = xcode || Calabash::Cucumber::Environment.xcode
  options[:inject_dylib] = detect_inject_dylib_option(launch_options)

  @launch_args = options

  @run_loop = new_run_loop(options)
  if @run_loop.is_a?(Hash)
    @automator = Calabash::Cucumber::Automator::Instruments.new(@run_loop)
  elsif @run_loop.is_a?(RunLoop::DeviceAgent::Client)
    @automator = Calabash::Cucumber::Automator::DeviceAgent.new(@run_loop)
  else
    raise ArgumentError, %Q[

Could not determine which automator to use based on the launch arguments:

#{@launch_args.join("$-0")}

RunLoop.run returned:

#{@run_loop}

]
  end

  Calabash::Cucumber::UIA.redefine_instance_methods_if_necessary(options[:xcode],
                                                                 automator)

  if !options[:calabash_lite]
    Calabash::Cucumber::HTTP.ensure_connectivity
    check_server_gem_compatibility
  end

  usage_tracker.post_usage_async

  # :on_launch to the Cucumber World if:
  # * the Launcher is part of the World (it is not by default).
  # * Cucumber responds to :on_launch.
  self.send(:on_launch) if self.respond_to?(:on_launch)

  self
end

#reset_simulator(device = nil) ⇒ Object

Erases a simulator. This is the same as touching the Simulator “Reset Content & Settings” menu item.

Parameters:

  • device (RunLoop::Device, String) (defaults to: nil)

    The simulator to erase. Can be a RunLoop::Device instance, a simulator UUID, or a human readable simulator name.

Raises:

  • ArgumentError If the simulator is a physical device

  • RuntimeError If the simulator cannot be shutdown

  • RuntimeError If the simulator cannot be erased



315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
# File 'lib/calabash-cucumber/launcher.rb', line 315

def reset_simulator(device=nil)
  if device.is_a?(RunLoop::Device)
    device_target = device
  else
    device_target = detect_device(:device => device)
  end

  if device_target.physical_device?
    raise ArgumentError,
%Q{
Cannot reset: #{device_target}.

Resetting physical devices is not supported.
}
  end

  RunLoop::CoreSimulator.erase(device_target)
  device_target
end

#simulator_target?(options = {}) ⇒ Boolean

Is the current device under test a simulator?

Can be used before or after the application has been launched.

Maintainers, please do not call this method.

Parameters:

  • options (Hash) (defaults to: {})

    This argument is deprecated since 0.19.0.

Returns:

  • (Boolean)

    True if the device under test a simulator.



295
296
297
298
299
300
301
302
303
# File 'lib/calabash-cucumber/launcher.rb', line 295

def simulator_target?(options={})
  if Calabash::Cucumber::Environment.xtc?
    false
  elsif @device
    @device.simulator?
  else
    detect_device(options).simulator?
  end
end