lighthouse-reporting 1.2.0 → 1.3.1

package/README.md

@@ -4,10 +4,322 @@
 
 The reports include trend history support, allowing you to track performance improvements over time.
 
+<p align="center">
+  <img alt="HTML" src="./docs/html_report.png" width="45%">
+&nbsp; &nbsp; &nbsp; &nbsp;
+  <img alt="Plot" src="./docs/plot_report.png" width="45%">
+</p>
+
 ## Usage
 
-### Jenkins
+Examples of usage with Playwright + Lighthouse (and Storybook).
+
+### In your frontend or testing framework
+The example of usage [playwright](https://github.com/microsoft/playwright) and [playwright-lighthouse](https://github.com/abhinaba-ghosh/playwright-lighthouse) together.
+
+<details>
+  <summary>lighthouse_pages.spec</summary>
+
+```ts
+import path from 'path'
+import { playAudit } from 'playwright-lighthouse'
+import { playwrightLighthouseTest, getScores, writeCsvResult, writeHtmlListEntryWithRetry, LighthouseResult } from 'lighthouse-reporting'
+import { MyPage1 } from '../../pages/my-page-1.page.js'
+import { MyPage2 } from '../../pages/my-page-1.page.js'
+
+playwrightLighthouseTest.setTimeout(60000)
+const reportDir = path.join(process.cwd(), 'lighthouse')
+const htmlFilePath = path.join(reportDir, 'index.html')
+
+const swimlanes = ['performance']
+const lighthousePages = [
+    { name: 'MyPage1', po: MyPage1, thresholds: { performance: 80, accessibility: 88, seo: 92 }, swimlanes },
+    { name: 'MyPage2', po: MyPage2, thresholds: { performance: 90, accessibility: 100, seo: 90 }, swimlanes },
+]
+
+lighthousePages.forEach(({ name, po, thresholds, swimlanes }) => {
+    playwrightLighthouseTest(name, async ({ port, baseURL }) => {
+        const onlyCategories = ['accessibility', 'seo', 'performance']
+
+        const result: LighthouseResult = await playAudit({
+            url: baseURL + po.getPath('123'),
+            port,
+            thresholds,
+            reports: {
+                formats: {
+                    html: true,
+                },
+                name,
+                directory: reportDir,
+            },
+            opts: {
+                onlyCategories,
+                screenEmulation: { disabled: true },
+            },
+            disableLogs: true,
+            ignoreError: true,
+        })
+
+        const scores = getScores(result)
+        await writeCsvResult(reportDir, name, scores, thresholds, swimlanes)
+        await writeHtmlListEntryWithRetry(htmlFilePath, name, scores, thresholds, result.comparisonError)
+
+        if (result.comparisonError) {
+            throw new Error(result.comparisonError)
+        }
+    })
+})
+```
+
+</details>
+
+### Or in Storybook
+
+An example for storybook with lighthouse and screenshot testing
+
+<details>
+  <summary>storybook.spec.ts</summary>
+
+```ts
+import path from 'path'
+import { BrowserContext } from '@playwright/test'
+import { playAudit } from 'playwright-lighthouse'
+import {
+    playwrightLighthouseTest,
+    getScores,
+    writeCsvResult,
+    writeHtmlListEntryWithRetry,
+    LighthouseResult,
+    StorybookIndexStory,
+    storybookPlaywright,
+} from 'lighthouse-reporting'
+
+playwrightLighthouseTest.setTimeout(60000)
+const reportDir = path.join(process.cwd(), process.env.LH_REPORT_DIR as string)
+const htmlFilePath = path.join(reportDir, 'index.html')
+
+const stories = storybookPlaywright.getStories('./storybook-static/index.json', (story) => {
+    // skip docs, etc
+    if (story.type !== 'story') {
+        return false
+    }
+    // only include stories with test tag
+    if (!story.tags.includes('test')) {
+        return false
+    }
+    return true
+})
+
+stories.forEach((story) => {
+    playwrightLighthouseTest(`${story.title} - ${story.name}`, async ({ context, port, baseURL }) => {
+        await runLighthouse(story, context, port, baseURL)
+        await storybookPlaywright.captureScreenshot(story, context)
+    })
+})
+
+const runLighthouse = async (story: StorybookIndexStory, context: BrowserContext, port: number, baseURL?: string) => {
+    const onlyCategories = ['accessibility']
+    const thresholds = { accessibility: 100 }
+    const name = story.id
+
+    const page = context.pages()[0]
+    await page.goto(`/iframe.html?id=${story.id}`)
+
+    const result: LighthouseResult = await playAudit({
+        url: baseURL + `/iframe.html?id=${story.id}`,
+        port,
+        thresholds,
+        reports: {
+            formats: {
+                html: true,
+            },
+            name,
+            directory: reportDir,
+        },
+        opts: {
+            onlyCategories,
+            screenEmulation: { disabled: true },
+        },
+        disableLogs: true,
+        ignoreError: true,
+    })
+
+    const scores = getScores(result)
+    await writeCsvResult(reportDir, name, scores, thresholds)
+    await writeHtmlListEntryWithRetry(htmlFilePath, name, scores, thresholds, result.comparisonError)
+}
+```
+
+</details>
+
+### Configs examples
+
+<details>
+  <summary>playwright.storybook.config.ts</summary>
+
+```ts
+import { PlaywrightTestConfig } from '@playwright/test'
+
+const baseURL = 'http://127.0.0.1:6009'
+// process.env.LH_REPORT_DIR = 'lighthouse-storybook' // adjust lighthouse output folder if required
+
+const config: PlaywrightTestConfig = {
+    use: {
+        viewport: { width: 1280, height: 820 },
+        ignoreHTTPSErrors: true,
+        acceptDownloads: false,
+        trace: 'off',
+        baseURL,
+        screenshot: { mode: 'off' },
+    },
+    projects: [
+        {
+            name: 'chromium',
+            use: {
+                browserName: 'chromium',
+                launchOptions: { args: ['--disable-gpu'] },
+            },
+            retries: 0,
+        },
+    ],
+    expect: { toMatchSnapshot: { threshold: 0.2 } },
+    reporter: 'line',
+    testDir: 'test/storybook',
+    testMatch: '*.spec.ts',
+    fullyParallel: true,
+    globalSetup: './src/global-setup.ts',
+    globalTeardown: './src/global-teardown.ts',
+    forbidOnly: true,
+    webServer: [
+        {
+            command: 'npx http-server ./storybook-static --port 6009 --silent',
+            url: `${baseURL}/index.json`,
+            timeout: 15 * 1000,
+            reuseExistingServer: false,
+            ignoreHTTPSErrors: true,
+        },
+    ],
+}
+export default config
+```
+
+</details>
+
+<details>
+  <summary>global-setup.ts</summary>
+
+```ts
+import { PlaywrightTestConfig } from '@playwright/test'
+
+const baseURL = 'http://127.0.0.1:6009'
+// process.env.LH_REPORT_DIR = 'lighthouse-storybook' // adjust lighthouse output folder if required
+
+const config: PlaywrightTestConfig = {
+    use: {
+        viewport: { width: 1280, height: 820 },
+        ignoreHTTPSErrors: true,
+        acceptDownloads: false,
+        trace: 'off',
+        baseURL,
+        screenshot: { mode: 'off' },
+    },
+    projects: [
+        {
+            name: 'chromium',
+            use: {
+                browserName: 'chromium',
+                launchOptions: { args: ['--disable-gpu'] },
+            },
+            retries: 0,
+        },
+    ],
+    expect: { toMatchSnapshot: { threshold: 0.2 } },
+    reporter: 'line',
+    testDir: 'test/storybook',
+    testMatch: '*.spec.ts',
+    fullyParallel: true,
+    globalSetup: './src/global-setup.ts',
+    globalTeardown: './src/global-teardown.ts',
+    forbidOnly: true,
+    webServer: [
+        {
+            command: 'npx http-server ./storybook-static --port 6009 --silent',
+            url: `${baseURL}/index.json`,
+            timeout: 15 * 1000,
+            reuseExistingServer: false,
+            ignoreHTTPSErrors: true,
+        },
+    ],
+}
+export default config
+```
+
+</details>
+
+<details>
+  <summary>global-teardown.ts</summary>
+
+```ts
+import { lighthousePlaywrightTeardown } from 'lighthouse-reporting'
+
+async function globalTeardown() {
+    await lighthousePlaywrightTeardown()
+}
+
+export default globalTeardown
+```
+
+</details>
+
+## Jenkins
+
+Plugins used [HTML Publisher](https://plugins.jenkins.io/htmlpublisher/) and [Plot](https://plugins.jenkins.io/plot/).
+
+<details>
+  <summary>Jenkinsfile</summary>
+
+```
+stage('Lighthouse') {
+    steps {
+        # run playwright-lighthouse tests
+    }
+
+    post {
+        always {
+            # html report per build
+            publishHTML(target: [
+                reportName           : 'Lighthouse',
+                reportDir            : "$WORKSPACE/lighthouse",
+                reportFiles          : 'index.html',
+                keepAll              : true,
+                alwaysLinkToLastBuild: true,
+                allowMissing         : false
+            ])
+
+            # csv trend history report
+            script {
+                csvFiles = findFiles(glob: 'lighthouse/*.csv')
+                for (csvFile in csvFiles) {
+                    filePath = "${csvFile}"
+                    plot(csvFileName: filePath.substring(filePath.lastIndexOf("/") + 1),
+                        csvSeries: [[displayTableFlag: false, exclusionValues: '', file: filePath, inclusionFlag: 'OFF', url: '']],
+                        exclZero: true,
+                        group: 'my app',
+                        numBuilds: '100',
+                        style: 'line',
+                        title: filePath.substring(filePath.lastIndexOf("/") + 1, filePath.indexOf(".")),
+                        yaxis: 'score',
+                        yaxisMaximum: '101',
+                        yaxisMinimum: '15') # adjust scale
+                }
+            }
+        }
+    }
+}
+```
+
+</details>
 
-### GitHub Actions
+## GitHub Actions
 
 TODO

package/dist/lighthouse-reporting.umd.cjs

@@ -202,12 +202,15 @@
       const stories = Object.values(storybookIndexJson.entries).filter(storyFilterFn);
       return stories;
     },
-    captureScreenshot: async (story, context, screenshotOptions) => {
+    captureScreenshot: async (story, context, screenshotOptions, actionBeforeScreenshot) => {
       const page = context.pages()[0];
       await page.goto(`/iframe.html?id=${story.id}`);
       await test.expect(page.locator(".sb-show-main")).toBeVisible();
       await test.expect(page.locator(".sb-show-errordisplay")).not.toBeVisible();
       await page.waitForLoadState("networkidle");
+      if (actionBeforeScreenshot) {
+        await actionBeforeScreenshot(page);
+      }
       await test.expect(page).toHaveScreenshot(`${story.id}.png`, screenshotOptions);
     }
   };

package/dist/storybookPlaywright.cjs

@@ -12,12 +12,15 @@ const storybookPlaywright = {
     const stories = Object.values(storybookIndexJson.entries).filter(storyFilterFn);
     return stories;
   },
-  captureScreenshot: async (story, context, screenshotOptions) => {
+  captureScreenshot: async (story, context, screenshotOptions, actionBeforeScreenshot) => {
     const page = context.pages()[0];
     await page.goto(`/iframe.html?id=${story.id}`);
     await test.expect(page.locator(".sb-show-main")).toBeVisible();
     await test.expect(page.locator(".sb-show-errordisplay")).not.toBeVisible();
     await page.waitForLoadState("networkidle");
+    if (actionBeforeScreenshot) {
+      await actionBeforeScreenshot(page);
+    }
     await test.expect(page).toHaveScreenshot(`${story.id}.png`, screenshotOptions);
   }
 };

package/dist/storybookPlaywright.d.ts

@@ -1,4 +1,4 @@
-import { BrowserContext } from '@playwright/test';
+import { BrowserContext, Locator, Page } from '@playwright/test';
 export interface StorybookIndexStory {
     id: string;
     title: string;
@@ -46,6 +46,49 @@ export declare const storybookPlaywright: {
              */
             height: number;
         };
-    }) => Promise<void>;
+        /**
+         * When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Defaults to
+         * `false`.
+         */
+        fullPage?: boolean;
+        /**
+         * Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink
+         * box `#FF00FF` that completely covers its bounding box.
+         */
+        mask?: Array<Locator>;
+        /**
+         * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is
+         * configurable with `TestConfig.expect`. Unset by default.
+         */
+        maxDiffPixelRatio?: number;
+        /**
+         * An acceptable amount of pixels that could be different. Default is configurable with `TestConfig.expect`. Unset by
+         * default.
+         */
+        maxDiffPixels?: number;
+        /**
+         * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images.
+         * Defaults to `false`.
+         */
+        omitBackground?: boolean;
+        /**
+         * When set to `"css"`, screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this
+         * will keep screenshots small. Using `"device"` option will produce a single pixel per each device pixel, so
+         * screenshots of high-dpi devices will be twice as large or even larger.
+         *
+         * Defaults to `"css"`.
+         */
+        scale?: 'css' | 'device';
+        /**
+         * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the
+         * same pixel in compared images, between zero (strict) and one (lax), default is configurable with
+         * `TestConfig.expect`. Defaults to `0.2`.
+         */
+        threshold?: number;
+        /**
+         * Time to retry the assertion for. Defaults to `timeout` in `TestConfig.expect`.
+         */
+        timeout?: number;
+    }, actionBeforeScreenshot?: ((page: Page) => Promise<void>) | undefined) => Promise<void>;
 };
 export {};

