Playbook class abstract

A user journey your app performs on itself: taps, typing, scrolling and page changes, at a natural, fast or slow pace, with a visible finger.

Playbooks run in debug and profile builds only. In a release build run throws and nothing can be registered, so a journey can't drive a user's app.

List the steps with the verbs a playbook inherits:

class SignUpPlaybook extends Playbook {
  @override
  String get description => 'New user signs up and lands on the dashboard';

  @override
  Map<String, dynamic> get defaults => {'email': 'demo@nylo.dev'};

  @override
  Future<void> setUp(PlaybookActor actor) async {
    await Auth.logout();
  }

  @override
  List<PlaybookStep> get steps => [
    visit(SignUpPage.path),
    type('Email', data['email']),
    type('Password', 'secret123', secret: true),
    tap('Create account'),
    waitForPage(DashboardPage.path),
    see('Welcome, ${data['email']}'),
  ];
}

Create one with metro make:playbook sign_up. Run it while the app is running with metro live:run playbook sign_up, from Dart with run, or in a widget test with run(clock: NyTesterClock(tester)).

A plain string target is matched the way a person reads the screen: visible text, then a field's hint or label, then a tooltip, a semantics label, a ValueKey, and finally text that contains it. Use Find for anything more precise.

Constructors

Playbook()

Properties

caption → PlaybookCaption: Where the step caption is shown.
no setter
data → Map<String, dynamic>: The data for this run: defaults, overridden by what the run passed.
no setter
defaults → Map<String, dynamic>: The data the steps start with. A run can override any of it.
no setter
description → String?: One line shown next to the playbook's name when Metro lists them.
no setter
hashCode → int: The hash code for this object.
no setterinherited
name → String?: The name this playbook runs by when it isn't registered with Nylo.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
showFinger → bool: Whether the finger is drawn while this playbook's steps run.
no setter
speed → PlaybookSpeed: The pace the playbook runs at when nothing else says.
no setter
steps → List<PlaybookStep>: The steps, in order. Read after setUp, so they can use data.
no setter

Methods

back() → PlaybookStep: Goes back a page.
dontSee(Object target) → PlaybookStep: Checks that target isn't on screen, waiting for it to go.
longPress(Object target) → PlaybookStep: Presses and holds target.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
pause({num seconds = 1}) → PlaybookStep: Holds still for seconds, e.g. to let a demo breathe.
play(Object playbook, {Map<String, dynamic>? data, PlaybookSpeed? speed}) → PlaybookStep: Runs another playbook here, in full: its setUp, steps and tearDown.
run({PlaybookSpeed? speed, Map<String, dynamic>? data, PlaybookClock? clock, bool overlay = true, void onEvent(Map<String, Object?> event)?}) → Future<PlaybookReport>: Runs the playbook and returns its report.
runWith(PlaybookSession session, {PlaybookSpeed? speed, Map<String, dynamic>? data, void emit(Map<String, Object?> event)?, List<String> path = const [], int depth = 0, String caption = ''}) → Future<PlaybookReport>: Runs this playbook inside session, which open started.
scene(String title, List<PlaybookStep> steps) → PlaybookStep: Groups steps under title, which leads their captions and nests their results in the report.
scrollTo(Object target, {Object? within}) → PlaybookStep: Scrolls until target is on screen.
see(Object target) → PlaybookStep: Checks that target is on screen, waiting for it to show up.
seed(List<Object> seeders) → Future<void>: Runs seeders (seeders or the names they're registered under), for setUp. Throws when one fails.
setUp(PlaybookActor actor) → Future<void>: Runs before the steps, e.g. to sign out or seed data.
step(String title, Future<void> action(PlaybookActor actor)) → PlaybookStep: A step that runs any code, using the same verbs on PlaybookActor.
tap(Object target) → PlaybookStep: Taps target.
tearDown(PlaybookActor actor) → Future<void>: Runs after the steps, even when one failed.
toString() → String: A string representation of this object.
inherited
type(Object target, Object? text, {bool clear = true, bool submit = false, bool secret = false}) → PlaybookStep: Types text into the field target, found by its hint or label.
visit(Object path, {Object? data}) → PlaybookStep: Opens the page at path, passing it data.
waitFor(Object target, {Duration? timeout}) → PlaybookStep: Waits up to timeout (10 seconds by default) for target.
waitForPage(Object path, {Duration? timeout}) → PlaybookStep: Waits for the page at path to be on screen.

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Properties

debugReleaseModeOverride ↔ bool: Makes this build act like a release build, for tests.
getter/setter pair
isAvailable → bool: Whether playbooks can run in this build: false in release builds.
no setter
isRunning → bool: Whether a playbook is running in this app.
no setter

Static Methods

close(PlaybookSession session) → void: Ends a run started with open and removes its overlay.
open({PlaybookClock? clock, bool overlay = true, PlaybookCaption caption = PlaybookCaption.bottom}) → Future<PlaybookSession>: Starts a run: waits for the app's first frame and shows the overlay.
runSteps(PlaybookActor actor, List<PlaybookStep> steps, PlaybookStepContext context, {bool skipAll = false}) → Future<List<PlaybookStepResult>>: Runs steps in order with actor, stopping at the first failure.
stop() → bool: Asks the running playbook to stop at its next wait.

Constants

maxDepth → const int: How deeply play() can nest playbooks.