@percy/client 1.10.3 → 1.11.0

package/README.md

@@ -7,6 +7,7 @@ builds. Can also be used to query for a project's builds using a read access tok
 - [Usage](#usage)
 - [Create a build](#create-a-build)
 - [Create, upload, and finalize snapshots](#create-upload-and-finalize-snapshots)
+- [Create, upload, and finalize comparisons](#create-upload-and-finalize-comparisons)
 - [Finalize a build](#finalize-a-build)
 - [Query for a build*](#query-for-a-build)
 - [Query for a project's builds*](#query-for-a-projects-builds)
@@ -59,7 +60,39 @@ await client.sendSnapshot(buildId, snapshotOptions)
   - `mimetype` — Resource mimetype (**required**)
   - `content` — Resource content (**required**)
   - `sha` — Resource content sha
-  - `root` — Boolean indicating a root resource
+  - `root` — Boolean indicating a root resource## Create, upload, and finalize snapshots
+
+## Create, upload, and finalize comparisons
+
+This method combines the work of creating a snapshot, creating an associated comparison, uploading
+associated comparison tiles, and finally finalizing the comparison.
+
+``` js
+await client.sendComparison(buildId, comparisonOptions)
+```
+
+#### Options
+
+- `name` — Snapshot name (**required**)
+- `clientInfo` — Additional client info
+- `environmentInfo` — Additional environment info
+- `externalDebugUrl` — External debug URL
+- `tag` — Tagged information about this comparison
+  - `name` — The tag name for this comparison, e.g. "iPhone 14 Pro" (**required**)
+  - `osName` - OS name for the comparison tag; e.g. "iOS"
+  - `osVersion` - OS version for the comparison tag; e.g. "16"
+  - `width` - The width for this type of comparison
+  - `height` - The height for this type of comparison
+  - `orientation` - Either "portrait" or "landscape"
+- `tiles` — Array of comparison tiles
+  - `sha` — Tile file contents SHA-256 hash
+  - `filepath` — Tile filepath in the filesystem (required when missing `content`)
+  - `content` — Tile contents as a string or buffer (required when missing `filepath`)
+  - `statusBarHeight` — Height of any status bar in this tile
+  - `navBarHeight` — Height of any nav bar in this tile
+  - `headerHeight` — Height of any header area in this tile
+  - `footerHeight` — Height of any footer area in this tile
+  - `fullscreen` — Boolean indicating this is a fullscreen tile
 
 ## Finalize a build
 

package/dist/client.js

@@ -7,13 +7,13 @@ import { pool, request, sha256hash, base64encode, getPackageJSON } from './utils
 const {
   PERCY_CLIENT_API_URL = 'https://percy.io/api/v1'
 } = process.env;
-const pkg = getPackageJSON(import.meta.url); // Validate build ID arguments
+const pkg = getPackageJSON(import.meta.url); // Validate ID arguments
 
-function validateBuildId(id) {
-  if (!id) throw new Error('Missing build ID');
+function validateId(type, id) {
+  if (!id) throw new Error(`Missing ${type} ID`);
 
   if (!(typeof id === 'string' || typeof id === 'number')) {
-    throw new Error('Invalid build ID');
+    throw new Error(`Invalid ${type} ID`);
   }
 } // Validate project path arguments
 
@@ -157,7 +157,7 @@ export class PercyClient {
   async finalizeBuild(buildId, {
     all = false
   } = {}) {
-    validateBuildId(buildId);
+    validateId('build', buildId);
     let qs = all ? 'all-shards=true' : '';
     this.log.debug(`Finalizing build ${buildId}...`);
     return this.post(`builds/${buildId}/finalize?${qs}`);
@@ -165,7 +165,7 @@ export class PercyClient {
 
 
   async getBuild(buildId) {
-    validateBuildId(buildId);
+    validateId('build', buildId);
     this.log.debug(`Get build ${buildId}`);
     return this.get(`builds/${buildId}`);
   } // Retrieves project builds optionally filtered. Requires a read access token.
@@ -252,9 +252,9 @@ export class PercyClient {
     filepath,
     content
   } = {}) {
-    validateBuildId(buildId);
+    validateId('build', buildId);
     this.log.debug(`Uploading resource: ${url}...`);
-    if (filepath) content = fs.readFileSync(filepath);
+    if (filepath) content = await fs.promises.readFile(filepath);
     return this.post(`builds/${buildId}/resources`, {
       data: {
         type: 'resources',
@@ -268,7 +268,7 @@ export class PercyClient {
 
 
   async uploadResources(buildId, resources) {
-    validateBuildId(buildId);
+    validateId('build', buildId);
     this.log.debug(`Uploading resources for ${buildId}...`);
     return pool(function* () {
       for (let resource of resources) {
@@ -288,7 +288,7 @@ export class PercyClient {
     environmentInfo,
     resources = []
   } = {}) {
-    validateBuildId(buildId);
+    validateId('build', buildId);
     this.addClientInfo(clientInfo);
     this.addEnvironmentInfo(environmentInfo);
 
@@ -297,6 +297,12 @@ export class PercyClient {
     }
 
     this.log.debug(`Creating snapshot: ${name}...`);
+
+    for (let resource of resources) {
+      if (resource.sha || resource.content || !resource.filepath) continue;
+      resource.content = await fs.promises.readFile(resource.filepath);
+    }
+
     return this.post(`builds/${buildId}/snapshots`, {
       data: {
         type: 'snapshots',
@@ -311,10 +317,11 @@ export class PercyClient {
           resources: {
             data: resources.map(r => ({
               type: 'resources',
-              id: r.sha || sha256hash(r.content),
+              id: r.sha ?? (r.content && sha256hash(r.content)),
               attributes: {
                 'resource-url': r.url || null,
                 'is-root': r.root || null,
+                'for-widths': r.widths || null,
                 mimetype: r.mimetype || null
               }
             }))
@@ -326,7 +333,7 @@ export class PercyClient {
 
 
   async finalizeSnapshot(snapshotId) {
-    if (!snapshotId) throw new Error('Missing snapshot ID');
+    validateId('snapshot', snapshotId);
     this.log.debug(`Finalizing snapshot ${snapshotId}...`);
     return this.post(`snapshots/${snapshotId}/finalize`);
   } // Convenience method for creating a snapshot for the active build, uploading
@@ -352,5 +359,104 @@ export class PercyClient {
     return snapshot;
   }
 
+  async createComparison(snapshotId, {
+    tag,
+    tiles = [],
+    externalDebugUrl
+  } = {}) {
+    validateId('snapshot', snapshotId);
+    this.log.debug(`Creating comparision: ${tag.name}...`);
+
+    for (let tile of tiles) {
+      if (tile.sha || tile.content || !tile.filepath) continue;
+      tile.content = await fs.promises.readFile(tile.filepath);
+    }
+
+    return this.post(`snapshots/${snapshotId}/comparisons`, {
+      data: {
+        type: 'comparisons',
+        attributes: {
+          'external-debug-url': externalDebugUrl || null
+        },
+        relationships: {
+          tag: {
+            data: {
+              type: 'tag',
+              attributes: {
+                name: tag.name || null,
+                width: tag.width || null,
+                height: tag.height || null,
+                'os-name': tag.osName || null,
+                'os-version': tag.osVersion || null,
+                orientation: tag.orientation || null
+              }
+            }
+          },
+          tiles: {
+            data: tiles.map(t => ({
+              type: 'tiles',
+              attributes: {
+                sha: t.sha || t.content && sha256hash(t.content),
+                'status-bar-height': t.statusBarHeight || null,
+                'nav-bar-height': t.navBarHeight || null,
+                'header-height': t.headerHeight || null,
+                'footer-height': t.footerHeight || null,
+                fullscreen: t.fullscreen || null
+              }
+            }))
+          }
+        }
+      }
+    });
+  }
+
+  async uploadComparisonTile(comparisonId, {
+    index = 0,
+    total = 1,
+    filepath,
+    content
+  } = {}) {
+    validateId('comparison', comparisonId);
+    this.log.debug(`Uploading comparison tile: ${index + 1}/${total} (${comparisonId})...`);
+    if (filepath) content = await fs.promises.readFile(filepath);
+    return this.post(`comparisons/${comparisonId}/tiles`, {
+      data: {
+        type: 'tiles',
+        attributes: {
+          'base64-content': base64encode(content),
+          index
+        }
+      }
+    });
+  }
+
+  async uploadComparisonTiles(comparisonId, tiles) {
+    validateId('comparison', comparisonId);
+    this.log.debug(`Uploading comparison tiles for ${comparisonId}...`);
+    return pool(function* () {
+      for (let index = 0; index < tiles.length; index++) {
+        yield this.uploadComparisonTile(comparisonId, {
+          index,
+          total: tiles.length,
+          ...tiles[index]
+        });
+      }
+    }, this, 2);
+  }
+
+  async finalizeComparison(comparisonId) {
+    validateId('comparison', comparisonId);
+    this.log.debug(`Finalizing comparison ${comparisonId}...`);
+    return this.post(`comparisons/${comparisonId}/finalize`);
+  }
+
+  async sendComparison(buildId, options) {
+    let snapshot = await this.createSnapshot(buildId, options);
+    let comparison = await this.createComparison(snapshot.data.id, options);
+    await this.uploadComparisonTiles(comparison.data.id, options.tiles);
+    await this.finalizeComparison(comparison.data.id);
+    return comparison;
+  }
+
 }
 export default PercyClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percy/client",
-  "version": "1.10.3",
+  "version": "1.11.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -31,8 +31,8 @@
     "test:coverage": "yarn test --coverage"
   },
   "dependencies": {
-    "@percy/env": "1.10.3",
-    "@percy/logger": "1.10.3"
+    "@percy/env": "1.11.0",
+    "@percy/logger": "1.11.0"
   },
-  "gitHead": "a9858d20a9b9708da0464c0617b32b2ee1c97433"
+  "gitHead": "0a5043cd677266390889063924f342af9b347055"
 }

package/test/helpers.js

@@ -120,6 +120,14 @@ export const api = {
           }
         }
       }
+    }],
+
+    '/snapshots/4567/comparisons': ({ body }) => [201, {
+      data: {
+        id: '891011',
+        attributes: body.attributes,
+        relationships: body.relationships
+      }
     }]
   },