screenshot method

PlaybookStep screenshot(
  1. String name, {
  2. List<String>? locales,
  3. List<String>? themes,
  4. String? caption,
  5. bool native = true,
})

Captures the screen as name.

metro live:run playbook <name> saves it as screenshots/<playbook>/<name>.png, with no flag needed. A run from code captures it with run(onScreenshot: ...), and any other run, such as PLAYBOOK_ON_BOOT, just waits for the screen to settle. name is used as a file name, so it's made of letters, digits, -, _ and ..

With locales or themes, the same screen is captured once in each, saved as es/cart.png or es-dark/cart.png. The app switches in place, keeping the page and its state, and switches back before the next step:

screenshot('cart', locales: ['en', 'es'], themes: ['light', 'dark']),
screenshot('home', locales: Screenshot.allLocales),

caption is the text above the screen when the run frames its screenshots, e.g. --screenshots --store ios-6.9 --frame. A translation key is translated into each locale.

On the iOS Simulator and Android, Metro captures the device's whole screen, so the status bar and keyboard are in it, and the finger and caption are hidden while it does. Add --clean-status-bar to the run for 9:41 with full signal and battery. Elsewhere, in runs that aren't from Metro, and in --store and --frame runs, the app captures its own screen. native false always uses the app's capture:

screenshot('checkout', native: false),

Implementation

PlaybookStep screenshot(
  String name, {
  List<String>? locales,
  List<String>? themes,
  String? caption,
  bool native = true,
}) {
  if (!RegExp(r'^[A-Za-z0-9][A-Za-z0-9_.-]*$').hasMatch(name)) {
    throw ArgumentError.value(
      name,
      'name',
      'must start with a letter or digit and use only letters, digits, '
          '"-", "_" and "."',
    );
  }
  return PlaybookScreenshotStep(
    name,
    locales: locales,
    themes: themes,
    caption: caption,
    native: native,
  );
}