Class: Screengrab::Runner

Inherits:
Object
  • Object
show all
Defined in:
screengrab/lib/screengrab/runner.rb

Constant Summary collapse

NEEDED_PERMISSIONS = 
[
  'android.permission.READ_EXTERNAL_STORAGE',
  'android.permission.WRITE_EXTERNAL_STORAGE',
  'android.permission.CHANGE_CONFIGURATION'
].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(executor = FastlaneCore::CommandExecutor, config = Screengrab.config, android_env = Screengrab.android_environment) ⇒ Runner

Returns a new instance of Runner.



17
18
19
20
21
22
23
24
 
# File 'screengrab/lib/screengrab/runner.rb', line 17

def initialize(executor = FastlaneCore::CommandExecutor,
               config = Screengrab.config,
               android_env = Screengrab.android_environment)

  @executor = executor
  @config = config
  @android_env = android_env
end

Instance Attribute Details

#number_of_retries ⇒ Object

Returns the value of attribute number_of_retries.



15
16
17
 
# File 'screengrab/lib/screengrab/runner.rb', line 15

def number_of_retries
  @number_of_retries
end

Instance Method Details

#clear_device_previous_screenshots(app_package_name, device_serial, device_screenshots_paths) ⇒ Object 



163
164
165
166
167
168
169
170
171
172
173
 
# File 'screengrab/lib/screengrab/runner.rb', line 163

def clear_device_previous_screenshots(app_package_name, device_serial, device_screenshots_paths)
  UI.message('Cleaning screenshots on device')

  device_screenshots_paths.each do |device_path|
    if_device_path_exists(app_package_name, device_serial, device_path) do |path|
      run_adb_command("-s #{device_serial} shell run-as #{app_package_name} rm -rf #{path}",
                      print_all: true,
                      print_command: true)
    end
  end
end

#clear_local_previous_screenshots(device_type_dir_name) ⇒ Object 



119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'screengrab/lib/screengrab/runner.rb', line 119

def clear_local_previous_screenshots(device_type_dir_name)
  if @config[:clear_previous_screenshots]
    UI.message("Clearing #{device_type_dir_name} within #{@config[:output_directory]}")

    # We'll clear the temporary directory where screenshots wind up after being pulled from
    # the device as well, in case those got stranded on a previous run/failure
    ['screenshots', device_type_dir_name].each do |dir_name|
      files = screenshot_file_names_in(@config[:output_directory], dir_name)
      File.delete(*files)
    end
  end
end

#determine_external_screenshots_path(device_serial, locales) ⇒ Object 



136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'screengrab/lib/screengrab/runner.rb', line 136

def determine_external_screenshots_path(device_serial, locales)
  # macOS evaluates $foo in `echo $foo` before executing the command,
  # Windows doesn't - hence the double backslash vs. single backslash
  command = Helper.windows? ? "shell echo \$EXTERNAL_STORAGE " : "shell echo \\$EXTERNAL_STORAGE"
  device_ext_storage = run_adb_command("-s #{device_serial} #{command}",
                                       print_all: true,
                                       print_command: true)
  device_ext_storage = device_ext_storage.strip
  return locales.map do |locale|
    File.join(device_ext_storage, @config[:app_package_name], 'screengrab', locale, "images", "screenshots")
  end.flatten
end

#determine_internal_screenshots_paths(app_package_name, locales) ⇒ Object 



149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'screengrab/lib/screengrab/runner.rb', line 149

def determine_internal_screenshots_paths(app_package_name, locales)
  return locales.map do |locale|
    [
      "/data/user/0/#{app_package_name}/files/#{app_package_name}/screengrab/#{locale}/images/screenshots",

      # https://github.com/fastlane/fastlane/issues/15653#issuecomment-578541663
      "/data/data/#{app_package_name}/files/#{app_package_name}/screengrab/#{locale}/images/screenshots",

      "/data/data/#{app_package_name}/app_screengrab/#{locale}/images/screenshots",
      "/data/data/#{app_package_name}/screengrab/#{locale}/images/screenshots"
    ]
  end.flatten
