@applitools/visual-grid-cli-utils 1.21.43 → 1.21.45

package/README.md

@@ -13,3 +13,20 @@ npm install -g @applitools/visual-grid-cli-utils
 ## Using it
 
 * To get all the options, do `visual-grid-cli-utils --help`
+
+### `view-rendering <render-id> --raw`
+
+* Instead of printing the view-rendering URL, `--raw` fetches a time-limited **signed URL to the
+  render's raw (unparsed) root-DOM CDT** and prints it together with its expiration.
+* It calls the rendering-api-app `/render` endpoint with the `rawCdtOnly` option; the server
+  enforces ownership (you must own the render, or be an admin).
+* Only renders created on or after **2026-06-26** are supported — the raw root-DOM CDT path
+  (`rdvsMetadata.rootDomRawResourcePath`) started being recorded with AD-14694. The feature is
+  not supported for renders created before then; the command prints a `404` hint explaining this.
+
+```sh
+vg-cli view-rendering <render-id> --raw
+# Raw root-DOM CDT URL:
+# https://storage.googleapis.com/rg-raw-.../<accountId>/<resourceId>?X-Goog-Signature=...
+# Expires at: 2026-06-28T12:00:00.000Z (TTL 900s)
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applitools/visual-grid-cli-utils",
-  "version": "1.21.43",
+  "version": "1.21.45",
   "description": "",
   "main": "src/visual-grid-cli-utils.js",
   "engines": {

package/src/commons/build-safari-emulation-info.js

@@ -0,0 +1,27 @@
+'use strict'
+
+function buildSafariEmulationInfo({
+  safariEmulationDeviceName,
+  safariEmulationOrientation,
+  safariEmulationViewport,
+  safariEmulationPixelRatio,
+  safariEmulationUserAgent,
+}) {
+  const anyFlagSet = !!(
+    safariEmulationDeviceName ||
+    safariEmulationViewport ||
+    safariEmulationPixelRatio !== undefined ||
+    safariEmulationUserAgent
+  )
+  if (!anyFlagSet) return undefined
+
+  const info = {}
+  if (safariEmulationDeviceName) info.deviceName = safariEmulationDeviceName
+  if (safariEmulationViewport) info.viewport = safariEmulationViewport
+  if (safariEmulationPixelRatio !== undefined) info.pixelRatio = safariEmulationPixelRatio
+  if (safariEmulationUserAgent) info.userAgent = safariEmulationUserAgent
+  info.screenOrientation = safariEmulationOrientation || 'portrait'
+  return info
+}
+
+module.exports = buildSafariEmulationInfo

package/src/commons/fetch-raw-cdt-url.js

@@ -0,0 +1,34 @@
+'use strict'
+const {fetch: defaultFetch} = require('@applitools/http-commons')
+
+// Fetch a time-limited signed URL for a render's raw (unparsed) root-DOM CDT by calling the
+// rendering-api-app `/render` endpoint with the `rawCdtOnly` flag (AD-14682). The endpoint
+// returns `{ url, expiresAt, ttlSeconds }` and enforces ownership server-side. `fetch` is
+// injectable for testing; it defaults to the shared http-commons fetch.
+async function fetchRawCdtUrl({vgUrl, renderId, authToken, agentId, fetch = defaultFetch}) {
+  const renderUrl = new URL('./render', vgUrl)
+  const response = await fetch(renderUrl, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Auth-Token': authToken,
+    },
+    body: JSON.stringify({
+      reRenderId: renderId,
+      rawCdtOnly: true,
+      agentId,
+      options: {
+        rawCdtOnly: true,
+      },
+    }),
+  })
+
+  if (!response.ok) {
+    const errorBody = await response.text()
+    throw new Error(`Failed to fetch raw CDT URL - HTTP ${response.status}: ${errorBody}`)
+  }
+
+  return response.json()
+}
+
+module.exports = fetchRawCdtUrl

package/src/commons/parse-viewport.js

@@ -0,0 +1,11 @@
+'use strict'
+
+function parseViewport(arg) {
+  const match = /^(\d+)x(\d+)$/i.exec(arg)
+  if (!match) {
+    throw new Error(`invalid viewport "${arg}". Expected format: WIDTHxHEIGHT (e.g., 393x695)`)
+  }
+  return {width: parseInt(match[1], 10), height: parseInt(match[2], 10)}
+}
+
+module.exports = parseViewport

package/src/job-info.js

@@ -3,6 +3,7 @@ const {fetchAsJsonWithJsonBody} = require('@applitools/http-commons')
 const createSession = require('./commons/create-session')
 const {convertBrowserNameToCanary} = require('./commons/parse-browser')
 const parseJson = require('./commons/parse-json.js')
+const buildSafariEmulationInfo = require('./commons/build-safari-emulation-info')
 
 async function main({
   apiKey,
@@ -13,6 +14,11 @@ async function main({
   native,
   deviceEmulation,
   deviceOrientation,
+  safariEmulationDeviceName,
+  safariEmulationOrientation,
+  safariEmulationViewport,
+  safariEmulationPixelRatio,
+  safariEmulationUserAgent,
   iosDeviceName,
   iosDeviceOrientation,
   androidDeviceName,
@@ -29,6 +35,14 @@ async function main({
   options.chromeHeadless = headless
   const vgUrl = process.env.VG_URL || 'https://render-wus.applitools.com'
 
+  const safariEmulationInfo = buildSafariEmulationInfo({
+    safariEmulationDeviceName,
+    safariEmulationOrientation,
+    safariEmulationViewport,
+    safariEmulationPixelRatio,
+    safariEmulationUserAgent,
+  })
+
   const {webhook, authToken} = await createSession(apiKey, serverUrl)
 
   const renderInfoUrl = new URL('./job-info', vgUrl)
@@ -38,9 +52,11 @@ async function main({
       accountOverride,
       webhook,
       renderInfo: {
-        emulationInfo: deviceEmulation
-          ? {deviceName: deviceEmulation, screenOrientation: deviceOrientation}
-          : undefined,
+        emulationInfo:
+          safariEmulationInfo ||
+          (deviceEmulation
+            ? {deviceName: deviceEmulation, screenOrientation: deviceOrientation}
+            : undefined),
         iosDeviceInfo: iosDeviceName
           ? {
               name: iosDeviceName,
@@ -56,8 +72,8 @@ async function main({
             }
           : undefined,
         vhsType: androidDeviceName ? androidVhsType : undefined,
-        width: deviceEmulation || iosDeviceName ? undefined : width,
-        height: deviceEmulation || iosDeviceName ? undefined : height,
+        width: deviceEmulation || iosDeviceName || safariEmulationInfo ? undefined : width,
+        height: deviceEmulation || iosDeviceName || safariEmulationInfo ? undefined : height,
         target: 'full-page',
       },
       agentId: `visual-grid-cli-utils/${require('../package.json').version}`,

package/src/rerender.js

@@ -12,6 +12,7 @@ const {convertBrowserNameToCanary} = require('./commons/parse-browser')
 const parseJson = require('./commons/parse-json.js')
 const normalizeChainedSelectorsArray = require('./commons/normalizeChainedSelectorsArray')
 const normalizeChainedSelectorsToFindRegionsForArray = require('./commons/normalizeChainedSelectorsToFindRegionsForArray')
+const buildSafariEmulationInfo = require('./commons/build-safari-emulation-info')
 
 async function main({
   apiKey,
@@ -26,6 +27,11 @@ async function main({
   headless,
   deviceEmulation,
   deviceOrientation,
+  safariEmulationDeviceName,
+  safariEmulationOrientation,
+  safariEmulationViewport,
+  safariEmulationPixelRatio,
+  safariEmulationUserAgent,
   androidDeviceName,
   androidVersion,
   androidDeviceOrientation,
@@ -64,6 +70,14 @@ async function main({
   options.chromeHeadless = headless
   const vgUrl = process.env.VG_URL || 'https://render-wus.applitools.com'
 
+  const safariEmulationInfo = buildSafariEmulationInfo({
+    safariEmulationDeviceName,
+    safariEmulationOrientation,
+    safariEmulationViewport,
+    safariEmulationPixelRatio,
+    safariEmulationUserAgent,
+  })
+
   const finalOutputFile = outputFile || path.join(fs.mkdtempSync(os.tmpdir() + '/'), 'rerender.png')
   const domSnapshotOutputFile = finalOutputFile.replace(/\.[a-zA-Z0-0]+$/, '.json')
   const domSnapshotHtml = finalOutputFile.replace(/\.[a-zA-Z0-0]+$/, '.html')
@@ -75,9 +89,11 @@ async function main({
     accountOverride,
     webhook,
     renderInfo: {
-      emulationInfo: deviceEmulation
-        ? {deviceName: deviceEmulation, screenOrientation: deviceOrientation}
-        : undefined,
+      emulationInfo:
+        safariEmulationInfo ||
+        (deviceEmulation
+          ? {deviceName: deviceEmulation, screenOrientation: deviceOrientation}
+          : undefined),
       iosDeviceInfo: iosDeviceName
         ? {
             name: iosDeviceName,
@@ -99,8 +115,8 @@ async function main({
           }
         : undefined,
       vhsType: androidDeviceName ? androidVhsType : undefined,
-      width: deviceEmulation || iosDeviceName ? undefined : width,
-      height: deviceEmulation || iosDeviceName ? undefined : height,
+      width: deviceEmulation || iosDeviceName || safariEmulationInfo ? undefined : width,
+      height: deviceEmulation || iosDeviceName || safariEmulationInfo ? undefined : height,
       target,
       selector: selector
         ? {selector, type: selector.startsWith('//') ? 'xpath' : 'css'}

package/src/view-rendering.js

@@ -3,6 +3,7 @@ const {exec} = require('child_process')
 const retry = require('p-retry')
 const createSession = require('./commons/create-session')
 const calculateViewRenderingUrl = require('./commons/view-rendering-url')
+const fetchRawCdtUrl = require('./commons/fetch-raw-cdt-url')
 const {fetch, throwErrorFromBadStatus} = require('@applitools/http-commons')
 const fs = require('fs')
 
@@ -52,7 +53,9 @@ async function waitForParsedStatus(vgUrl, renderId, authToken, waitTimeout = 5 *
   )
 }
 
-async function tryNewViewRenderingEndpoint(vgUrl, renderId, authToken, apiKey, serverUrl) {
+// `_authToken` is unused — this path mints its own session below; the `_` prefix satisfies the
+// no-unused-vars rule (was a pre-existing lint error on this line before the --raw change).
+async function tryNewViewRenderingEndpoint(vgUrl, renderId, _authToken, apiKey, serverUrl) {
   try {
     console.log(`[1/3] Starting resource parsing for render: ${renderId}`)
     // Step 1: Call rerender API with parseResourcesOnly flag
@@ -121,6 +124,7 @@ async function main({
   serverUrl,
   accountOverride,
   downloadVhsFolder,
+  raw,
 }) {
   if (!apiKey) {
     throw new Error(
@@ -134,6 +138,43 @@ async function main({
 
   const vgUrl = process.env.VG_URL || 'https://render-wus.applitools.com'
 
+  // --raw: fetch a signed URL to the render's raw root-DOM CDT (via the rawCdtOnly /render
+  // option, AD-14682) and print it + its expiration, instead of the view-rendering URL.
+  if (raw) {
+    const agentId = `visual-grid-cli-utils/${require('../package.json').version}`
+    let rawCdt
+    try {
+      rawCdt = await fetchRawCdtUrl({
+        vgUrl,
+        renderId,
+        authToken: finalAuthToken,
+        agentId,
+      })
+    } catch (err) {
+      // A 404 most commonly means the render has no stored raw root-DOM CDT path. That path
+      // (rdvsMetadata.rootDomRawResourcePath) only started being recorded with AD-14694, so
+      // the feature isn't supported for renders created before then — surface a gentle hint.
+      if (String(err.message).includes('HTTP 404')) {
+        console.log('\n⚠ No raw root-DOM CDT URL is available for this render (404).')
+        console.log(
+          '  This feature supports renders created on or after 2026-06-26; it is not supported',
+        )
+        console.log('  for renders created before then.')
+        console.log(`\n  Server response: ${err.message}`)
+        return
+      }
+      throw err
+    }
+
+    const {url, expiresAt, ttlSeconds} = rawCdt
+    console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
+    console.log('Raw root-DOM CDT URL:')
+    console.log(url)
+    console.log(`Expires at: ${expiresAt} (TTL ${ttlSeconds}s)`)
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
+    return
+  }
+
   // Try new view-rendering endpoint with rerender API
   const result = await tryNewViewRenderingEndpoint(
     vgUrl,

package/src/visual-grid-cli-utils.js

@@ -2,6 +2,7 @@
 const yargs = require('yargs')
 const {parseBrowser} = require('./commons/parse-browser')
 const parseRegion = require('./commons/parse-region')
+const parseViewport = require('./commons/parse-viewport')
 const splitApiKey = require('./commons/split-api-key')
 
 async function main(argv, {shouldExitOnError = false} = {}) {
@@ -39,6 +40,12 @@ async function main(argv, {shouldExitOnError = false} = {}) {
         .option('download-vhs-folder', {
           describe: 'Specify a folder to which download the vhs file (in case of VHS snapshot)',
           type: 'string',
+        })
+        .option('raw', {
+          describe:
+            "fetch a signed URL to the render's raw root-DOM CDT (and its expiration) instead of the view-rendering url",
+          default: false,
+          type: 'boolean',
         }),
     )
     .command('view-resource <hash>', 'view resource url', (yargs) =>
@@ -128,6 +135,29 @@ async function main(argv, {shouldExitOnError = false} = {}) {
           choices: ['portrait', 'landscape'],
           default: 'portrait',
         })
+        .option('safari-emulation-device-name', {
+          describe: 'the device name to use for Safari emulation (e.g., "iPhone 16")',
+          type: 'string',
+        })
+        .option('safari-emulation-orientation', {
+          describe: 'portrait or landscape for Safari emulation',
+          type: 'string',
+          choices: ['portrait', 'landscape'],
+          default: 'portrait',
+        })
+        .option('safari-emulation-viewport', {
+          describe: 'viewport for Safari emulation, in WIDTHxHEIGHT format (e.g., 393x695)',
+          type: 'string',
+          coerce: parseViewport,
+        })
+        .option('safari-emulation-pixel-ratio', {
+          describe: 'device pixel ratio for Safari emulation (e.g., 3)',
+          type: 'number',
+        })
+        .option('safari-emulation-user-agent', {
+          describe: 'user-agent string for Safari emulation',
+          type: 'string',
+        })
         .option('android-device-name', {
           describe: 'the name of the Android device to use',
           type: 'string',
@@ -491,6 +521,29 @@ async function main(argv, {shouldExitOnError = false} = {}) {
           choices: ['portrait', 'landscape'],
           default: 'portrait',
         })
+        .option('safari-emulation-device-name', {
+          describe: 'the device name to use for Safari emulation (e.g., "iPhone 16")',
+          type: 'string',
+        })
+        .option('safari-emulation-orientation', {
+          describe: 'portrait or landscape for Safari emulation',
+          type: 'string',
+          choices: ['portrait', 'landscape'],
+          default: 'portrait',
+        })
+        .option('safari-emulation-viewport', {
+          describe: 'viewport for Safari emulation, in WIDTHxHEIGHT format (e.g., 393x695)',
+          type: 'string',
+          coerce: parseViewport,
+        })
+        .option('safari-emulation-pixel-ratio', {
+          describe: 'device pixel ratio for Safari emulation (e.g., 3)',
+          type: 'number',
+        })
+        .option('safari-emulation-user-agent', {
+          describe: 'user-agent string for Safari emulation',
+          type: 'string',
+        })
         .option('ios-device-name', {
           describe: 'the name of the iOS device to use',
           type: 'string',
@@ -810,7 +863,7 @@ async function main(argv, {shouldExitOnError = false} = {}) {
 
   const args = /**@type {object}*/ (commandLineOptions.parse())
 
-  if (args._ && args._[0]) {
+  if (args._ && args._[0] && !args.help) {
     try {
       return await require(`./${args._[0]}`)(normalizeArgs(args))
     } catch (err) {