@argos-ci/playwright 5.0.9 → 5.0.10

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ElementHandle, Locator, Page, PageScreenshotOptions, LocatorScreenshotOptions } from '@playwright/test';
+import { ElementHandle, Locator, Page, PageScreenshotOptions, LocatorScreenshotOptions, Frame } from '@playwright/test';
 import { ViewportOption, StabilizationPluginOptions } from '@argos-ci/browser';
 import { ScreenshotMetadata } from '@argos-ci/util';
 
@@ -19,7 +19,7 @@ type ArgosScreenshotOptions = {
      */
     argosCSS?: string;
     /**
-     * Disable hover effects by moving the mouse to the top-left corner of the page.
+     * Disable hover effects by moving the mouse to the top-left corner of the document.
      * @default true
      */
     disableHover?: boolean;
@@ -59,6 +59,12 @@ type ArgosScreenshotOptions = {
      */
     afterScreenshot?: () => Promise<void> | void;
 } & LocatorOptions & ScreenshotOptions<LocatorScreenshotOptions> & ScreenshotOptions<PageScreenshotOptions>;
+type Attachment = {
+    name: string;
+    contentType: string;
+    path: string;
+};
+type Handler = Page | Frame;
 /**
  * Stabilize the UI and takes a screenshot of the application under test.
  *
@@ -68,9 +74,9 @@ type ArgosScreenshotOptions = {
  */
 declare function argosScreenshot(
 /**
- * Playwright `page` object.
+ * Playwright `page` or `frame` object.
  */
-page: Page, 
+handler: Handler, 
 /**
  * Name of the screenshot. Must be unique.
  */
@@ -78,7 +84,7 @@ name: string,
 /**
  * Options for the screenshot.
  */
-options?: ArgosScreenshotOptions): Promise<void>;
+options?: ArgosScreenshotOptions): Promise<Attachment[]>;
 
 /**
  * Get the CSP script hash.
@@ -88,10 +94,13 @@ declare function getCSPScriptHash(): string;
 type MetadataConfig = {
     sdk: ScreenshotMetadata["sdk"];
     playwrightLibraries: string[];
+    url?: string;
+    test?: ScreenshotMetadata["test"];
+    viewport?: ScreenshotMetadata["viewport"];
 };
 /**
  * Set the metadata config.
  */
 declare function setMetadataConfig(metadata: MetadataConfig): void;
 
-export { type ArgosScreenshotOptions, setMetadataConfig as DO_NOT_USE_setMetadataConfig, argosScreenshot, getCSPScriptHash };
+export { type ArgosScreenshotOptions, type Attachment, setMetadataConfig as DO_NOT_USE_setMetadataConfig, type MetadataConfig, argosScreenshot, getCSPScriptHash };

package/dist/index.js

@@ -42,6 +42,9 @@ var DEFAULT_PLAYWRIGHT_LIBRARIES = [
   "playwright",
   "playwright-core"
 ];
+function getMetadataOverrides() {
+  return metadataConfigStorage.getStore();
+}
 async function getAutomationLibraryMetadata() {
   const metadataConfig = metadataConfigStorage.getStore();
   const libraries = metadataConfig?.playwrightLibraries ?? DEFAULT_PLAYWRIGHT_LIBRARIES;
@@ -81,8 +84,31 @@ async function getLibraryMetadata() {
     sdk
   };
 }