end

#device_api_version(device_serial) ⇒ Object 



416
417
418
419
 
# File 'screengrab/lib/screengrab/runner.rb', line 416

def device_api_version(device_serial)
  run_adb_command("-s #{device_serial} shell getprop ro.build.version.sdk",
                  print_all: true, print_command: true).to_i
end

#enable_clean_status_bar(device_serial, app_apk_path) ⇒ Object 



421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
 
# File 'screengrab/lib/screengrab/runner.rb', line 421

def enable_clean_status_bar(device_serial, app_apk_path)
  return unless device_api_version(device_serial) >= 23

  unless @android_env.aapt_path
    UI.error("The `aapt` command could not be found, so status bar could not be cleaned. Make sure android_home is configured for screengrab or ANDROID_HOME is set in the environment")
    return
  end

  # Check if the app wants to use the clean status bar feature
  badging_dump = @executor.execute(command: "#{@android_env.aapt_path} dump badging #{app_apk_path}",
                                   print_all: true, print_command: true)
  return unless badging_dump.include?('uses-feature: name=\'tools.fastlane.screengrab.cleanstatusbar\'')

  UI.message('Enabling clean status bar')

  # Make sure the app requests the DUMP permission
  unless badging_dump.include?('uses-permission: name=\'android.permission.DUMP\'')
    UI.user_error!("The clean status bar feature requires the android.permission.DUMP permission but it could not be found in your app APK")
  end

  # Grant the DUMP permission
  run_adb_command("-s #{device_serial} shell pm grant #{@config[:app_package_name]} android.permission.DUMP",
                  print_all: true, print_command: true)

  # Enable the SystemUI demo mode
  run_adb_command("-s #{device_serial} shell settings put global sysui_demo_allowed 1",
                  print_all: true, print_command: true)
end

#grant_permissions(device_serial) ⇒ Object 



225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'screengrab/lib/screengrab/runner.rb', line 225

def grant_permissions(device_serial)
  UI.message('Granting the permission necessary to change locales on the device')
  run_adb_command("-s #{device_serial} shell pm grant #{@config[:app_package_name]} android.permission.CHANGE_CONFIGURATION",
                  print_all: true,
                  print_command: true)

  if device_api_version(device_serial) >= 23
    UI.message('Granting the permissions necessary to access device external storage')
    run_adb_command("-s #{device_serial} shell pm grant #{@config[:app_package_name]} android.permission.WRITE_EXTERNAL_STORAGE",
                    print_all: true,
                    print_command: true)
    run_adb_command("-s #{device_serial} shell pm grant #{@config[:app_package_name]} android.permission.READ_EXTERNAL_STORAGE",
                    print_all: true,
                    print_command: true)
  end
end

#if_device_path_exists(app_package_name, device_serial, device_path) ⇒ Object

Some device commands fail if executed against a device path that does not exist, so this helper method provides a way to conditionally execute a block only if the provided path exists on the device.



375
376
377
378
379
380
381
382
383
384
 
# File 'screengrab/lib/screengrab/runner.rb', line 375

def if_device_path_exists(app_package_name, device_serial, device_path)
  return if run_adb_command("-s #{device_serial} shell run-as #{app_package_name} ls #{device_path}",
                            print_all: false,
                            print_command: false).include?('No such file')

  yield(device_path)
rescue
  # Some versions of ADB will have a non-zero exit status for this, which will cause the executor to raise.
  # We can safely ignore that and treat it as if it returned 'No such file'
end

#install_apks(device_serial, app_apk_path, tests_apk_path) ⇒ Object 



193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'screengrab/lib/screengrab/runner.rb', line 193

