@argos-ci/playwright 7.7.1 → 7.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -64,7 +64,7 @@ options?: ArgosSnapshotOptions): Promise<ArgosAttachment[]>;
64
64
  //#endregion
65
65
  //#region src/screenshot.d.ts
66
66
  type LocatorOptions = Parameters<Page["locator"]>[1];
67
- type ScreenshotOptions<TBase extends PageScreenshotOptions | LocatorScreenshotOptions> = Omit<TBase, "encoding" | "type" | "omitBackground" | "path">;
67
+ type ScreenshotOptions<TBase extends PageScreenshotOptions | LocatorScreenshotOptions> = Omit<TBase, "encoding" | "type" | "omitBackground" | "path" | "mask">;
68
68
  type ArgosScreenshotOptions = {
69
69
  /**
70
70
  * `Locator` or string selector of the element to take a screenshot of.
@@ -73,6 +73,7 @@ type ArgosScreenshotOptions = {
73
73
  element?: string | ElementHandle | Locator;
74
74
  /**
75
75
  * Viewports to take screenshots of.
76
+ * Not supported on pages without a viewport, such as Electron windows.
76
77
  */
77
78
  viewports?: ViewportOption[];
78
79
  /**
@@ -87,6 +88,35 @@ type ArgosScreenshotOptions = {
87
88
  * Custom CSS evaluated during the screenshot process.
88
89
  */
89
90
  argosCSS?: string;
91
+ /**
92
+ * Elements to hide from the screenshot, as `Locator`s or string selectors.
93
+ * Hidden elements keep their space in the layout, like with the
94
+ * `data-visual-test="transparent"` helper.
95
+ * Selectors that match nothing are ignored.
96
+ * @example
97
+ * argosScreenshot(page, "home", {
98
+ * hide: ["#clock", page.getByTestId("avatar")],
99
+ * })
100
+ */
101
+ hide?: (string | Locator)[];
102
+ /**
103
+ * Elements to remove from the screenshot, as `Locator`s or string selectors.
104
+ * Removed elements no longer take space in the layout, like with the
105
+ * `data-visual-test="removed"` helper.
106
+ * Selectors that match nothing are ignored.
107
+ * @example
108
+ * argosScreenshot(page, "home", { remove: [".cookie-banner"] })
109
+ */
110
+ remove?: (string | Locator)[];
111
+ /**
112
+ * Elements to cover with a box when the screenshot is taken, as `Locator`s
113
+ * or string selectors, like with the `data-visual-test="blackout"` helper.
114
+ * Selectors that match nothing are ignored.
115
+ * @see https://playwright.dev/docs/api/class-page#page-screenshot-option-mask
116
+ * @example
117
+ * argosScreenshot(page, "home", { mask: ["#map", page.getByRole("img")] })
118
+ */
119
+ mask?: (string | Locator)[];
90
120
  /**
91
121
  * Disable hover effects by moving the mouse to the top-left corner of the document.
92
122
  * @default true
package/dist/index.mjs CHANGED
@@ -194,10 +194,28 @@ function getPage(handler) {
194
194
  /**
195
195
  * Get the viewport size.
196
196
  */
197
- function getViewportSize(page) {
197
+ async function getViewportSize(page) {
198
198
  const viewportSize = page.viewportSize();
199
- if (!viewportSize) throw new Error("Snapshots can't be taken without a viewport.");
200
- return viewportSize;
199
+ if (viewportSize) return viewportSize;
200
+ return page.evaluate(() => ({
201
+ width: window.innerWidth,
202
+ height: window.innerHeight
203
+ }));
204
+ }
205
+ /**
206
+ * Get the browser running the page, or `undefined` if it can't be identified.
207
+ */
208
+ async function getBrowserMetadata(page) {
209
+ const browser = page.context().browser();
210
+ if (browser) return {
211
+ name: browser.browserType().name(),
212
+ version: browser.version()
213
+ };
214
+ const electronVersion = (await page.evaluate(() => navigator.userAgent)).match(/\bElectron\/(\S+)/)?.[1];
215
+ return electronVersion ? {
216
+ name: "electron",
217
+ version: electronVersion
218
+ } : void 0;
201
219
  }
202
220
  /**
203
221
  * Sets the viewport size and waits for the visual viewport to match the specified dimensions.
@@ -247,28 +265,22 @@ async function getPathAndMetadata(args) {
247
265
  const overrides = getMetadataOverrides();
248
266
  const path = useArgosReporter && testInfo ? testInfo.outputPath("argos", `${names.name}${extension}`) : resolve(root, `${names.name}${extension}`);
249
267
  const dir = dirname(path);
250
- const [colorScheme, mediaType, libMetadata, testMetadata] = await Promise.all([
268
+ const [colorScheme, mediaType, libMetadata, testMetadata, viewportSize, browser] = await Promise.all([
251
269
  handler.evaluate(() => window.__ARGOS__.getColorScheme()),
252
270
  handler.evaluate(() => window.__ARGOS__.getMediaType()),
253
271
  getLibraryMetadata(),
254
272
  getTestMetadata(testInfo),
273
+ checkIsFrame(handler) ? null : getViewportSize(handler),
274
+ getBrowserMetadata(getPage(handler)),
255
275
  dir !== root ? mkdir(dir, { recursive: true }) : null
256
276
  ]);
257
- const viewportSize = checkIsFrame(handler) ? null : getViewportSize(handler);
258
- const browser = getPage(handler).context().browser();
259
- if (!browser) throw new Error("Can't take screenshots without a browser.");
260
- const browserName = browser.browserType().name();
261
- const browserVersion = browser.version();
262
277
  const metadata = {
263
278
  url: overrides?.url ?? handler.url(),
264
279
  colorScheme,
265
280
  mediaType,
266
281
  test: testMetadata,
267
282
  story: overrides?.story,
268
- browser: {
269
- name: browserName,
270
- version: browserVersion
271
- },
283
+ browser,
272
284
  ...libMetadata
273
285
  };
274
286
  const viewport = viewportSize ?? getMetadataOverrides()?.viewport;
@@ -307,6 +319,20 @@ async function beforeEach(handler, context) {
307
319
  };
308
320
  }
309
321
  /**
322
+ * Get the `Locator` of a string selector, or the `Locator` itself.
323
+ */
324
+ function toLocator(handler, target) {
325
+ return typeof target === "string" ? handler.locator(target) : target;
326
+ }
327
+ /**
328
+ * Apply the `hide` and `remove` options until `afterEach` runs, as if the
329
+ * matched elements had the `data-visual-test` helper attribute.
330
+ */
331
+ async function applyHelpers(handler, options) {
332
+ const apply = (targets = [], helper) => targets.map((target) => toLocator(handler, target).evaluateAll((elements, helper) => window.__ARGOS__.applyHelper(elements, helper), helper));
333
+ await Promise.all([...apply(options.hide, "transparent"), ...apply(options.remove, "removed")]);
334
+ }
335
+ /**
310
336
  * Increase the timeout for the test x3.
311
337
  * Returns a function to reset the timeout.
312
338
  */
@@ -442,10 +468,14 @@ const DEFAULT_SCREENSHOT_ROOT = "./screenshots";
442
468
  * @see https://argos-ci.com/docs/reference/playwright
443
469
  */
444
470
  async function argosScreenshot(handler, name, options = {}) {
445
- const { element, has, hasText, hasNot, hasNotText, viewports, argosCSS: _argosCSS, root = DEFAULT_SCREENSHOT_ROOT, ariaSnapshot, disableHover = true, baseName, ...playwrightOptions } = options;
471
+ const { element, has, hasText, hasNot, hasNotText, viewports, argosCSS: _argosCSS, root = DEFAULT_SCREENSHOT_ROOT, ariaSnapshot, disableHover = true, baseName, hide, remove, mask = [], ...playwrightOptions } = options;
446
472
  const baseNames = normalizeBaseNames(baseName);
447
473
  if (!handler) throw new Error("A Playwright `handler` object is required.");
448
474
  if (!name) throw new Error("The `name` argument is required.");
475
+ if (viewports) {
476
+ if (checkIsFrame(handler)) throw new Error(`viewports option is not supported with an iframe`);
477
+ if (!handler.viewportSize()) throw new Error(`viewports option is not supported on a page without a viewport, such as an Electron window`);
478
+ }
449
479
  const screenshotTarget = typeof element === "string" ? handler.locator(element, {
450
480
  has,
451
481
  hasText,
@@ -460,7 +490,6 @@ async function argosScreenshot(handler, name, options = {}) {
460
490
  useArgosReporter,
461
491
  root
462
492
  });
463
- const originalViewportSize = checkIsFrame(handler) ? null : getViewportSize(handler);
464
493
  const fullPage = options.fullPage !== void 0 ? options.fullPage : screenshotTarget === handler;
465
494
  const context = getStabilizationContext(options);
466
495
  const afterAll = await beforeAll(handler, context, { disableHover });
@@ -485,6 +514,10 @@ async function argosScreenshot(handler, name, options = {}) {
485
514
  stabilize: stabilizationOptions ?? options.stabilize
486
515
  })) });
