@birdseye/snapshot
Taking snapshots for Birdseye catalog.
Install
$ npm install --save-dev @birdseye/snapshot
Usage
Before running capturing process, you need to pass snapshotPlugin
in plugins
option of birdseye
function.
import birdseye from '@birdseye/app'
import { snapshotPlugin } from '@birdseye/snapshot/lib/plugin'
const load = (ctx: any) => ctx.keys().map((x: any) => ctx(x).default)
const catalogs = load(require.context('./catalogs', true, /\.catalog\.ts$/))
birdseye('#app', catalogs, {
plugins: [snapshotPlugin]
})
Next, write birdseye/capture.js
like below:
const path = require('path')
const { spawn } = require('child_process')
const { snapshot } = require('@birdseye/snapshot')
function wait(n) {
return new Promise(resolve => {
setTimeout(resolve, n)
})
}
;(async () => {
const cp = spawn('npm run serve -- birdseye/preview.js', {
cwd: path.resolve(__dirname, '../'),
shell: true,
stdio: 'ignore'
})
await wait(3000)
await snapshot({
url: 'http://localhost:8080'
})
cp.kill()
})()
Then run the script with following command:
$ node birdseye/capture.js
It will store snapshot images in birdseye/snapshots
for all component catalogs. You can run visual regression test with the snapshots.
Snapshot Options
You can specify snapshot options into your catalog to tweak capture behavior.
import { catalogFor } from '@birdseye/vue'
import MyButton from '@/components/MyButton.vue'
export default catalogFor(MyButton, 'MyButton')
.add('primary', {
props: {
primary: true
},
slots: {
default: 'Button Text'
},
plugins: {
snapshot: {
delay: 1000
}
}
})
All options should be into plugins.snapshot
for each catalog settings.
Available snapshot options are below:
skip
Set true
if you want to skip capturing for the catalog. (default false
)target
CSS selector for the element that will be captured. (default: the root element of the preview)delay
A delay (ms) before taking snapshot.disableCssAnimation
Disable CSS animations and transitions if true
. (default true
)capture
A function to define interactions (e.g. click
, hover
etc. the an element) before capture. See Triggering Interaction before Capture for details.
Triggering Interaction before Capture
There are cases that you want to manipulate a rendered catalog before capturing it. For example, capturing a hover style of a button, a focused style of a text field, etc.
You can trigger such manipulations with capture
option:
import { catalogFor } from '@birdseye/vue'
import MyButton from '@/components/MyButton.vue'
export default catalogFor(MyButton, 'MyButton')
.add('primary', {
props: {
primary: true
},
slots: {
default: 'Button Text'
},
plugins: {
snapshot: {
capture: async (page, capture) => {
await capture()
await page.hover('.my-button')
await capture()
}
}
}
})
capture
option is a function receiving two arguments - a page context and a capture function. The page context has methods to trigger manipulations for an element in the page. They are just aliases of Puppeteer's ElementHandle methods except receiving the selector for the element as the first argument. Available methods are below:
- click
- focus
- hover
- press
- select
- tap
- type
The original method arguments are supposed to placed after the second argument. For example, if you write el.click({ button: 'right' })
with Puppeteer, the equivalent is page.click('.selector', { button: 'right' })
.
In addition, page.mouse
and page.keyboard
are also exposed under the page context with the same name and the same interface of functions.
Visual Regression Testing with reg-suit
reg-suit is a visual regression testing tool which compares snapshot images, stores snapshots on cloud storage (S3, GCS), etc. This section describes how to set up visual regiression testing with reg-suit and @birdseye/snapshot with storing snapshot images on S3. You may also want to read the example repository of reg-suit.
Before using reg-suit, setup your AWS credentials. Set environment variables:
export AWS_ACCESS_KEY_ID=<your-access-key>
export AWS_SECRET_ACCESS_KEY=<your-secret-key>
Or create a file at ~/.aws/credentials
:
[default]
aws_access_key_id = <your-access-key>
aws_secret_access_key = <your-secret-key>
Install reg-suit and execute initialization command. The reg-suit CLI tool asks you several questions for set up:
$ npm install -D reg-suit
$ npx reg-suit init
After finishing reg-suit set up, run the following command for visual regression test:
$ node birdseye/capture.js && reg-suit run
License
MIT