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



223
224
225
226
227
228
229
230
 
# File 'lib/calabash-cucumber/launcher.rb', line 223

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

.launcher ⇒ Calabash::Cucumber::Launcher

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

Returns:



252
253
254
 
# File 'lib/calabash-cucumber/launcher.rb', line 252

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

.launcher_if_used ⇒ Calabash::Cucumber::Launcher

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

Returns:



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

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.



271
272
273
274
275
276
277
278
279
 
# File 'lib/calabash-cucumber/launcher.rb', line 271

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) 


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

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



350
351
352
353
354
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
406
 
# File 'lib/calabash-cucumber/launcher.rb', line 350

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

  # What was Calabash tracking? Read this post for information
  # No private data (like ip addresses) were collected
  # https://github.com/calabash/calabash-android/issues/655
  #
  # Removing usage tracking to avoid problems with EU General Data
  # Protection Regulation which takes effect in 2018.
  # 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



310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
 
# File 'lib/calabash-cucumber/launcher.rb', line 310

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.



290
291
292
293
294
295
296
297
298
 
# File 'lib/calabash-cucumber/launcher.rb', line 290

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