def install_apks(device_serial, app_apk_path, tests_apk_path)
  UI.message('Installing app APK')
  apk_install_output = run_adb_command("-s #{device_serial} install -t -r #{app_apk_path.shellescape}",
                                       print_all: true,
                                       print_command: true)
  UI.user_error!("App APK could not be installed") if apk_install_output.include?("Failure [")

  UI.message('Installing tests APK')
  apk_install_output = run_adb_command("-s #{device_serial} install -t -r #{tests_apk_path.shellescape}",
                                       print_all: true,
                                       print_command: true)
  UI.user_error!("Tests APK could not be installed") if apk_install_output.include?("Failure [")
end

#installed_packages(device_serial) ⇒ Object

Return an array of packages that are installed on the device



387
388
389
390
391
392
 
# File 'screengrab/lib/screengrab/runner.rb', line 387

def installed_packages(device_serial)
  packages = run_adb_command("-s #{device_serial} shell pm list packages",
                             print_all: true,
                             print_command: true)
  packages.split("\n").map { |package| package.gsub("package:", "") }
end

#move_pulled_screenshots(locale, pull_dir, device_type_dir_name) ⇒ Object 



341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
 
# File 'screengrab/lib/screengrab/runner.rb', line 341

def move_pulled_screenshots(locale, pull_dir, device_type_dir_name)
  # Glob pattern that finds the pulled screenshots directory for each locale
  # Possible matches:
  #   [pull_dir]/en-US/images/screenshots
  #   [pull_dir]/screengrab/en-US/images/screenshots
  screenshots_dir_pattern = File.join(pull_dir, '**', "screenshots")

  Dir.glob(screenshots_dir_pattern, File::FNM_CASEFOLD).each do |screenshots_dir|
    src_screenshots = Dir.glob(File.join(screenshots_dir, '*.png'), File::FNM_CASEFOLD)

    # The :output_directory is the final location for the screenshots, so we begin by replacing
    # the temp directory portion of the path, with the output directory
    dest_dir = screenshots_dir.gsub(pull_dir, @config[:output_directory])

    # Different versions of adb are inconsistent about whether they will pull down the containing
    # directory for the screenshots, so we'll try to remove that path from the directory name when
    # creating the destination path.
    # See: https://github.com/fastlane/fastlane/pull/4915#issuecomment-236368649
    dest_dir = dest_dir.gsub(%r{(app_)?screengrab/}, '')

    # We then replace the last segment of the screenshots directory path with the device_type
    # specific name, as expected by supply
    #
    # (Moved to: fastlane/metadata/android/en-US/images/phoneScreenshots)
    dest_dir = File.join(File.dirname(dest_dir), locale, 'images', device_type_dir_name)

    FileUtils.mkdir_p(dest_dir)
    FileUtils.cp_r(src_screenshots, dest_dir)
    UI.success("Screenshots copied to #{dest_dir}")
  end
end

#pull_screenshots_from_device(locale, device_serial, device_screenshots_paths, device_type_dir_name) ⇒ Object 



291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
 
# File 'screengrab/lib/screengrab/runner.rb', line 291