487
516
  await waitForReadiness(handler, context);
517
+ await applyHelpers(handler, {
518
+ hide,
519
+ remove
520
+ });
488
521
  const afterEach = await beforeEach(handler, context);
489
522
  await waitForReadiness(handler, context);
490
523
  const [snapshotPath] = await Promise.all([
@@ -509,9 +542,9 @@ async function argosScreenshot(handler, name, options = {}) {
509
542
  path: screenshotPath,
510
543
  type: "png",
511
544
  fullPage,
512
- mask: [handler.locator("[data-visual-test=\"blackout\"]")],
513
545
  animations: "disabled",
514
- ...playwrightOptions
546
+ ...playwrightOptions,
547
+ mask: ["[data-visual-test=\"blackout\"]", ...mask].map((target) => toLocator(handler, target))
515
548
  }),
516
549
  writeMetadata(screenshotPath, metadata)
517
550
  ]);
@@ -544,15 +577,15 @@ async function argosScreenshot(handler, name, options = {}) {
544
577
  };
545
578
  const allAttachments = [];
546
579
  if (viewports) {
547
- if (checkIsFrame(handler)) throw new Error(`viewports option is not supported with an iframe`);
580
+ const page = getPage(handler);
581
+ const originalViewportSize = page.viewportSize();
548
582
  for (const viewport of viewports) {
549
583
  const viewportSize = resolveViewport(viewport);
550
- await setViewportSize(handler, viewportSize);
584
+ await setViewportSize(page, viewportSize);
551
585
  const attachments = await stabilizeAndScreenshot(getScreenshotName(name, { viewportWidth: viewportSize.width }), baseNames?.map((baseName) => getScreenshotName(baseName, { viewportWidth: viewportSize.width })) ?? null);
552
586
  allAttachments.push(...attachments);
553
587
  }
554
- if (!originalViewportSize) throw new Error(`Invariant: viewport size must be saved`);
555
- await setViewportSize(handler, originalViewportSize);
588
+ if (originalViewportSize) await setViewportSize(page, originalViewportSize);
556
589
  } else {
557
590
  const attachments = await stabilizeAndScreenshot(name, baseNames);
558
591
  allAttachments.push(...attachments);
package/dist/reporter.mjs CHANGED
@@ -183,7 +183,7 @@ const RECOMMENDED_CHROMIUM_ARGS = ["--disable-lcd-text", "--font-render-hinting=
183
183
  */
184
184
  function checkLaunchOptions(config) {
185
185
  for (const project of config.projects) {
186
- if ((project.use.browserName ?? "chromium") !== "chromium") continue;
186
+ if ((project.use.browserName ?? project.use.defaultBrowserType ?? "chromium") !== "chromium") continue;
187
187
  const args = project.use.launchOptions?.args ?? [];
188
188
  const missing = RECOMMENDED_CHROMIUM_ARGS.filter((arg) => !args.includes(arg));
189
189
  if (missing.length > 0) {
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@argos-ci/playwright",
3
3
  "description": "Playwright SDK for visual testing with Argos.",
4
- "version": "7.7.1",
4
+ "version": "7.8.0",
5
5
  "author": "Smooth Code",
6
6
  "license": "MIT",
7
7
  "repository": {
@@ -14,15 +14,20 @@
14
14
  "url": "https://github.com/argos-ci/argos-javascript/issues"
15
15
  },
16
16
  "keywords": [
17
+ "argos",
18
+ "argos-ci",
17
19
  "playwright",
18
20
  "playwright-reporter",
19
- "reporter",
20
21
  "playwright-plugin",
21
- "argos",
22
+ "reporter",
22
23
  "testing",
23
- "visual testing",
24
- "regression",
25
- "visual regression"
24
+ "e2e-testing",
25
+ "visual-testing",
26
+ "visual-regression",
27
+ "visual-regression-testing",
28
+ "screenshot-testing",
29
+ "snapshot-testing",
30
+ "aria-snapshot"
26
31
  ],
27
32
  "publishConfig": {
28
33
  "access": "public"
@@ -47,9 +52,9 @@
47
52
  "node": ">=22.0.0"
48
53
  },
49
54
  "dependencies": {
50
- "@argos-ci/browser": "6.5.0",
51
- "@argos-ci/core": "6.8.7",
52
- "@argos-ci/util": "4.2.2",
55
+ "@argos-ci/browser": "6.6.0",
56
+ "@argos-ci/core": "6.8.8",
57
+ "@argos-ci/util": "4.2.3",
53
58
  "chalk": "^6.0.1",
54
59
  "debug": "^4.4.3"
55
60
  },
@@ -69,5 +74,5 @@
69
74
  "lint": "eslint .",
70
75
  "test": "vitest src"
71
76
  },
72
- "gitHead": "e9d0b2fb39001683230eff86f9c39e0016b5cf27"
77
+ "gitHead": "e6023fc9502dba025911c8e4fd5dab829b729125"
73
78
  }