Proposal: expose `triggerScreenshot()` as JS API

[lacolaco]

Abstract

• Expose a public API function which can trigger screen shot capturing during play() interaction steps.

Motivation

Storybook v6.4 added Interactions feature which allows us to write stories with actual browser events from synthetic user interactions. Currently, Storycap can capture screenshots of the moment after finished the interaction.

I think it would be more effective visual testing to have a capability to capture at the steps during the interaction. For example, assume a password input form with a property for toggle text visibility. Its story and an interaction function maybe become like below:

export const PasswordInput = {
  render: () => <MyPasswordInput />,
  play: async () => {
    // ...
    const input = await findByRole('....');
    await userEvent.type(input, 'password');
    // == CAPTURE 1 ==
    await triggerScreenshot('hidden password')
    const toggle = await findByRole('button');
    await userEvent.click(toggle);
    // == CAPTURE 2 ==
    await triggerScreenshot('visible password')
  },
}

APIs

I think Storycap has already triggerScreenshot() function as an internal function. It is only needed to expose that as a public API. But it should be an Async Function that returns Promise for using in play() function.

[MH4GF]

I want this feature too. There are many cases where I want to explicitly declare the screenshot timing in the play function.