@screenly/edge-apps 1.5.0 → 26.8.0

package/README.md

@@ -342,6 +342,43 @@ afterEach(() => {
 })
 ```
 
+### Screenshot Testing
+
+`captureScreenshot()` consolidates the Playwright boilerplate (browser
+context/page setup, clock and `screenly.js` mocking, navigation, and cleanup)
+that's otherwise duplicated across every resolution in an Edge App's e2e
+screenshot spec. Keep `test()` in your spec file so Playwright still reports
+the correct source location; pass app-specific route mocks through the
+optional `setupMocks` callback, omitting it when there's nothing app-specific
+to mock.
+
+```typescript
+import { test } from '@playwright/test'
+import {
+  captureScreenshot,
+  createMockScreenlyForScreenshots,
+  RESOLUTIONS,
+} from '@screenly/edge-apps/test/screenshots'
+
+const { screenlyJsContent } = createMockScreenlyForScreenshots()
+
+for (const { width, height } of RESOLUTIONS) {
+  test(`screenshot ${width}x${height}`, async ({ browser }) => {
+    await captureScreenshot(browser, {
+      width,
+      height,
+      filenamePrefix: 'my-edge-app',
+      screenlyJsContent,
+      setupMocks: async (page) => {
+        await page.route('**/api**', async (route) => {
+          await route.fulfill({ status: 200, body: '{}' })
+        })
+      },
+    })
+  })
+}
+```
+
 ## Types
 
 ```typescript

package/dist/test/screenshots.d.ts

