Skip to main content

actor

An actor represents a user. It interacts with the application by emulating actions on the page.

hover

Uses the original playwright method

click​

Uses the original playwright method

dblclick​

Uses the original playwright method

fill​

Uses the original playwright method

wait​

Uses the original playwright method

Attention

This method is intended solely for debugging.

scrollTo​

Uses the original method playwright

select​

Uses the original playwright method

keyboard​

press​

Uses the original playwright method

down​

Uses the original playwright method

up​

Uses the original playwright method

mouse​

move​

Uses the original playwright method

down​

Uses the original playwright method

up​

Uses the original playwright method

wheel​

Uses the original playwright method

clear​

Uses the original playwright method

highlight​

Uses the original playwright method

Attention

This method is intended solely for debugging.

drag​

Uses the original playwright method

blur​

Uses the original playwright method

pressSequentially​

Uses the original playwright method

waitFor​

Uses the original playwright method

waitForURL​

Uses the original playwright method

resize​

Changes the browser viewport according to the configuration:

actor.resize({ width: 1440, height: 920 });
tip

resize also affects the screenshot size. It is recommended to use this method when capturing long forms and lists.

note

The size is preserved for all subsequent actions and can be overridden by a subsequent resize.

screenshot​

Takes intermediate screenshots during page interactions.

note

If called last in the chain, it overrides the parameters of the last screenshot created by default.

Attention

Screenshot names must be in PascalCase format. Underscores are allowed as well.

actor
  // Take a screenshot of the initial form state
  .screenshot('Initial')
  .do(fillForm())
  // Name the final screenshot 'Filled'
  .screenshot('Filled');

Masking​

Elements can be masked on screenshots, which can be useful when working with dynamically changing data:

actor
  .do(fillForm())
  // Mask the component displaying time
  .screenshot('Filled', { mask: [finder.get(appClock())] });
Attention

This property is recommended to be used as rarely as possible, as it reduces regression protection. Prefer alternative methods for mocking external dependencies.

uploadFile​

Uploads one or more files to the target element:

actor.uploadFile(finder.get(uploadTrigger()), 'path/to/file_0.ext');
note

The first argument to uploadFile accepts the element that triggers the file dialog when clicked.

tip

File paths are resolved relative to the project's working directory. Therefore, it is recommended to keep them in a single location for simplicity:

function getPath(file: string) {
  return `/src/storyshots/externals/files/${file}`;
}

actor.uploadFile(finder.get(uploadTrigger()), [
  getPath('file_1.ext'),
  getPath('file_2.ext'),
]);

do​

Allows extending user actions using special transformers:

function enterCredentials(): ActorTransformer {
  return (actor) =>
    actor
      .fill(finder.getByRole('username'), 'user')
      .fill(finer.getByRole('password'), 'pass');
}

actor.do(enterCredentials());

The function also accepts story configuration as a second argument:

function closePopup(): ActorTransformer {
  return (actor, config) =>
    config.device.name === 'mobile'
      ? actor.do(swipe())
      : actor.click(finder.get(cross()));
}

toMeta​

Converts actor actions to meta objects used by storyshots.

note

When the resulting array is empty, the test is considered empty and is not run by the test runner.

stop​

Stops execution of all subsequent actions:

actor
  .hover() // Will execute
  .stop() // After this point, all subsequent actions will not be executed
  .click()
  .fill();
Attention

This method is intended solely for debugging.

exec​

Executes the provided function in the page context.

actor
  .do(submit())
  // Will run immediately after submit
  .exec(() => window.alert('Code has been injected'));
Attention

Functions passed to exec cannot have external dependencies except for global Browser API objects.