✨ Add additional snapshot command exec helpers by wwilsman · Pull Request #922 · percy/cli

wwilsman · 2022-05-12T21:14:01Z

What is this?

This PR adds additional helpers provided with scripts evaluated on pages using the core browser.

In practice, these helpers are available to any execute option when using the percy snapshot command. For our own internal use, we can utilize these helpers when given their associated snapshot option (like waitForSelector). We could also potential use them while scraping for snapshots in other SDKs (like Storybook).

While addressing these helpers and in making them publicly accessible, I also decided to address how the current generatePromise function works. Currently, it returns a promise-like generator that can be "canceled" and have registered handlers called. However, only one place (besides tests) actually uses this feature: the queue. After updating the util, the queue was updated to utilize replacement utils instead.

Will close #857

Helpers:

generatePromise(generator[, signal][, callback]) - Updated to accept an AbortSignal, available in browser environments and later Node versions. However for some current versions of Node, a polyfill is required to support the minimum features needed to cancel a generator loop. The generatePromise util can now also receive an optional Node-style callback argument, which is utilized by the queue.
waitFor(predicate[, options]) - Split into two separate functions. A new util, yieldFor, which is an async generator function that behaves exactly the same as waitFor. The main difference is instead of running automatically, it runs the predicate check only when iterated. The existing waitFor util is now just a wrapper for generatePromise(yieldFor(...)).
waitForTimeout(timeout[, value]) - A promisified version of setTimeout (without a callback). The first argument is the timeout and the second optional argument is the value to resolve.
waitForSelector(selector[, timeout]) - Alias for waitFor(() => document.querySelector(selector), timeout).
waitForXPath(selector[, timeout]) - Like waitForSelector(...), but uses document.evaulate(...) instead.
scrollToBottom([options][, onScroll]) - A browser util to scroll to the bottom of the page, one window at a time. Any provided options are passed along to window.scrollTo(...), and any provided onScroll function will be awaited on after each window segment is scrolled.
config - An object containing global Percy config options. Also available as window.__PERCY__.config.
snapshot - An object containing the current snapshot options. Only available when execute options are provided. Also available as window.__PERCY__.snapshot.

Also changed in this PR:

The change from "cancelable" generators to AbortController highlighted that our intent was always to abort (cancel implies it has not yet started). With this, I also updated @percy/cli-command to use an AbortController for dealing with process signals. In combination with the new generatePromise util, the code for process signal handling was actually cut back significantly. However, any code that previously relied on error.canceled needed to be updated to check the error name, which is the recommended way for checking for an AbortError (emitted by an AbortSignal).

In order to get a global config reference in the right place, the browser class constructor was refactored slightly to accept a core percy instance. Other constructor code was moved into the launch method, and some process code was moved into a spawn method.

To Do:

These helpers should be publicly documented. The snapshot command itself also lacks good documentation, so this could be an opportunity to write better documentation around that in general.

The generatePromise function now accepts an abort signal and node-style callback. Rather than returning a promise-like generator, it now always returns a promise. A new AbortController polyfill was added for Node environments to support providing the generatorPromise function with an abort signal. A yieldFor function replaces the previous waitFor function with the same basic functionality; yielding on every iteration to the provided predicate function. The waitFor function is now a shortcut for generatePromise(yieldFor(...args)). A new waitForTimeout function was added in preperation of more exec utils.

These are not reset during hooks, so they can leak between tests when redefined

Robdel12

🏁 Slick stuff! Documenting this will be really nice and give folks using snapshot methods (the CLI, storybook, etc) will love these helpers 🔥

wwilsman added 3 commits May 12, 2022 14:14

♻ Refactor browser constructor to use percy instance reference

9adfbd4

♻ Use core generator and abort utils for cli-command

34347de

wwilsman added the ✨ enhancement New feature or request label May 12, 2022

wwilsman requested a review from Robdel12 May 12, 2022 21:14

wwilsman added 2 commits May 12, 2022 16:31

✨ Introduce additional core exec helpers

37fcaa7

🚨 Remove empty comment

c78d820

wwilsman force-pushed the ww/add-exec-helpers branch from 5a05edf to c78d820 Compare May 12, 2022 21:32

✅ Make some test variables constants

cc7bdb1

These are not reset during hooks, so they can leak between tests when redefined

wwilsman force-pushed the ww/add-exec-helpers branch from 7462235 to cc7bdb1 Compare May 12, 2022 21:46

🙈 Ignore coverage of injected code

f16fc45

Robdel12 approved these changes May 13, 2022

View reviewed changes

wwilsman merged commit 0f4575e into master May 13, 2022

wwilsman deleted the ww/add-exec-helpers branch May 13, 2022 16:51

wwilsman mentioned this pull request May 25, 2022

🐛 Add back browser executable environment variable #938

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

✨ Add additional snapshot command exec helpers#922

✨ Add additional snapshot command exec helpers#922
wwilsman merged 7 commits intomasterfrom
ww/add-exec-helpers

wwilsman commented May 12, 2022 •

edited

Loading

Uh oh!

Robdel12 left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

wwilsman commented May 12, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is this?

Helpers:

Also changed in this PR:

To Do:

Uh oh!

Robdel12 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

wwilsman commented May 12, 2022 •

edited

Loading