Merge pull request #5 from argos-ci/docs

Improve documentation

README.md

@@ -1,52 +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/)
-- `options.element` - Accept an ElementHandle or a string selector to screenshot an element
-
-```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());
-  });
-});
-```
-
-Screenshots are stored in `screenshots/argos` folder, relative to current directory.
-
-### 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)

docs/index.mdx

@@ -3,53 +3,67 @@ title: Puppeteer
 slug: /puppeteer
 ---
 
-# Install Argos with Puppeteer
+# Use Argos with Puppeteer
 
-Setup Argos with [Puppeteer](https://github.com/puppeteer/puppeteer).
+Integrating Argos with your [Puppeteer](https://github.com/puppeteer/puppeteer) tests to enable visual testing on your application.
 
-Install the [@argos-ci/puppeteer](https://github.com/argos-ci/argos-puppeteer) library to use Puppeteer commands and utilities for Argos visual testing.
+Puppeteer already offers a command to take screenshots. The official Argos Puppeteer integration uses it but also does several things:
 
-## 1. Install
+- Wait for all images to be loaded
+- Wait for all fonts to be loaded
+- Wait for no `aria-busy` (loader) elements to be present in the page
+- Hide scrollbars
+- Hide carets
+- Expose CSS helpers to help you hiding content
 
-```sh
-npm install --save-dev @argos-ci/puppeteer
+## Setup
+
+```
+npm install --save-dev @argos-ci/cli @argos-ci/puppeteer
 ```
 
 ## Usage
 
-The `argosScreenshot` command to stabilizes the UI before taking a screenshot.
-
 `argosScreenshot(page, name[, options])`
 
 - `page` - A `puppeteer` page instance
 - `name` - The screenshot name; must be unique
-- `options` - Send to [Page.screenshot command options](https://pptr.dev/next/api/puppeteer.page.screenshot/)
+- `options` - See [Page.screenshot command options](https://pptr.dev/next/api/puppeteer.page.screenshot/)
+- `options.element` - Accept an ElementHandle or a string selector to screenshot an element
 
 ```js
-import { puppeteer } from 'puppeteer';
-import { argosScreenshot } from '@argos/puppeteer';
-
-async puppeteerScreenshot(url) => {
-  const browser = await puppeteer.launch();
-  const page = await browser.newPage();
-  await page.goto('http://my-site.com/', { waitUntil: 'networkidle2' });
-  await argosScreenshot(page, 'home');
-
-  await browser.close();
-};
+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
+Screenshots are stored in `screenshots/argos` folder, relative to current directory.
+
+### 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.
 
 - `[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
 
 ```html
 <!-- Hide a div from a screenshot -->
 <div id="clock" data-visual-test="transparent">...</div>
 ```
+
+## Upload screenshots to Argos
+
+Before publishing, generate a unique `<project-token>` by [subscribing to Argos](https://github.com/marketplace/argos-ci).
+
+Once you installed the `@argos-ci/cli` package and have a `<project-token>`, run the following command in your project directory.
+
+```
+npx argos upload --token <project-token> screenshots/argos
+```

fixtures/dummy.html

@@ -52,13 +52,6 @@ <h3>Hidden</h3>
         </div>
       </div>
 
-      <h3>Blackout</h3>
-      <div class="field">
-        <div data-visual-test="blackout">
-          This div has `data-visual-test="blackout"` attribute.
-        </div>
-      </div>
-
       <h3>Loader (3s)</h3>
       <div id="loader-container" class="field">
         <div id="loader" aria-busy="true"></div>

index.js

@@ -38,11 +38,29 @@ 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";
 }
 
+/**
+ * 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,
@@ -69,7 +87,8 @@ export async function argosScreenshot(
     mkdirp(directory),
     page.addStyleTag({ content: GLOBAL_STYLES }),
     page.waitForFunction(ensureNoBusy),
-    page.waitForFunction(waitForFontLoading),
+    page.waitForFunction(waitForFonts),
+    page.waitForFunction(waitForImages),
   ]);
 
   await resolvedElement.screenshot({