package/dist/storybookPlaywright.js

@@ -10,12 +10,15 @@ const storybookPlaywright = {
     const stories = Object.values(storybookIndexJson.entries).filter(storyFilterFn);
     return stories;
   },
-  captureScreenshot: async (story, context, screenshotOptions) => {
+  captureScreenshot: async (story, context, screenshotOptions, actionBeforeScreenshot) => {
     const page = context.pages()[0];
     await page.goto(`/iframe.html?id=${story.id}`);
     await expect(page.locator(".sb-show-main")).toBeVisible();
     await expect(page.locator(".sb-show-errordisplay")).not.toBeVisible();
     await page.waitForLoadState("networkidle");
+    if (actionBeforeScreenshot) {
+      await actionBeforeScreenshot(page);
+    }
     await expect(page).toHaveScreenshot(`${story.id}.png`, screenshotOptions);
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lighthouse-reporting",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "type": "module",
   "scripts": {
     "build": "vite build && vite build -c vite.umd.config.ts && tsc -p ./tsconfig.build.json",
@@ -29,7 +29,7 @@
   "devDependencies": {
     "@playwright/test": "^1.34.3",
     "@types/fs-extra": "^11.0.1",
-    "@types/node": "^20.2.3",
+    "@types/node": "^20.2.4",
     "@typescript-eslint/eslint-plugin": "^5.59.7",
     "@typescript-eslint/parser": "^5.59.7",
     "eslint": "^8.41.0",
@@ -41,7 +41,7 @@
     "prettier": "^2.8.8",
     "semantic-release": "^21.0.2",
     "typescript": "^5.0.4",
-    "vite": "^4.3.8",
+    "vite": "^4.3.9",
     "vite-plugin-static-copy": "^0.15.0"
   },
   "dependencies": {