def pull_screenshots_from_device(locale, device_serial, device_screenshots_paths, device_type_dir_name)
  UI.message("Pulling captured screenshots for locale #{locale} from the device")
  starting_screenshot_count = screenshot_file_names_in(@config[:output_directory], device_type_dir_name).length

  UI.verbose("Starting screenshot count is: #{starting_screenshot_count}")

  # Make a temp directory into which to pull the screenshots before they are moved to their final location.
  # This makes directory cleanup easier, as the temp directory will be removed when the block completes.

  Dir.mktmpdir do |tempdir|
    device_screenshots_paths.each do |device_path|
      if_device_path_exists(@config[:app_package_name], device_serial, device_path) do |path|
        next unless path.include?(locale)
        out = run_adb_command("-s #{device_serial} pull #{path} #{tempdir}",
                              print_all: false,
                              print_command: true,
                              raise_errors: false)
        if out =~ /Permission denied/
          dir = File.dirname(path)
          base = File.basename(path)
          run_adb_command("-s #{device_serial} shell run-as #{@config[:app_package_name]} \"tar -cC #{dir} #{base}\" | tar -xv -f- -C #{tempdir}",
                          print_all: false,
                          print_command: true)
        end
      end
    end

    # The SDK can't 100% determine what kind of device it is running on relative to the categories that
    # supply and Google Play care about (phone, 7" tablet, TV, etc.).
    #
    # Therefore, we'll move the pulled screenshots from their genericly named folder to one named by the
    # user provided device_type option value to match the directory structure that supply expects
    move_pulled_screenshots(locale, tempdir, device_type_dir_name)
  end

  ending_screenshot_count = screenshot_file_names_in(@config[:output_directory], device_type_dir_name).length

  UI.verbose("Ending screenshot count is: #{ending_screenshot_count}")

  # Because we can't guarantee the screenshot output directory will be empty when we pull, we determine
  # success based on whether there are more screenshots there than when we started.
  # This is only applicable though when `clear_previous_screenshots` is set to `true`.
  if starting_screenshot_count == ending_screenshot_count && @config[:clear_previous_screenshots]
    UI.error("Make sure you've used Screengrab.screenshot() in your tests and that your expected tests are being run.")
    UI.abort_with_message!("No screenshots were detected 📷❌")
  end

  ending_screenshot_count - starting_screenshot_count
end

#run ⇒ Object 



26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'screengrab/lib/screengrab/runner.rb', line 26

def run
  # Standardize the locales
  @config[:locales].map! { |locale| locale.gsub("_", "-") }
  FastlaneCore::PrintTable.print_values(config: @config, hide_keys: [], title: "Summary for screengrab #{Fastlane::VERSION}")

  app_apk_path = @config.fetch(:app_apk_path, ask: false)
  tests_apk_path = @config.fetch(:tests_apk_path, ask: false)
  discovered_apk_paths = Dir[File.join('**', '*.apk')]

  apk_paths_provided = app_apk_path && !app_apk_path.empty? && tests_apk_path && !tests_apk_path.empty?

  unless apk_paths_provided || discovered_apk_paths.any?
    UI.error('No APK paths were provided and no APKs could be found')
    UI.error("Please provide APK paths with 'app_apk_path' and 'tests_apk_path' and make sure you have assembled APKs prior to running this command.")
    return
  end

  test_classes_to_use = @config[:use_tests_in_classes]
  test_packages_to_use = @config[:use_tests_in_packages]

  if test_classes_to_use && test_classes_to_use.any? && test_packages_to_use && test_packages_to_use.any?
    UI.error("'use_tests_in_classes' and 'use_tests_in_packages' can not be combined. Please use one or the other.")
    return
  end

  if (test_classes_to_use.nil? || test_classes_to_use.empty?) && (test_packages_to_use.nil? || test_packages_to_use.empty?)
    UI.important('Limiting the test classes run by `screengrab` to just those that generate screenshots can make runs faster.')
    UI.important('Consider using the :use_tests_in_classes or :use_tests_in_packages option, and organize your tests accordingly.')
  end

  device_type_dir_name = "#{@config[:device_type]}Screenshots"
  clear_local_previous_screenshots(device_type_dir_name)

  device_serial = select_device

  device_screenshots_paths = [
    determine_external_screenshots_path(device_serial, @config[:locales]),
    determine_internal_screenshots_paths(@config[:app_package_name], @config[:locales])
  ].flatten

  # Root is needed to access device paths at /data
  if @config[:use_adb_root]
    run_adb_command("-s #{device_serial} root", print_all: false, print_command: true)
    run_adb_command("-s #{device_serial} wait-for-device", print_all: false, print_command: true)
  end

  clear_device_previous_screenshots(@config[:app_package_name], device_serial, device_screenshots_paths)

  app_apk_path ||= select_app_apk(discovered_apk_paths)
  tests_apk_path ||= select_tests_apk(discovered_apk_paths)

  validate_apk(app_apk_path)

  number_of_screenshots = run_tests(device_type_dir_name, device_screenshots_paths, device_serial, app_apk_path, tests_apk_path, test_classes_to_use, test_packages_to_use, @config[:launch_arguments])

  ReportsGenerator.new.generate

  UI.success("Captured #{number_of_screenshots} new screenshots! 📷✨")
