PRO-17102 feat: add screenshot dimensions to HTML report and logs

Author: uid11

autotests/configurator/regroupSteps.ts

@@ -5,8 +5,6 @@ import type {LogEvent, Mutable} from 'e2ed/types';
 
 /**
  * Regroup log events (for grouping of `TestRun` steps).
- * This base client function should not use scope variables (except other base functions).
- * @internal
  */
 export const regroupSteps = (logEvents: readonly LogEvent[]): readonly LogEvent[] => {
   const topLevelTypes: readonly LogEventType[] = [

src/README.md

@@ -15,43 +15,44 @@ Modules in the dependency graph should only import the modules above them:
 8. `utils/getHash`
 9. `generators`
 10. `utils/headers`
-11. `utils/viewport`
-12. `utils/parse`
-13. `utils/distanceBetweenSelectors`
-14. `utils/getDurationWithUnits`
-15. `utils/valueToString`
-16. `utils/error`
-17. `utils/asserts`
-18. `utils/object`
-19. `utils/uiMode`
-20. `utils/runLabel`
-21. `utils/clone`
-22. `utils/notIncludedInPackTests`
-23. `utils/userland`
-24. `utils/fn`
-25. `utils/environment`
-26. `utils/packCompiler`
-27. `config`
-28. `utils/config`
-29. `utils/generalLog`
-30. `utils/testFilePaths`
-31. `utils/exit`
-32. `utils/promise`
-33. `utils/resourceUsage`
-34. `utils/fs`
-35. `utils/getGlobalErrorHandler`
-36. `utils/tests`
-37. `utils/end`
-38. `utils/pack`
-39. `useContext`
-40. `context`
-41. `utils/step`
-42. `utils/apiStatistics`
-43. `utils/selectors`
-44. `selectors`
-45. `utils/log`
-46. `step`
-47. `utils/waitForEvents`
-48. `utils/expect`
-49. `expect`
-50. ...
+11. `utils/screenshot`
+12. `utils/viewport`
+13. `utils/parse`
+14. `utils/distanceBetweenSelectors`
+15. `utils/getDurationWithUnits`
+16. `utils/valueToString`
+17. `utils/error`
+18. `utils/asserts`
+19. `utils/object`
+20. `utils/uiMode`
+21. `utils/runLabel`
+22. `utils/clone`
+23. `utils/notIncludedInPackTests`
+24. `utils/userland`
+25. `utils/fn`
+26. `utils/environment`
+27. `utils/packCompiler`
+28. `config`
+29. `utils/config`
+30. `utils/generalLog`
+31. `utils/testFilePaths`
+32. `utils/exit`
+33. `utils/promise`
+34. `utils/resourceUsage`
+35. `utils/fs`
+36. `utils/getGlobalErrorHandler`
+37. `utils/tests`
+38. `utils/end`
+39. `utils/pack`
+40. `useContext`
+41. `context`
+42. `utils/step`
+43. `utils/apiStatistics`
+44. `utils/selectors`
+45. `selectors`
+46. `utils/log`
+47. `step`
+48. `utils/waitForEvents`
+49. `utils/expect`
+50. `expect`
+51. ...

src/actions/takeElementScreenshot.ts

@@ -1,7 +1,12 @@
 import {join} from 'node:path';
 
-import {LogEventType, SCREENSHOTS_DIRECTORY_PATH} from '../constants/internal';
+import {
+  ADDITIONAL_STEP_TIMEOUT,
+  LogEventType,
+  SCREENSHOTS_DIRECTORY_PATH,
+} from '../constants/internal';
 import {step} from '../step';
+import {getDimensionsString, getPngDimensions} from '../utils/screenshot';
 
 import type {Locator} from '@playwright/test';
 
@@ -17,6 +22,7 @@ export const takeElementScreenshot = async (
   options: Options = {},
 ): Promise<void> => {
   const {path: pathToScreenshot, ...optionsWithoutPath} = options;
+  const {timeout} = options;
 
   await step(
     'Take a screenshot of the element',
@@ -26,10 +32,14 @@ export const takeElementScreenshot = async (
         options.path = join(SCREENSHOTS_DIRECTORY_PATH, pathToScreenshot);
       }
 
-      await selector.getPlaywrightLocator().screenshot(options);
+      const screenshot = await selector.getPlaywrightLocator().screenshot(options);
+      const dimensions = getDimensionsString(getPngDimensions(screenshot));
+
+      return {dimensions};
     },
     {
       payload: {pathToScreenshot, ...optionsWithoutPath, selector},
+      ...(timeout !== undefined ? {timeout: timeout + ADDITIONAL_STEP_TIMEOUT} : undefined),
       type: LogEventType.InternalAction,
     },
   );

src/actions/takeScreenshot.ts

@@ -1,8 +1,13 @@
 import {join} from 'node:path';
 
-import {LogEventType, SCREENSHOTS_DIRECTORY_PATH} from '../constants/internal';
+import {
+  ADDITIONAL_STEP_TIMEOUT,
+  LogEventType,
+  SCREENSHOTS_DIRECTORY_PATH,
+} from '../constants/internal';
 import {step} from '../step';
 import {getPlaywrightPage} from '../useContext';
+import {getDimensionsString, getPngDimensions} from '../utils/screenshot';
 
 import type {Page} from '@playwright/test';
 
@@ -13,6 +18,7 @@ type Options = Parameters<Page['screenshot']>[0];
  */
 export const takeScreenshot = async (options: Options = {}): Promise<void> => {
   const {path: pathToScreenshot, ...optionsWithoutPath} = options;
+  const {timeout} = options;
 
   await step(
     'Take a screenshot of the page',
@@ -24,8 +30,15 @@ export const takeScreenshot = async (options: Options = {}): Promise<void> => {
 
       const page = getPlaywrightPage();
 
-      await page.screenshot(options);
+      const screenshot = await page.screenshot(options);
+      const dimensions = getDimensionsString(getPngDimensions(screenshot));
+
+      return {dimensions};
+    },
+    {
+      payload: {pathToScreenshot, ...optionsWithoutPath},
+      ...(timeout !== undefined ? {timeout: timeout + ADDITIONAL_STEP_TIMEOUT} : undefined),
+      type: LogEventType.InternalAction,
     },
-    {payload: {pathToScreenshot, ...optionsWithoutPath}, type: LogEventType.InternalAction},
   );
 };

src/types/index.ts

@@ -47,6 +47,8 @@ export type {
 export type {KeyboardPressKey} from './keyboard';
 export type {Log, LogContext, LogParams, LogPayload, LogTag} from './log';
 export type {
+  Dimensions,
+  DimensionsString,
   MatchScreenshotConfig,
   ScreenshotMeta,
   ToMatchScreenshotOptions,

src/types/internal.ts

@@ -78,10 +78,14 @@ export type {
   Payload,
 } from './log';
 export type {
+  Dimensions,
+  DimensionsString,
   MatchScreenshotConfig,
   ScreenshotMeta,
   ToMatchScreenshotOptions,
 } from './matchScreenshot';
+/** @internal */
+export type {ScreenshotLogFields} from './matchScreenshot';
 export type {ApiMockFunction} from './mockApiRoute';
 /** @internal */
 export type {ApiMockState} from './mockApiRoute';

src/types/matchScreenshot.ts

@@ -1,9 +1,23 @@
+import type {Brand} from './brand';
 import type {Url} from './http';
 import type {RunLabel} from './runLabel';
 import type {Selector} from './selectors';
 import type {TestStaticOptions} from './testRun';
 import type {TestMetaPlaceholder} from './userland';
 
+/**
+ * Dimensions of screenshot image.
+ */
+export type Dimensions = Readonly<{
+  height: number;
+  width: number;
+}>;
+
+/**
+ * String with dimensions of screenshot, like `320x108`.
+ */
+export type DimensionsString = Brand<string, 'DimensionsString'>;
+
 /**
  * Functions that describe the `toMatchScreenshot` assert (in `expect`).
  */
@@ -32,6 +46,16 @@ export type MatchScreenshotConfig<TestMeta = TestMetaPlaceholder> = Readonly<{
   ) => Promise<string>;
 }>;
 
+/**
+ * Log fields for single screenshot.
+ * @internal
+ */
+export type ScreenshotLogFields = {
+  dimensions: DimensionsString;
+  readonly screenshotId: string;
+  url: Url;
+};
+
 /**
  * General screenshot metadata (like test name, assert description, etc.).
  */

src/utils/expect/getEmptyAdditionalLogFields.ts

@@ -0,0 +1,17 @@
+import type {AdditionalLogFields} from './types';
+
+type Options = Readonly<{
+  expectedScreenshotId: string;
+}>;
+
+/**
+ * Get empty additional log fields object for `toMatchScreenshot` assertion.
+ * @internal
+ */
+export const getEmptyAdditionalLogFields = ({
+  expectedScreenshotId,
+}: Options): AdditionalLogFields => ({
+  actual: undefined,
+  diff: undefined,
+  expected: {dimensions: undefined, screenshotId: expectedScreenshotId, url: undefined},
+});

src/utils/expect/toMatchScreenshot.ts

@@ -1,5 +1,4 @@
 import {randomUUID} from 'node:crypto';
-import {readFile} from 'node:fs/promises';
 import {join} from 'node:path';
 
 import {isLocalRun} from '../../configurator';
@@ -14,24 +13,18 @@ import {getFullPackConfig} from '../config';
 import {E2edError} from '../error';
 import {writeFile} from '../fs';
 import {setReadonlyProperty} from '../object';
+import {getDimensionsString, getPngDimensions} from '../screenshot';
 
+import {getEmptyAdditionalLogFields} from './getEmptyAdditionalLogFields';
 import {getScreenshotMeta} from './getScreenshotMeta';
+import {writeScreenshotFromPath} from './writeScreenshotFromPath';
 
-import type {FilePathFromRoot, Selector, ToMatchScreenshotOptions, Url} from '../../types/internal';
+import type {FilePathFromRoot, Selector, ToMatchScreenshotOptions} from '../../types/internal';
 
 import type {Expect} from './Expect';
 
 import {expect as playwrightExpect} from '@playwright/test';
 
-type AdditionalLogFields = {
-  actualScreenshotId: string | undefined;
-  actualScreenshotUrl: Url | undefined;
-  diffScreenshotId: string | undefined;
-  diffScreenshotUrl: Url | undefined;
-  expectedScreenshotId: string;
-  expectedScreenshotUrl: Url | undefined;
-};
-
 /**
  * Checks that the selector screenshot matches the one specified by `expectedScreenshotId`.
  * @internal
@@ -44,8 +37,7 @@ export const toMatchScreenshot = async (
 ): Promise<void> => {
   const actualValue = context.actualValue as Selector;
   const {description} = context;
-  const {getScreenshotUrlById, readScreenshot, writeScreenshot} =
-    getFullPackConfig().matchScreenshot;
+  const {getScreenshotUrlById, readScreenshot} = getFullPackConfig().matchScreenshot;
 
   const assertId = randomUUID();
   const screenshotFileName = `${assertId}.png`;
@@ -54,14 +46,7 @@ export const toMatchScreenshot = async (
     screenshotFileName,
   ) as FilePathFromRoot;
 
-  const additionalLogFields: AdditionalLogFields = {
-    actualScreenshotId: undefined,
-    actualScreenshotUrl: undefined,
-    diffScreenshotId: undefined,
-    diffScreenshotUrl: undefined,
-    expectedScreenshotId,
-    expectedScreenshotUrl: undefined,
-  };
+  const additionalLogFields = getEmptyAdditionalLogFields({expectedScreenshotId});
 
   setReadonlyProperty(context, 'additionalLogFields', additionalLogFields);
 
@@ -70,13 +55,17 @@ export const toMatchScreenshot = async (
   let expectedScreenshotFound = false;
 
   if (expectedScreenshotId) {
-    additionalLogFields.expectedScreenshotUrl = getScreenshotUrlById(expectedScreenshotId);
+    additionalLogFields.expected.url = getScreenshotUrlById(expectedScreenshotId);
 
     const expectedScreenshot = await readScreenshot(expectedScreenshotId, meta);
 
     if (expectedScreenshot !== undefined) {
       expectedScreenshotFound = true;
 
+      additionalLogFields.expected.dimensions = getDimensionsString(
+        getPngDimensions(expectedScreenshot),
+      );
+
       if (!isLocalRun) {
         await writeFile(screenshotPath, expectedScreenshot);
       }
@@ -112,20 +101,19 @@ export const toMatchScreenshot = async (
       const actualScreenshotPath = join(output, `${assertId}-actual.png`) as FilePathFromRoot;
       const diffScreenshotPath = join(output, `${assertId}-diff.png`) as FilePathFromRoot;
 
-      const actualScreenshot = await readFile(actualScreenshotPath);
-      const actualScreenshotId = await writeScreenshot(actualScreenshot, meta);
-
-      additionalLogFields.actualScreenshotId = actualScreenshotId;
-      additionalLogFields.actualScreenshotUrl = getScreenshotUrlById(actualScreenshotId);
-
-      const diffScreenshot = await readFile(diffScreenshotPath);
-      const diffScreenshotId = await writeScreenshot(diffScreenshot, {
-        ...meta,
-        actual: actualScreenshotId,
+      const actualScreenshotId = await writeScreenshotFromPath({
+        additionalLogFields,
+        meta,
+        path: actualScreenshotPath,
+        type: 'actual',
       });
 
-      additionalLogFields.diffScreenshotId = diffScreenshotId;
-      additionalLogFields.diffScreenshotUrl = getScreenshotUrlById(diffScreenshotId);
+      await writeScreenshotFromPath({
+        additionalLogFields,
+        meta: {...meta, actual: actualScreenshotId},
+        path: diffScreenshotPath,
+        type: 'diff',
+      });
     } catch (secondError) {
       throw new E2edError(errorMessage, {secondError});
     }
@@ -138,11 +126,12 @@ export const toMatchScreenshot = async (
   }
 
   try {
-    const actualScreenshot = await readFile(screenshotPath);
-    const actualScreenshotId = await writeScreenshot(actualScreenshot, meta);
-
-    additionalLogFields.actualScreenshotId = actualScreenshotId;
-    additionalLogFields.actualScreenshotUrl = getScreenshotUrlById(actualScreenshotId);
+    await writeScreenshotFromPath({
+      additionalLogFields,
+      meta,
+      path: screenshotPath,
+      type: 'actual',
+    });
   } catch (secondError) {
     throw new E2edError(message, {secondError});
   }