@argos-ci/playwright 7.7.0 → 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
@@ -179,6 +209,12 @@ export declare function getCSPScriptHash(): string;
179
209
  type MetadataConfig = {
180
210
  sdk: ScreenshotMetadata["sdk"];
181
211
  playwrightLibraries: string[];
212
+ /**
213
+ * Automation library resolved by the SDK itself, which wins over
214
+ * `playwrightLibraries`: for packages this one cannot resolve from its own
215
+ * install location, like a user's Storybook under strict package managers.
216
+ */
217
+ automationLibrary?: ScreenshotMetadata["automationLibrary"];
182
218
  url?: string;
183
219
  test?: ScreenshotMetadata["test"];
184
220
  story?: ScreenshotMetadata["story"];
package/dist/index.mjs CHANGED
@@ -43,7 +43,9 @@ function getMetadataOverrides() {
43
43
  * Get the name and version of the automation library.
44
44
  */
45
45
  async function getAutomationLibraryMetadata() {
46
- const libraries = metadataConfigStorage.getStore()?.playwrightLibraries ?? DEFAULT_PLAYWRIGHT_LIBRARIES;
46
+ const metadataConfig = metadataConfigStorage.getStore();
47
+ if (metadataConfig?.automationLibrary) return metadataConfig.automationLibrary;
48
+ const libraries = metadataConfig?.playwrightLibraries ?? DEFAULT_PLAYWRIGHT_LIBRARIES;
47
49
  for (const name of libraries) {
48
50
  const pkgPath = tryResolve(`${name}/package.json`);
49
51
  if (pkgPath) return {
@@ -192,10 +194,28 @@ function getPage(handler) {
192
194
  /**
193
195
  * Get the viewport size.
194
196
  */
195
- function getViewportSize(page) {
197
+ async function getViewportSize(page) {
196
198
  const viewportSize = page.viewportSize();
197
- if (!viewportSize) throw new Error("Snapshots can't be taken without a viewport.");
198
- 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;
199
219
  }
200
220
  /**
201
221
  * Sets the viewport size and waits for the visual viewport to match the specified dimensions.
@@ -245,28 +265,22 @@ async function getPathAndMetadata(args) {
245
265
  const overrides = getMetadataOverrides();
246
266
  const path = useArgosReporter && testInfo ? testInfo.outputPath("argos", `${names.name}${extension}`) : resolve(root, `${names.name}${extension}`);
247
267
  const dir = dirname(path);
248
- const [colorScheme, mediaType, libMetadata, testMetadata] = await Promise.all([
268
+ const [colorScheme, mediaType, libMetadata, testMetadata, viewportSize, browser] = await Promise.all([
249
269
  handler.evaluate(() => window.__ARGOS__.getColorScheme()),
250
270
  handler.evaluate(() => window.__ARGOS__.getMediaType()),
251
271
  getLibraryMetadata(),
252
272
  getTestMetadata(testInfo),
273
+ checkIsFrame(handler) ? null : getViewportSize(handler),
274
+ getBrowserMetadata(getPage(handler)),
253
275
  dir !== root ? mkdir(dir, { recursive: true }) : null
254
276
  ]);
255
- const viewportSize = checkIsFrame(handler) ? null : getViewportSize(handler);
256
- const browser = getPage(handler).context().browser();
257
- if (!browser) throw new Error("Can't take screenshots without a browser.");
258
- const browserName = browser.browserType().name();
259
- const browserVersion = browser.version();
260
277
  const metadata = {
261
278
  url: overrides?.url ?? handler.url(),
262
279
  colorScheme,
263
280
  mediaType,
264
281
  test: testMetadata,
265
282
  story: overrides?.story,
266
- browser: {
267
- name: browserName,
268
- version: browserVersion
269
- },
283
+ browser,
270
284
  ...libMetadata
271
285
  };
272
286
  const viewport = viewportSize ?? getMetadataOverrides()?.viewport;
@@ -305,6 +319,20 @@ async function beforeEach(handler, context) {
305
319
  };
306
320
  }
307
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
+ /**
308
336
  * Increase the timeout for the test x3.
309
337
  * Returns a function to reset the timeout.
310
338
  */
@@ -440,10 +468,14 @@ const DEFAULT_SCREENSHOT_ROOT = "./screenshots";
440
468
  * @see https://argos-ci.com/docs/reference/playwright
441
469
  */
442
470
  async function argosScreenshot(handler, name, options = {}) {
443
- 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;
444
472
  const baseNames = normalizeBaseNames(baseName);
445
473
  if (!handler) throw new Error("A Playwright `handler` object is required.");
446
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
+ }
447
479
  const screenshotTarget = typeof element === "string" ? handler.locator(element, {
448
480
  has,
449
481
  hasText,
@@ -458,7 +490,6 @@ async function argosScreenshot(handler, name, options = {}) {
458
490
  useArgosReporter,
459
491
  root
460
492
  });
461
- const originalViewportSize = checkIsFrame(handler) ? null : getViewportSize(handler);
462
493
  const fullPage = options.fullPage !== void 0 ? options.fullPage : screenshotTarget === handler;
463
494
  const context = getStabilizationContext(options);
464
495
  const afterAll = await beforeAll(handler, context, { disableHover });
@@ -483,6 +514,10 @@ async function argosScreenshot(handler, name, options = {}) {
483
514
  stabilize: stabilizationOptions ?? options.stabilize
484
515
  })) });
485
516
  await waitForReadiness(handler, context);
517
+ await applyHelpers(handler, {
518
+ hide,
519
+ remove
520
+ });
486
521
  const afterEach = await beforeEach(handler, context);
487
522
  await waitForReadiness(handler, context);
488
523
  const [snapshotPath] = await Promise.all([
@@ -507,9 +542,9 @@ async function argosScreenshot(handler, name, options = {}) {
507
542
  path: screenshotPath,
508
543
  type: "png",
509
544
  fullPage,
510
- mask: [handler.locator("[data-visual-test=\"blackout\"]")],
511
545
  animations: "disabled",
512
- ...playwrightOptions
546
+ ...playwrightOptions,
547
+ mask: ["[data-visual-test=\"blackout\"]", ...mask].map((target) => toLocator(handler, target))
513
548
  }),
514
549
  writeMetadata(screenshotPath, metadata)
515
550
  ]);
@@ -542,15 +577,15 @@ async function argosScreenshot(handler, name, options = {}) {
542
577
  };
543
578
  const allAttachments = [];
544
579
  if (viewports) {
545
- if (checkIsFrame(handler)) throw new Error(`viewports option is not supported with an iframe`);
580
+ const page = getPage(handler);
581
+ const originalViewportSize = page.viewportSize();
546
582
  for (const viewport of viewports) {
547
583
  const viewportSize = resolveViewport(viewport);
548
- await setViewportSize(handler, viewportSize);
584
+ await setViewportSize(page, viewportSize);
549
585
  const attachments = await stabilizeAndScreenshot(getScreenshotName(name, { viewportWidth: viewportSize.width }), baseNames?.map((baseName) => getScreenshotName(baseName, { viewportWidth: viewportSize.width })) ?? null);
550
586
  allAttachments.push(...attachments);
551
587
  }
552
- if (!originalViewportSize) throw new Error(`Invariant: viewport size must be saved`);
553
- await setViewportSize(handler, originalViewportSize);
588
+ if (originalViewportSize) await setViewportSize(page, originalViewportSize);
554
589
  } else {
555
590
  const attachments = await stabilizeAndScreenshot(name, baseNames);
556
591
  allAttachments.push(...attachments);
package/dist/reporter.mjs CHANGED
@@ -33,7 +33,9 @@ const DEFAULT_PLAYWRIGHT_LIBRARIES = [
33
33
  * Get the name and version of the automation library.
34
34
  */
35
35
  async function getAutomationLibraryMetadata() {
36
- const libraries = metadataConfigStorage.getStore()?.playwrightLibraries ?? DEFAULT_PLAYWRIGHT_LIBRARIES;
36
+ const metadataConfig = metadataConfigStorage.getStore();
37
+ if (metadataConfig?.automationLibrary) return metadataConfig.automationLibrary;
38
+ const libraries = metadataConfig?.playwrightLibraries ?? DEFAULT_PLAYWRIGHT_LIBRARIES;
37
39
  for (const name of libraries) {
38
40
  const pkgPath = tryResolve(`${name}/package.json`);
39
41
  if (pkgPath) return {
@@ -181,7 +183,7 @@ const RECOMMENDED_CHROMIUM_ARGS = ["--disable-lcd-text", "--font-render-hinting=
181
183
  */
182
184
  function checkLaunchOptions(config) {
183
185
  for (const project of config.projects) {
184
- if ((project.use.browserName ?? "chromium") !== "chromium") continue;
186
+ if ((project.use.browserName ?? project.use.defaultBrowserType ?? "chromium") !== "chromium") continue;
185
187
  const args = project.use.launchOptions?.args ?? [];
186
188
  const missing = RECOMMENDED_CHROMIUM_ARGS.filter((arg) => !args.includes(arg));
187
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.0",
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.6",
52
- "@argos-ci/util": "4.2.1",
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": "4f0edc08d8549534dd3a682bbe034ebcb604bddf"
77
+ "gitHead": "e6023fc9502dba025911c8e4fd5dab829b729125"
73
78
  }