Cicdplaywright

docs/E2E/VISUAL.md

@@ -1 +1,85 @@
-TBD
+# Visual Testing with Playwright and Virtual Camera
+
+This project uses Playwright for visual tests and a thin Virtual Camera API to keep tests clean and portable.
+
+Goals:
+- Framework-agnostic test code using Atoms and Helpers
+- Centralize visual capture via a Camera (Percy or manual PNGs)
+- Stable screenshots (disable animations, consistent widths)
+
+## Setup
+
+- Playwright config at `packages/bits/playwright.config.ts` defines a `visual` project and outputs artifacts to `test-results/`.
+- Manual snapshots: set `SNAPSHOTS_UPLOAD=manual` to write PNGs to `_snapshots/`.
+- Percy (optional): set `PERCY_TOKEN` in your environment and run via `percy exec`.
+
+## Virtual Camera API
+
+Import from `packages/bits/e2e/virtual-camera`:
+- `new Camera().loadFilm(page, testName, suiteName?)` – initialize camera
+- `camera.turn.on()` / `camera.turn.off()` – enable/disable lens CSS and configuration
+- `camera.say.cheese(label)` – capture a snapshot with an optional stabilization delay
+- `camera.be.responsive(widths, callback?)` – set responsive widths and optional callback that receives the Playwright `page`
+
+By default, the Camera engine selects the Percy lens when `process.env.PERCY` is present. Otherwise, with `SNAPSHOTS_UPLOAD=manual`, it saves PNGs.
+
+## Best Practices
+
+- Disable CSS animations for visual runs:
+  - `await Helpers.disableCSSAnimations(Animations.TRANSITIONS_AND_ANIMATIONS)`
+- Interact via Atoms (see `docs/E2E/ATOMS.md`) to keep tests resilient.
+- Use meaningful snapshot labels tied to user actions.
+- Prefer consistent viewport widths; set `camera.be.responsive([1920])` as needed.
+
+## Example: Busy Visual Test
+
+```ts
+import { test, Helpers, Animations } from "../../setup";
+import { Atom } from "../../atom";
+import { ButtonAtom } from "../button/button.atom";
+import { Camera } from "../../virtual-camera/Camera";
+
+const name = "Busy";
+
+test.describe(`Visual tests: ${name}`, () => {
+  let switchBusyState: ButtonAtom;
+
+  test.beforeEach(async ({ page }) => {
+    await Helpers.prepareBrowser("busy/busy-visual-test", page);
+    await Helpers.disableCSSAnimations(Animations.TRANSITIONS_AND_ANIMATIONS);
+    switchBusyState = Atom.find<ButtonAtom>(ButtonAtom, "nui-busy-test-button");
+  });
+
+  test(`${name} visual test`, async ({ page }) => {
+    const camera = new Camera().loadFilm(page, `${name} visual test`, "Bits");
+    await camera.turn.on();
+
+    await camera.say.cheese("initial");
+
+    await switchBusyState.click();
+    await camera.say.cheese("busy-state");
+
+    await Helpers.switchDarkTheme("on");
+    await camera.say.cheese("dark-theme");
+    await Helpers.switchDarkTheme("off");
+
+    await camera.turn.off();
+  });
+});
+```
+
+## Running Visual Tests
+
+- Run the visual project:
+```powershell
+cd packages/bits
+yarn e2e:playwright:base --project=visual
+```
+
+- With Percy:
+```powershell
+cd packages/bits
+percy exec -- yarn e2e:playwright:base --project=visual
+```
+
+Snapshots will appear in CircleCI artifacts or `_snapshots/` when using manual mode.

package.json

@@ -24,10 +24,13 @@
     "@angular/platform-browser": "20.3.16",
     "@angular/platform-browser-dynamic": "20.3.16",
     "@angular/router": "20.3.16",
+    "@axe-core/playwright": "4.10.1",
     "@axe-core/webdriverjs": "4.10.1",
     "@compodoc/compodoc": "1.1.26",
-    "@percy/cli": "1.30.2",
+    "@percy/cli": "1.31.8",
+    "@percy/playwright": "1.0.10",
     "@percy/protractor": "2.0.1",
+    "@playwright/test": "1.58.1",
     "@schematics/angular": "20.3.15",
     "@stackblitz/sdk": "1.11.0",
     "@stylistic/eslint-plugin-ts": "3.1.0",
@@ -41,7 +44,7 @@
     "@typescript-eslint/parser": "8.30.1",
     "copyfiles": "2.4.1",
     "core-js": "3.39.0",
-    "eslint": "9.24.0",
+    "eslint": "9.26.0",
     "eslint-import-resolver-typescript": "4.3.2",
     "eslint-plugin-import": "2.31.0",
     "eslint-plugin-jsdoc": "50.6.9",