end

#run_adb_command(command, print_all: false, print_command: false, raise_errors: true) ⇒ Object 



394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
 
# File 'screengrab/lib/screengrab/runner.rb', line 394

def run_adb_command(command, print_all: false, print_command: false, raise_errors: true)
  adb_host = @config[:adb_host]
  host = adb_host.nil? ? '' : "-H #{adb_host} "
  output = ''
  begin
    errout = nil
    cmdout = @executor.execute(command: @android_env.adb_path + " " + host + command,
                              print_all: print_all,
                              print_command: print_command,
                              error: raise_errors ? nil : proc { |out, status| errout = out }) || ''
    output = errout || cmdout
  rescue => ex
    if raise_errors
      raise ex
    end
  end
  output.lines.reject do |line|
    # Debug/Warning output from ADB
    line.start_with?('adb: ') && !line.start_with?('adb: error: ')
  end.join('') # Lines retain their newline chars
end

#run_tests(device_type_dir_name, device_screenshots_paths, device_serial, app_apk_path, tests_apk_path, test_classes_to_use, test_packages_to_use, launch_arguments) ⇒ Object 



242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'screengrab/lib/screengrab/runner.rb', line 242

def run_tests(device_type_dir_name, device_screenshots_paths, device_serial, app_apk_path, tests_apk_path, test_classes_to_use, test_packages_to_use, launch_arguments)
  unless @config[:reinstall_app]
    install_apks(device_serial, app_apk_path, tests_apk_path)
    grant_permissions(device_serial)
    enable_clean_status_bar(device_serial, app_apk_path)
  end

  number_of_screenshots = 0

  @config[:locales].each do |locale|
    if @config[:reinstall_app]
      uninstall_apks(device_serial, @config[:app_package_name], @config[:tests_package_name])
      install_apks(device_serial, app_apk_path, tests_apk_path)
      grant_permissions(device_serial)
      enable_clean_status_bar(device_serial, app_apk_path)
    end
    number_of_screenshots += run_tests_for_locale(device_type_dir_name, device_screenshots_paths, locale, device_serial, test_classes_to_use, test_packages_to_use, launch_arguments)
  end

  number_of_screenshots
end

#run_tests_for_locale(device_type_dir_name, device_screenshots_paths, locale, device_serial, test_classes_to_use, test_packages_to_use, launch_arguments) ⇒ Object 



264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
 
# File 'screengrab/lib/screengrab/runner.rb', line 264

def run_tests_for_locale(device_type_dir_name, device_screenshots_paths, locale, device_serial, test_classes_to_use, test_packages_to_use, launch_arguments)
  UI.message("Running tests for locale: #{locale}")

  instrument_command = ["-s #{device_serial} shell am instrument --no-window-animation -w",
                        "-e testLocale #{locale.tr('-', '_')}",
                        "-e endingLocale #{@config[:ending_locale].tr('-', '_')}"]
  instrument_command << "-e appendTimestamp #{@config[:use_timestamp_suffix]}"
  instrument_command << "-e class #{test_classes_to_use.join(',')}" if test_classes_to_use
  instrument_command << "-e package #{test_packages_to_use.join(',')}" if test_packages_to_use
  instrument_command << launch_arguments.map { |item| '-e ' + item }.join(' ') if launch_arguments
  instrument_command << "#{@config[:tests_package_name]}/#{@config[:test_instrumentation_runner]}"

  test_output = run_adb_command(instrument_command.join(" \\\n"),
                                print_all: true,
                                print_command: true)

  if test_output.include?("FAILURES!!!")
    if @config[:exit_on_test_failure]
      UI.test_failure!("Tests failed for locale #{locale} on device #{device_serial}")
    else
      UI.error("Tests failed")
    end
  end

  pull_screenshots_from_device(locale, device_serial, device_screenshots_paths, device_type_dir_name)