-async function getTestMetadataFromTestInfo(testInfo) {
+function resolveTestFilePath(filepath, repositoryPath) {
+  if (!repositoryPath) {
+    return filepath;
+  }
+  return relative(repositoryPath, filepath);
+}
+async function getTestMetadata(testInfo) {
   const repositoryPath = await getGitRepositoryPath();
+  const metadataConfig = metadataConfigStorage.getStore();
+  if (metadataConfig?.test) {
+    return {
+      ...metadataConfig.test,
+      location: metadataConfig.test?.location ? {
+        file: resolveTestFilePath(
+          metadataConfig.test.location.file,
+          repositoryPath
+        ),
+        line: metadataConfig.test.location.line,
+        column: metadataConfig.test.location.column
+      } : void 0
+    };
+  }
+  if (!testInfo) {
+    return null;
+  }
   const testMetadata = {
     id: testInfo.testId,
     title: testInfo.title,
@@ -91,7 +117,7 @@ async function getTestMetadataFromTestInfo(testInfo) {
     retries: testInfo.project.retries,
     repeat: testInfo.repeatEachIndex,
     location: {
-      file: repositoryPath ? relative(repositoryPath, testInfo.file) : testInfo.file,
+      file: resolveTestFilePath(testInfo.file, repositoryPath),
       line: testInfo.line,
       column: testInfo.column
     }
@@ -111,12 +137,12 @@ function checkIsUsingArgosReporter(testInfo) {
 
 // src/screenshot.ts
 var DEFAULT_SCREENSHOT_ROOT = "./screenshots";
-async function injectArgos(page) {
-  const injected = await page.evaluate(
+async function injectArgos(handler) {
+  const injected = await handler.evaluate(
     () => typeof window.__ARGOS__ !== "undefined"
   );
   if (!injected) {
-    await page.addScriptTag({ content: getGlobalScript() });
+    await handler.addScriptTag({ content: getGlobalScript() });
   }
 }
 async function getTestInfo() {
@@ -127,6 +153,15 @@ async function getTestInfo() {
     return null;
   }
 }
+function checkIsFrame(handler) {
+  return "page" in handler && typeof handler.page === "function";
+}
+function getPage(handler) {
+  if (checkIsFrame(handler)) {
+    return handler.page();
+  }
+  return handler;
+}
 function getViewportSize(page) {
   const viewportSize = page.viewportSize();
   if (!viewportSize) {
@@ -150,30 +185,30 @@ function getStabilizationContext(options) {
     options: stabilize
   };
 }
-async function beforeAll(page, options) {
+async function beforeAll(handler, options) {
   const { disableHover = true } = options;
   const context = getStabilizationContext(options);
-  await page.evaluate(
+  await handler.evaluate(
     (context2) => window.__ARGOS__.beforeAll(context2),
     context
   );
   if (disableHover) {
-    await page.mouse.move(0, 0);
+    await getPage(handler).mouse.move(0, 0);
   }
   return async () => {
-    await page.evaluate(
+    await handler.evaluate(
       () => window.__ARGOS__.afterAll()
     );
   };
 }
-async function beforeEach(page, options) {
+async function beforeEach(handler, options) {
   const context = getStabilizationContext(options);
-  await page.evaluate(
+  await handler.evaluate(
     (context2) => window.__ARGOS__.beforeEach(context2),
     context
   );
   return async () => {
-    await page.evaluate(
+    await handler.evaluate(
       () => window.__ARGOS__.afterEach()
     );
   };
@@ -192,11 +227,11 @@ async function increaseTimeout() {
   }
   return null;
 }
-async function waitForReadiness(page, options) {
+async function waitForReadiness(handler, options) {
   const context = getStabilizationContext(options);
   const timeout = await increaseTimeout();
   try {
-    await page.waitForFunction(
+    await handler.waitForFunction(
       (context2) => {
         const argos = window.__ARGOS__;
         return argos.waitFor(context2);
@@ -206,7 +241,7 @@ async function waitForReadiness(page, options) {
     );
     timeout?.reset();
   } catch (error) {
-    const reasons = await page.evaluate(
+    const reasons = await handler.evaluate(
       (context2) => window.__ARGOS__.getWaitFailureExplanations(
         context2
       ),
@@ -234,7 +269,7 @@ function getScreenshotNames(name, testInfo) {
   }
   return { name, baseName: null };
 }
-async function argosScreenshot(page, name, options = {}) {
+async function argosScreenshot(handler, name, options = {}) {
   const {
     element,
     has,
@@ -244,13 +279,13 @@ async function argosScreenshot(page, name, options = {}) {
     root = DEFAULT_SCREENSHOT_ROOT,
     ...playwrightOptions
   } = options;
-  if (!page) {
-    throw new Error("A Playwright `page` object is required.");
+  if (!handler) {
+    throw new Error("A Playwright `handler` object is required.");
   }
   if (!name) {
     throw new Error("The `name` argument is required.");
   }
-  const handle = typeof element === "string" ? page.locator(element, { has, hasText }) : element ?? page;
+  const screenshotTarget = typeof element === "string" ? handler.locator(element, { has, hasText }) : element ?? (checkIsFrame(handler) ? handler.locator("body") : handler);
   const testInfo = await getTestInfo();
   const useArgosReporter = Boolean(
     testInfo && checkIsUsingArgosReporter(testInfo)
@@ -259,33 +294,33 @@ async function argosScreenshot(page, name, options = {}) {
     // Create the screenshot folder if it doesn't exist
     useArgosReporter ? null : mkdir(root, { recursive: true }),
     // Inject Argos script into the page
-    injectArgos(page)
+    injectArgos(handler)
   ]);
-  const originalViewportSize = getViewportSize(page);
-  const fullPage = options.fullPage !== void 0 ? options.fullPage : handle === page;
-  const afterAll = await beforeAll(page, options);
+  const originalViewportSize = checkIsFrame(handler) ? null : getViewportSize(handler);
+  const fullPage = options.fullPage !== void 0 ? options.fullPage : screenshotTarget === handler;
+  const afterAll = await beforeAll(handler, options);
   const collectMetadata = async (testInfo2) => {
+    const overrides = getMetadataOverrides();
     const [colorScheme, mediaType, libMetadata, testMetadata] = await Promise.all([
-      page.evaluate(
+      handler.evaluate(
         () => window.__ARGOS__.getColorScheme()
       ),
-      page.evaluate(
+      handler.evaluate(
         () => window.__ARGOS__.getMediaType()
       ),
       getLibraryMetadata(),
-      testInfo2 ? getTestMetadataFromTestInfo(testInfo2) : null
+      getTestMetadata(testInfo2)
     ]);
-    const viewportSize = getViewportSize(page);
-    const browser = page.context().browser();
+    const viewportSize = checkIsFrame(handler) ? null : getViewportSize(handler);
+    const browser = getPage(handler).context().browser();
     if (!browser) {
       throw new Error("Can't take screenshots without a browser.");
     }
     const browserName = browser.browserType().name();
     const browserVersion = browser.version();
-    const url = page.url();
+    const url = overrides?.url ?? handler.url();
     const metadata = {
       url,
-      viewport: viewportSize,
       colorScheme,
       mediaType,
       test: testMetadata,
@@ -295,6 +330,10 @@ async function argosScreenshot(page, name, options = {}) {
       },
       ...libMetadata
     };
+    const viewport = viewportSize ?? getMetadataOverrides()?.viewport;
+    if (viewport) {
+      metadata.viewport = viewport;
+    }
     return metadata;
   };
   const stabilizeAndScreenshot = async (name2) => {
@@ -314,53 +353,74 @@ async function argosScreenshot(page, name, options = {}) {
       await mkdir(dirname(screenshotPath), { recursive: true });
     }
     await options.beforeScreenshot?.({
-      runStabilization: (stabilizationOptions) => waitForReadiness(page, {
+      runStabilization: (stabilizationOptions) => waitForReadiness(handler, {
         ...options,
         stabilize: stabilizationOptions ?? options.stabilize
       })
     });
-    await waitForReadiness(page, options);
-    const afterEach = await beforeEach(page, options);
-    await waitForReadiness(page, options);
+    await waitForReadiness(handler, options);
+    const afterEach = await beforeEach(handler, options);
+    await waitForReadiness(handler, options);
     await Promise.all([
-      handle.screenshot({
+      screenshotTarget.screenshot({
         path: screenshotPath,
         type: "png",
         fullPage,
-        mask: [page.locator('[data-visual-test="blackout"]')],
+        mask: [handler.locator('[data-visual-test="blackout"]')],
         animations: "disabled",
         ...playwrightOptions
       }),
       writeMetadata(screenshotPath, metadata)
     ]);
+    const attachments = [
+      {
+        name: getAttachmentName(names.name, "screenshot"),
+        contentType: "image/png",
+        path: screenshotPath
+      },
+      {
+        name: getAttachmentName(names.name, "metadata"),
+        contentType: "application/json",
+        path: getMetadataPath(screenshotPath)
+      }
+    ];
     if (useArgosReporter && testInfo) {
-      await Promise.all([
-        testInfo.attach(getAttachmentName(names.name, "metadata"), {
-          path: getMetadataPath(screenshotPath),
-          contentType: "application/json"
-        }),
-        testInfo.attach(getAttachmentName(names.name, "screenshot"), {
-          path: screenshotPath,
-          contentType: "image/png"
-        })
-      ]);
+      await Promise.all(
+        attachments.map(
+          (attachment) => testInfo.attach(attachment.name, {
+            path: attachment.path,
+            contentType: attachment.contentType
+          })
+        )
+      );
     }
     await afterEach();
     await options.afterScreenshot?.();
+    return attachments;
   };
+  const allAttachments = [];
   if (viewports) {
+    if (checkIsFrame(handler)) {
+      throw new Error(`viewports option is not supported with an iframe`);
+    }
     for (const viewport of viewports) {
       const viewportSize = resolveViewport(viewport);
-      await setViewportSize(page, viewportSize);
-      await stabilizeAndScreenshot(
+      await setViewportSize(handler, viewportSize);
+      const attachments = await stabilizeAndScreenshot(
         getScreenshotName(name, { viewportWidth: viewportSize.width })
       );
+      allAttachments.push(...attachments);
+    }
+    if (!originalViewportSize) {
+      throw new Error(`Invariant: viewport size must be saved`);
     }
-    await setViewportSize(page, originalViewportSize);
+    await setViewportSize(handler, originalViewportSize);
   } else {
-    await stabilizeAndScreenshot(name);
+    const attachments = await stabilizeAndScreenshot(name);
+    allAttachments.push(...attachments);
   }
   await afterAll();
+  return allAttachments;
 }
 
 // src/csp.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@argos-ci/playwright",
   "description": "Playwright SDK for visual testing with Argos.",
-  "version": "5.0.9",
+  "version": "5.0.10",
   "author": "Smooth Code",
   "license": "MIT",
   "repository": {
@@ -47,9 +47,9 @@
     "node": ">=18.16.0"
   },
   "dependencies": {
-    "@argos-ci/browser": "4.2.0",
-    "@argos-ci/core": "3.2.1",
-    "@argos-ci/util": "2.3.2",
+    "@argos-ci/browser": "4.2.1",
+    "@argos-ci/core": "3.2.2",
+    "@argos-ci/util": "2.3.3",
     "chalk": "^5.4.1",
     "debug": "^4.4.0"
   },
@@ -67,5 +67,5 @@
     "check-format": "prettier --check --ignore-unknown --ignore-path=../../.gitignore --ignore-path=../../.prettierignore .",
     "lint": "eslint ."
   },
-  "gitHead": "899956c05cad3211eb2dd030a214a2e0af12e27d"
+  "gitHead": "ecab2281c36828d0c43728e3ed98e1eefe227c99"
 }