@@ -18,6 +18,37 @@ interface PlaywrightRouteFulfillOptions {
 interface PlaywrightRoute {
     fulfill(options: PlaywrightRouteFulfillOptions): Promise<void>;
 }
+interface PlaywrightRequest {
+    url(): string;
+    method(): string;
+}
+type PlaywrightRouteHandler = (route: PlaywrightRoute, request: PlaywrightRequest) => Promise<void> | void;
+interface PlaywrightRoutable {
+    route(url: string | RegExp, handler: PlaywrightRouteHandler): Promise<void>;
+}
+interface PlaywrightPage extends PlaywrightRoutable {
+    clock: {
+        setFixedTime(time: Date | number | string): Promise<void>;
+    };
+    goto(url: string): Promise<unknown>;
+    waitForLoadState(state: 'networkidle'): Promise<void>;
+    screenshot(options: {
+        path: string;
+        fullPage: boolean;
+    }): Promise<Buffer>;
+}
+interface PlaywrightBrowserContext {
+    newPage(): Promise<PlaywrightPage>;
+    close(): Promise<void>;
+}
+interface PlaywrightBrowser {
+    newContext(options: {
+        viewport: {
+            width: number;
+            height: number;
+        };
+    }): Promise<PlaywrightBrowserContext>;
+}
 /**
  * Standard resolutions for screenshot testing
  * Covers all supported Screenly player resolutions
@@ -92,17 +123,13 @@ export interface OpenWeatherMocks {
  * @param page - Playwright page object
  * @param mocks - Mock data for OpenWeather API endpoints
  */
-export declare function setupOpenWeatherMocks(page: {
-    route: (url: string, handler: (route: PlaywrightRoute) => Promise<void>) => Promise<void>;
-}, mocks: OpenWeatherMocks): Promise<void>;
+export declare function setupOpenWeatherMocks(page: PlaywrightRoutable, mocks: OpenWeatherMocks): Promise<void>;
 /**
  * Setup screenly.js route mock in Playwright
  * @param page - Playwright page object
  * @param screenlyJsContent - JavaScript content string for screenly.js
  */
-export declare function setupScreenlyJsMock(page: {
-    route: (url: string, handler: (route: PlaywrightRoute) => Promise<void>) => Promise<void>;
-}, screenlyJsContent: string): Promise<void>;
+export declare function setupScreenlyJsMock(page: PlaywrightRoutable, screenlyJsContent: string): Promise<void>;
 /**
  * Freeze the browser clock to a fixed point in time before page load.
  * Must be called before `page.goto()` to ensure the clock is set before
@@ -117,4 +144,32 @@ export declare function setupClockMock(page: {
         setFixedTime(time: Date | number | string): Promise<void>;
     };
 }, date?: Date | number | string): Promise<void>;
+/**
+ * Options for {@link captureScreenshot}.
+ */
+export interface CaptureScreenshotOptions {
+    /** Viewport width */
+    width: number;
+    /** Viewport height */
+    height: number;
+    /** Prefix used for the output screenshot filename */
+    filenamePrefix: string;
+    /** JavaScript content string for screenly.js mocking */
+    screenlyJsContent: string;
+    /** Callback for app-specific route mocks, called before `page.goto()` */
+    setupMocks?: (page: PlaywrightPage) => Promise<void> | void;
+}
+/**
+ * Captures a single screenshot at the given viewport size, handling the
+ * common boilerplate shared across Edge App screenshot specs: browser
+ * context/page setup, clock and screenly.js mocking, navigation, and
+ * cleanup. App-specific route mocks are supplied via `setupMocks`.
+ *
+ * Callers should keep `test()` in their spec files (rather than wrapping it
+ * in this helper) so Playwright reports the correct source location.
+ *
+ * @param browser - Playwright browser object
+ * @param options - Capture options
+ */
+export declare function captureScreenshot(browser: PlaywrightBrowser, { width, height, filenamePrefix, screenlyJsContent, setupMocks, }: CaptureScreenshotOptions): Promise<void>;
 //# sourceMappingURL=screenshots.d.ts.map

package/dist/test/screenshots.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screenshots.d.ts","sourceRoot":"","sources":["../../src/test/screenshots.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EACjB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAE9C,OAAO,EAAE,kBAAkB,EAAE,CAAA;AAE7B;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAmC,CAAA;AAErE,UAAU,6BAA6B;IACrC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,UAAU,eAAe;IACvB,OAAO,CAAC,OAAO,EAAE,6BAA6B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/D;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWd,CAAA;AAEV;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAI1C;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,cAAc,EAAE,cAAc,GAC7B,MAAM,CAKR;AAED;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,GAAE,OAAO,CAAC,gBAAgB,CAAM,EACxC,QAAQ,GAAE,OAAO,CAAC,gBAAgB,CAAM,EACxC,YAAY,SAA0B,GACrC;IAAE,YAAY,EAAE,cAAc,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAS7D;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE;IACJ,KAAK,EAAE,CACL,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,KAC/C,OAAO,CAAC,IAAI,CAAC,CAAA;CACnB,EACD,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,IAAI,CAAC,CAuCf;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE;IACJ,KAAK,EAAE,CACL,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,KAC/C,OAAO,CAAC,IAAI,CAAC,CAAA;CACnB,EACD,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE;IACJ,KAAK,EAAE;QAAE,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAA;CACrE,EACD,IAAI,GAAE,IAAI,GAAG,MAAM,GAAG,MAA8B,GACnD,OAAO,CAAC,IAAI,CAAC,CAEf"}
+{"version":3,"file":"screenshots.d.ts","sourceRoot":"","sources":["../../src/test/screenshots.ts"],"names":[],"mappings":"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"}

package/dist/test/screenshots.js

@@ -125,3 +125,34 @@ export async function setupScreenlyJsMock(page, screenlyJsContent) {
 export async function setupClockMock(page, date = FIXED_SCREENSHOT_DATE) {
     await page.clock.setFixedTime(date);
 }
+/**
+ * Captures a single screenshot at the given viewport size, handling the
+ * common boilerplate shared across Edge App screenshot specs: browser
+ * context/page setup, clock and screenly.js mocking, navigation, and
+ * cleanup. App-specific route mocks are supplied via `setupMocks`.
+ *
+ * Callers should keep `test()` in their spec files (rather than wrapping it
+ * in this helper) so Playwright reports the correct source location.
+ *
+ * @param browser - Playwright browser object
+ * @param options - Capture options
+ */
+export async function captureScreenshot(browser, { width, height, filenamePrefix, screenlyJsContent, setupMocks = async () => { }, }) {
+    const screenshotsDir = getScreenshotsDir();
+    const context = await browser.newContext({ viewport: { width, height } });
+    try {
+        const page = await context.newPage();
+        await setupClockMock(page);
+        await setupScreenlyJsMock(page, screenlyJsContent);
+        await setupMocks(page);
+        await page.goto('/');
+        await page.waitForLoadState('networkidle');
+        await page.screenshot({
+            path: path.join(screenshotsDir, `${filenamePrefix}-${width}x${height}.png`),
+            fullPage: false,
+        });
+    }
+    finally {
+        await context.close();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@screenly/edge-apps",
-  "version": "1.5.0",
+  "version": "26.8.0",
   "description": "A TypeScript library for interfacing with Screenly Edge Apps API",
   "type": "module",
   "sideEffects": [

package/scripts/create-template/e2e/screenshots.spec.ts

@@ -1,33 +1,19 @@
 import { test } from '@playwright/test'
 import {
+  captureScreenshot,
   createMockScreenlyForScreenshots,
-  getScreenshotsDir,
   RESOLUTIONS,
-  setupClockMock,
-  setupScreenlyJsMock,
 } from '@screenly/edge-apps/test/screenshots'
-import path from 'path'
 
 const { screenlyJsContent } = createMockScreenlyForScreenshots()
 
 for (const { width, height } of RESOLUTIONS) {
   test(`screenshot ${width}x${height}`, async ({ browser }) => {
-    const screenshotsDir = getScreenshotsDir()
-
-    const context = await browser.newContext({ viewport: { width, height } })
-    const page = await context.newPage()
-
-    await setupClockMock(page)
-    await setupScreenlyJsMock(page, screenlyJsContent)
-
-    await page.goto('/')
-    await page.waitForLoadState('networkidle')
-
-    await page.screenshot({
-      path: path.join(screenshotsDir, `${width}x${height}.png`),
-      fullPage: false,
+    await captureScreenshot(browser, {
+      width,
+      height,
+      filenamePrefix: '{{APP_NAME}}',
+      screenlyJsContent,
     })
-
-    await context.close()
   })
 }