end

#screenshot_file_names_in(output_directory, device_type) ⇒ Object 



132
133
134
 
# File 'screengrab/lib/screengrab/runner.rb', line 132

def screenshot_file_names_in(output_directory, device_type)
  Dir.glob(File.join(output_directory, '**', device_type, '*.png'), File::FNM_CASEFOLD)
end

#select_app_apk(discovered_apk_paths) ⇒ Object 



109
110
111
112
 
# File 'screengrab/lib/screengrab/runner.rb', line 109

def select_app_apk(discovered_apk_paths)
  UI.important("To not be asked about this value, you can specify it using 'app_apk_path'")
  UI.select('Select your debug app APK', discovered_apk_paths)
end

#select_device ⇒ Object 



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'screengrab/lib/screengrab/runner.rb', line 86

def select_device
  adb = Fastlane::Helper::AdbHelper.new(adb_path: @android_env.adb_path, adb_host: @config[:adb_host])
  devices = adb.load_all_devices

  UI.user_error!('There are no connected and authorized devices or emulators') if devices.empty?

  specific_device = @config[:specific_device]
  if specific_device
    devices.select! do |d|
      d.serial.include?(specific_device)
    end
  end

  UI.user_error!("No connected devices matched your criteria: #{specific_device}") if devices.empty?

  if devices.length > 1
    UI.important("Multiple connected devices, selecting the first one")
    UI.important("To specify which connected device to use, use the -s (specific_device) config option")
  end

  devices.first.serial
end

#select_tests_apk(discovered_apk_paths) ⇒ Object 



114
115
116
117
 
# File 'screengrab/lib/screengrab/runner.rb', line 114

def select_tests_apk(discovered_apk_paths)
  UI.important("To not be asked about this value, you can specify it using 'tests_apk_path'")
  UI.select('Select your debug tests APK', discovered_apk_paths)
end

#uninstall_apks(device_serial, app_package_name, tests_package_name) ⇒ Object 



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
 
# File 'screengrab/lib/screengrab/runner.rb', line 207

def uninstall_apks(device_serial, app_package_name, tests_package_name)
  packages = installed_packages(device_serial)

  if packages.include?(app_package_name.to_s)
    UI.message('Uninstalling app APK')
    run_adb_command("-s #{device_serial} uninstall #{app_package_name}",
                    print_all: true,
                    print_command: true)
  end

  if packages.include?(tests_package_name.to_s)
    UI.message('Uninstalling tests APK')
    run_adb_command("-s #{device_serial} uninstall #{tests_package_name}",
                    print_all: true,
                    print_command: true)
  end
end

#validate_apk(app_apk_path) ⇒ Object 



175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'screengrab/lib/screengrab/runner.rb', line 175

def validate_apk(app_apk_path)
  unless @android_env.aapt_path
    UI.important("The `aapt` command could not be found on your system, so your app APK could not be validated")
    return
  end

  UI.message('Validating app APK')
  apk_permissions = @executor.execute(command: "#{@android_env.aapt_path} dump permissions #{app_apk_path}",
                                      print_all: true,
                                      print_command: true)

  missing_permissions = NEEDED_PERMISSIONS.reject { |needed| apk_permissions.include?(needed) }

  if missing_permissions.any?
    UI.user_error!("The needed permission(s) #{missing_permissions.join(', ')} could not be found in your app APK")
  end
end