@percy/playwright 1.0.5 → 1.0.6-beta.0

package/README.md

@@ -58,4 +58,91 @@ $ percy exec -- node script.js
 
 - `page` (**required**) - A `playwright` page instance
 - `name` (**required**) - The snapshot name; must be unique to each snapshot
-- `options` - [See per-snapshot configuration options](https://docs.percy.io/docs/cli-configuration#per-snapshot-configuration)
+- `options` - [See per-snapshot configuration options](https://www.browserstack.com/docs/percy/take-percy-snapshots/overview#per-snapshot-configuration)
+
+
+## Percy on Automate
+
+## Usage
+
+```javascript
+const { chromium } = require('playwright');
+const percyScreenshot = require('@percy/playwright');
+
+const desired_cap = {
+  'browser': 'chrome',
+  'browser_version': 'latest',
+  'os': 'osx',
+  'os_version': 'ventura',
+  'name': 'Percy Playwright PoA Demo',
+  'build': 'percy-playwright-javascript-tutorial',
+  'browserstack.username': 'username',
+  'browserstack.accessKey': 'accesskey'
+};
+
+(async () => {
+  const cdpUrl = `wss://cdp.browserstack.com/playwright?caps=${encodeURIComponent(JSON.stringify(desired_cap))}`;
+  const browser = await chromium.connect(cdpUrl);
+  const page = await browser.newPage();
+  await page.goto("https://percy.io/");
+  await percyScreenshot(page, 'Screenshot 1');
+
+  // Options for percyScreenshot
+  // await percyScreenshot(page, 'Screenshot 1', {
+  //   fullPage: true,
+  //   percyCSS: 'body { background: red; }',
+  //   ignoreRegionSelectors: ['#ignore-this'],
+  //   customIgnoreRegions: [{ top: 10, right: 10, bottom: 120, left: 10 }],
+  // });
+
+  await browser.close();
+})();
+```
+
+## Configuration
+
+`percyScreenshot(page, name[, options])`
+
+- `page` (**required**) - A `playwright` page instance
+- `name` (**required**) - The snapshot name; must be unique to each snapshot
+- `options` (**optional**) - There are various options supported by percyScreenshot to server further functionality.
+    - `sync` - Boolean value by default it falls back to `false`, Gives the processed result around screenshot [From CLI v1.28.0-beta.0+]
+    - `fullPage` - Boolean value by default it falls back to `false`, Takes full page screenshot [From CLI v1.27.6+]
+    - `freezeAnimatedImage` - Boolean value by default it falls back to `false`, you can pass `true` and percy will freeze image based animations.
+    - `freezeImageBySelectors` - List of selectors. Images will be freezed which are passed using selectors. For this to work `freezeAnimatedImage` must be set to true.
+    - `freezeImageByXpaths` - List of xpaths. Images will be freezed which are passed using xpaths. For this to work `freezeAnimatedImage` must be set to true.
+    - `percyCSS` - Custom CSS to be added to DOM before the screenshot being taken. Note: This gets removed once the screenshot is taken.
+    - `ignoreRegionXpaths` - List of xpaths. elements in the DOM can be ignored using xpath
+    - `ignoreRegionSelectors` - List of selectors. elements in the DOM can be ignored using selectors.
+    - `customIgnoreRegions` - List of custom objects. elements can be ignored using custom boundaries. Just passing a simple object for it like below.
+      - example: ```{top: 10, right: 10, bottom: 120, left: 10}```
+      - In above example it will draw rectangle of ignore region as per given coordinates.
+        - `top` (int): Top coordinate of the ignore region.
+        - `bottom` (int): Bottom coordinate of the ignore region.
+        - `left` (int): Left coordinate of the ignore region.
+        - `right` (int): Right coordinate of the ignore region.
+    - `considerRegionXpaths` - List of xpaths. elements in the DOM can be considered for diffing and will be ignored by Intelli Ignore using xpaths.
+    - `considerRegionSelectors` - List of selectors. elements in the DOM can be considered for diffing and will be ignored by Intelli Ignore using selectors.
+    - `customConsiderRegions` - List of custom objects. elements can be considered for diffing and will be ignored by Intelli Ignore using custom boundaries
+      - example:  ```{top: 10, right: 10, bottom: 120, left: 10}```
+      - In above example it will draw rectangle of consider region will be drawn.
+      - Parameters:
+        - `top` (int): Top coordinate of the consider region.
+        - `bottom` (int): Bottom coordinate of the consider region.
+        - `left` (int): Left coordinate of the consider region.
+        - `right` (int): Right coordinate of the consider region.
+
+### Creating Percy on automate build
+Note: Automate Percy Token starts with `auto` keyword. The command can be triggered using `exec` keyword.
+```sh-session
+$ export PERCY_TOKEN=[your-project-token]
+$ percy exec -- [playwright test command]
+[percy] Percy has started!
+[percy] [Playwright example] : Starting automate screenshot ...
+[percy] Screenshot taken "Playwright example"
+[percy] Stopping percy...
+[percy] Finalized build #1: https://percy.io/[your-project]
+[percy] Done!
+```
+
+Refer to docs here: [Percy on Automate](https://www.browserstack.com/docs/percy/integrate/functional-and-visual)

package/index.js

@@ -1,17 +1,18 @@
 const utils = require('@percy/sdk-utils');
+const { Utils } = require('./utils');
 
 // Collect client and environment information
 const sdkPkg = require('./package.json');
 const playwrightPkg = require('playwright/package.json');
 const CLIENT_INFO = `${sdkPkg.name}/${sdkPkg.version}`;
 const ENV_INFO = `${playwrightPkg.name}/${playwrightPkg.version}`;
+const log = utils.logger('playwright');
 
 // Take a DOM snapshot and post it to the snapshot endpoint
 async function percySnapshot(page, name, options) {
   if (!page) throw new Error('A Playwright `page` object is required.');
   if (!name) throw new Error('The `name` argument is required.');
   if (!(await utils.isPercyEnabled())) return;
-  let log = utils.logger('playwright');
 
   try {
     // Inject the DOM serialization script
@@ -40,4 +41,36 @@ async function percySnapshot(page, name, options) {
   }
 }
 
-module.exports = percySnapshot;
+// Takes Playwright screenshot with Automate
+async function percyScreenshot(page, name, options) {
+  if (!page) throw new Error('A Playwright `page` object is required.');
+  if (!name) throw new Error('The `name` argument is required.');
+  if (!(await utils.isPercyEnabled())) return;
+  if (Utils.projectType() !== 'automate') {
+    throw new Error('Invalid function call - percyScreenshot(). Please use percySnapshot() function for taking screenshot. percyScreenshot() should be used only while using Percy with Automate. For more information on usage of PercySnapshot(), refer doc for your language https://docs.percy.io/docs/end-to-end-testing');
+  }
+
+  try {
+    const sessionDetails = await Utils.sessionDetails(page);
+    const sessionId = sessionDetails.hashed_id;
+    const pageGuid = page._guid;
+    const frameGuid = page._mainFrame._guid;
+    const data = {
+      environmentInfo: ENV_INFO,
+      clientInfo: CLIENT_INFO,
+      sessionId: sessionId,
+      pageGuid: pageGuid,
+      frameGuid: frameGuid,
+      framework: 'playwright',
+      snapshotName: name,
+      options
+    };
+    const response = await Utils.captureAutomateScreenshot(data);
+    return response?.body?.data;
+  } catch (err) {
+    log.error(`Could not take percy screenshot "${name}"`);
+    log.error(err);
+  }
+}
+
+module.exports = { percySnapshot, percyScreenshot, CLIENT_INFO, ENV_INFO };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@percy/playwright",
   "description": "Playwright client library for visual testing with Percy",
-  "version": "1.0.5",
+  "version": "1.0.6-beta.0",
   "license": "MIT",
   "author": "Perceptual Inc.",
   "repository": "https://github.com/percy/percy-playwright",
@@ -26,7 +26,8 @@
     "test:types": "tsd"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "tag": "beta"
   },
   "peerDependencies": {
     "playwright-core": ">=1"
@@ -34,6 +35,7 @@
   "devDependencies": {
     "@percy/cli": "^1.28.2",
     "@playwright/test": "^1.24.2",
+    "babel-eslint": "^10.1.0",
     "cross-env": "^7.0.2",
     "eslint": "^7.18.0",
     "eslint-config-standard": "^16.0.2",
@@ -43,6 +45,7 @@
     "eslint-plugin-standard": "^5.0.0",
     "nyc": "^15.1.0",
     "playwright": "^1.24.2",
+    "sinon": "^18.0.0",
     "tsd": "^0.25.0"
   }
 }

package/types/index.d.ts

@@ -6,3 +6,9 @@ export default function percySnapshot(
   name: string,
   options?: SnapshotOptions
 ): Promise<void>;
+
+export default function percyScreenshot(
+  page: Playwright.Page,
+  name: string,
+  options?: SnapshotOptions
+): Promise<void>;