@argos-ci/puppeteer 0.0.1 → 0.0.2

package/README.md

@@ -1,49 +1,20 @@
-# @argos-ci/puppeteer
+<p align="center">
+  <a href="https://argos-ci.com/?utm_source=github&utm_medium=logo" target="_blank">
+    <img src="https://raw.githubusercontent.com/argos-ci/argos/main/resources/logos/logo-github-readme.png" alt="Argos" width="300" height="61">
+  </a>
+</p>
 
-[Puppeteer](https://pptr.dev/) commands and utilities for [Argos](https://argos-ci.com) visual testing.
+_Argos is a visual testing solution that fits in your workflow to avoid visual regression. Takes screenshots on each commit and be notified if something changes._
+
+# Official Argos Puppeteer integration
 
 [![npm version](https://img.shields.io/npm/v/@argos-ci/puppeteer.svg)](https://www.npmjs.com/package/@argos-ci/puppeteer)
 [![npm dm](https://img.shields.io/npm/dm/@argos-ci/puppeteer.svg)](https://www.npmjs.com/package/@argos-ci/puppeteer)
 [![npm dt](https://img.shields.io/npm/dt/@argos-ci/puppeteer.svg)](https://www.npmjs.com/package/@argos-ci/puppeteer)
 
-## Installation
-
-```sh
-npm install --save-dev @argos-ci/puppeteer
-```
-
-## Usage
-
-Stabilizes the UI before taking a screenshot.
-
-`argosScreenshot(page, name[, options])`
-
-- `page` - A `puppeteer` page instance
-- `name` - The screenshot name; must be unique
-- `options` - See [Page.screenshot command options](https://pptr.dev/next/api/puppeteer.page.screenshot/)
-
-```js
-describe("Integration test with visual testing", () => {
-  it("Loads the homepage", async () => {
-    const browser = await puppeteer.launch();
-    const page = await browser.newPage();
-    await page.goto(TEST_URL);
-    await argosScreenshot(page, this.test.fullTitle());
-  });
-});
-```
-
-## Helper attributes
-
-The `data-visual-test` attributes allow you to control how elements behave in the Argos screenshot.
-
-It is often used to hide changing element like dates.
+Visit [docs.argos-ci.com/puppeteer](https://docs.argos-ci.com/puppeteer) for guides, API and more.
 
-- `[data-visual-test="transparent"]` - Make the element transparent (`opacity: 0`)
-- `[data-visual-test="removed"]` - Remove the element (`display: none`)
-- `[data-visual-test="blackout"]` - Blacked out the element
+## Links
 
-```html
-<!-- Hide a div from a screenshot -->
-<div id="clock" data-visual-test="transparent">...</div>
-```
+- [Official SDK Docs](https://docs.argos-ci.com/)
+- [Discord](https://discord.gg/pK79sv85Vg)

package/index.d.ts

@@ -1,9 +1,15 @@
-import type { Page, ScreenshotOptions } from "puppeteer";
+import type { Page, ScreenshotOptions, ElementHandle } from "puppeteer";
 
-export type ArgosScreenshotOptions = Omit<
-  ScreenshotOptions,
-  "encoding" | "type" | "omitBackground" | "path"
->;
+export interface ArgosScreenshotOptions
+  extends Omit<
+    ScreenshotOptions,
+    "encoding" | "type" | "omitBackground" | "path"
+  > {
+  /**
+   * ElementHandle or string selector of the element to take a screenshot of.
+   */
+  element?: string | ElementHandle;
+}
 
 /**
  * Stabilize the UI and takes a screenshot of the application under test.

package/index.js

@@ -38,27 +38,62 @@ async function ensureNoBusy() {
   );
 }
 
-// Check if the fonts are loaded
-function waitForFontLoading() {
+/**
+ * Wait for all fonts to be loaded.
+ */
+function waitForFonts() {
   return document.fonts.status === "loaded";
 }
 
-export async function argosScreenshot(page, name, { fullPage, clip } = {}) {
+/**
+ * Wait for all images to be loaded.
+ */
+async function waitForImages() {
+  return Promise.all(
+    Array.from(document.images)
+      .filter((img) => !img.complete)
+      .map(
+        (img) =>
+          new Promise((resolve) => {
+            img.onload = img.onerror = resolve;
+          })
+      )
+  );
+}
+
+export async function argosScreenshot(
+  page,
+  name,
+  { element = page, ...options } = {}
+) {
   if (!page) throw new Error("A Puppeteer `page` object is required.");
   if (!name) throw new Error("The `name` argument is required.");
 
-  await Promise.all([
+  if (typeof element === "string") {
+    await page.waitForSelector(element);
+    element = await page.$(element);
+  }
+
+  const directory = resolve(process.cwd(), "screenshots/argos");
+
+  const [resolvedElement] = await Promise.all([
+    (async () => {
+      if (typeof element === "string") {
+        await page.waitForSelector(element);
+        return page.$(element);
+      }
+      return element;
+    })(),
+    mkdirp(directory),
     page.addStyleTag({ content: GLOBAL_STYLES }),
     page.waitForFunction(ensureNoBusy),
-    page.waitForFunction(waitForFontLoading),
+    page.waitForFunction(waitForFonts),
+    page.waitForFunction(waitForImages),
   ]);
 
-  const directory = resolve(process.cwd(), "screenshots/argos");
-  await mkdirp(directory);
-  await page.screenshot({
+  await resolvedElement.screenshot({
     path: resolve(directory, `${name}.png`),
     type: "png",
-    fullPage,
-    clip,
+    ...options,
   });
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@argos-ci/puppeteer",
   "description": "Visual testing solution to avoid visual regression. Puppeteer commands and utilities for Argos visual testing.",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "author": "Smooth Code",
   "license": "MIT",
   "repository": "github:argos-ci/argos-puppeteer",