@@ -59,12 +62,13 @@
     "karma-junit-reporter": "2.0.1",
     "karma-spec-reporter": "0.0.34",
     "less": "4.2.0",
-    "lodash": "4.17.21",
+    "lodash": "4.17.23",
     "lz-string": "1.5.0",
     "moment": "2.30.1",
     "moment-timezone": "0.5.46",
     "ng-packagr": "20.3.2",
     "npm-run-all": "4.1.5",
+    "playwright-ng-schematics": "2.0.3",
     "prettier": "2.8.8",
     "prettier-plugin-sort-json": "0.0.3",
     "protractor": "7.0.0",
@@ -78,9 +82,6 @@
     "tslib": "2.8.1",
     "typescript": "5.8",
     "webpack": "5.96.1",
-    "playwright-ng-schematics": "2.0.3",
-    "@playwright/test": "^1.52.0",
-    "@axe-core/playwright": "^4.10.1",
     "zone.js": "0.15.0"
   },
   "resolutions": {

packages/bits/e2e/atom.ts

@@ -135,7 +135,11 @@ export class Atom {
         await this.locator.click();
     }
 
-    public async hover(): Promise<void> {
-        await this.locator.hover();
+    public async hover(target?: Locator, force: boolean = false): Promise<void> {
+        if (target) {
+            await target.hover( { force });
+            return;
+        }
+        await this.locator.hover({ force });
     }
 }

packages/bits/e2e/components/badge/badge.a11y.spec.ts

@@ -0,0 +1,40 @@
+// © 2022 SolarWinds Worldwide, LLC. All rights reserved.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+//  of this software and associated documentation files (the "Software"), to
+//  deal in the Software without restriction, including without limitation the
+//  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the Software is
+//  furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+//  all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+//  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+//  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+//  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+//  THE SOFTWARE.
+
+import { test, Helpers, Animations } from "../../setup";
+
+
+test.describe("a11y: badge", () => {
+    const rulesToDisable = [
+        "label",
+        "landmark-one-main",
+        "page-has-heading-one",
+        "region",
+    ];
+
+    test.beforeEach(async ({ page }) => {
+        await Helpers.prepareBrowser("common/badge/badge-visual-test", page);
+        await Helpers.disableCSSAnimations(Animations.TRANSITIONS_AND_ANIMATIONS);
+    });
+
+    test("should check a11y of badge", async ({ runA11yScan }) => {
+        await runA11yScan(undefined, rulesToDisable);
+    });
+});

packages/bits/e2e/components/badge/badge.visual.spec.ts

@@ -0,0 +1,45 @@
+// © 2022 SolarWinds Worldwide, LLC. All rights reserved.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+//  of this software and associated documentation files (the "Software"), to
+//  deal in the Software without restriction, including without limitation the
+//  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the Software is
+//  furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+//  all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+//  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+//  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+//  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+//  THE SOFTWARE.
+
+import { test, Helpers, Animations } from "../../setup";
+import { Camera } from "../../virtual-camera/Camera";
+
+const name = "Badge";
+
+test.describe(`Visual tests: ${name}`, () => {
+    let camera: Camera;
+
+    test.beforeEach(async ({ page }) => {
+        await Helpers.prepareBrowser("common/badge/badge-visual-test", page);
+        await Helpers.disableCSSAnimations(Animations.TRANSITIONS_AND_ANIMATIONS);
+        camera = new Camera().loadFilm(page, name, "Bits");
+    });
+
+    test(`${name} visual test`, async () => {
+        await camera.turn.on();
+
+        await camera.say.cheese(`Default`);
+
+        await Helpers.switchDarkTheme("on");
+        await camera.say.cheese(`Dark theme`);
+
+        await camera.turn.off();
+    });
+});

packages/bits/e2e/components/breadcrumb/breadcrumb.visual.spec.ts

@@ -0,0 +1,60 @@
+// © 2022 SolarWinds Worldwide, LLC. All rights reserved.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+//  of this software and associated documentation files (the "Software"), to
+//  deal in the Software without restriction, including without limitation the
+//  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the Software is
+//  furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+//  all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+//  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+//  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+//  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+//  THE SOFTWARE.
+
+import { Atom } from "../../atom";
+import { test, Helpers, Animations } from "../../setup";
+import { Camera } from "../../virtual-camera/Camera";
+
+const name: string = "Breadcrumb";
+
+test.describe(`Visual tests: ${name}`, () => {
+    let camera: Camera;
+    let showSecondViewButton: Atom;
+    let showThirdViewButton: Atom;
+
+    test.beforeEach(async ({ page }) => {
+        await Helpers.prepareBrowser("breadcrumb/breadcrumb-visual-test", page);
+        await Helpers.disableCSSAnimations(Animations.TRANSITIONS_AND_ANIMATIONS);
+
+        camera = new Camera().loadFilm(page, name, "Bits");
+        showSecondViewButton = Atom.find<Atom>(
+            Atom,
+            "nui-demo-breadcrumb-show-second-view"
+        );
+        showThirdViewButton = Atom.find<Atom>(
+            Atom,
+            "nui-demo-breadcrumb-show-third-view"
+        );
+    });
+
+    test(`${name} visual test`, async () => {
+        await camera.turn.on();
+
+        await showSecondViewButton.click();
+        await showThirdViewButton.click();
+        await camera.say.cheese(`Default breadcrumb styles`);
+
+        await Helpers.switchDarkTheme("on");
+        await camera.say.cheese(`Dark theme`);
+        await Helpers.switchDarkTheme("off");
+
+        await camera.turn.off();
+    });
+});

packages/bits/e2e/components/busy/busy.a11y.ts → packages/bits/e2e/components/busy/busy.a11y.spec.ts

@@ -18,31 +18,31 @@
 //  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 //  THE SOFTWARE.
 
-import { browser, by, element, ElementFinder } from "protractor";
+import { BusyAtom } from "./busy.atom";
+import { Atom } from "../../atom";
+import { test, Helpers, Animations } from "../../setup";
 
-import { assertA11y, Helpers } from "../../helpers";
-import { BusyAtom } from "../public_api";
-
-describe("a11y: busy", () => {
+test.describe("a11y: busy", () => {
     const rulesToDisable: string[] = [
         "color-contrast",
         "aria-progressbar-name",
         "duplicate-id",
     ];
 
-    let switchBusyState: ElementFinder;
+    let switchBusyState: Atom;
 
-    beforeAll(async () => {
-        await Helpers.prepareBrowser("busy/busy-visual-test");
-        switchBusyState = element(by.id("nui-busy-test-button"));
+    test.beforeEach(async ({ page }) => {
+        await Helpers.prepareBrowser("busy/busy-visual-test", page);
+        await Helpers.disableCSSAnimations(Animations.ALL);
+        switchBusyState = Atom.find<Atom>(Atom, "nui-busy-test-button");
     });
 
-    it("should check a11y of busy - on", async () => {
-        await assertA11y(browser, BusyAtom, rulesToDisable);
+    test("should check a11y of busy - on", async ({ runA11yScan }) => {
+        await runA11yScan(BusyAtom, rulesToDisable);
     });
 
-    it("should check a11y of busy - off", async () => {
+    test("should check a11y of busy - off", async ({ runA11yScan }) => {
         await switchBusyState.click();
-        await assertA11y(browser, BusyAtom, rulesToDisable);
+        await runA11yScan(BusyAtom, rulesToDisable);
     });
 });

packages/bits/e2e/components/busy/busy.visual.ts → packages/bits/e2e/components/busy/busy.visual.spec.ts

@@ -18,36 +18,34 @@
 //  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 //  THE SOFTWARE.
 
-import { browser, by, element, ElementFinder } from "protractor";
-
-import { Animations, Helpers } from "../../helpers";
+import { Atom } from "../../atom";
+import { test, Helpers, Animations } from "../../setup";
 import { Camera } from "../../virtual-camera/Camera";
 
-const name: string = "Busy";
+const name = "Busy";
 
-describe(`Visual tests: ${name}`, () => {
+test.describe(`Visual tests: ${name}`, () => {
     let camera: Camera;
-    let switchBusyState: ElementFinder;
+    let switchBusyState: Atom;
 
-    beforeAll(async () => {
-        await Helpers.prepareBrowser("busy/busy-visual-test");
-        await Helpers.disableCSSAnimations(
-            Animations.TRANSITIONS_AND_ANIMATIONS
-        );
+    test.beforeEach(async ({ page }) => {
+        await Helpers.prepareBrowser("busy/busy-visual-test", page);
+        await Helpers.disableCSSAnimations(Animations.TRANSITIONS_AND_ANIMATIONS);
 
-        camera = new Camera().loadFilm(browser, name);
-        switchBusyState = element(by.id("nui-busy-test-button"));
+        camera = new Camera().loadFilm(page, name, "Bits");
+        switchBusyState = Atom.find(Atom, "nui-busy-test-button");
     });
 
-    it(`${name} visual test`, async () => {
+    test(`${name} visual test`, async () => {
         await camera.turn.on();
 
         await switchBusyState.click();
         await camera.say.cheese(`States of Busy component`);
 
         await Helpers.switchDarkTheme("on");
         await camera.say.cheese(`Dark theme`);
+        await Helpers.switchDarkTheme("off");
 
         await camera.turn.off();
-    }, 100000);
+    });
 });