PoC for component testing

.gitignore

@@ -81,6 +81,7 @@ dist/
 /backstop_data/bitmaps_test/
 /backstop_data/bitmaps_reference/
 /backstop_data/html_report/
+/screenshots/**/failed/**
 
 # GitHub Actions #
 ###############

README.md

@@ -33,7 +33,44 @@ To contribute to Stacks documentation or its CSS library, you’ll need to build
 Having trouble getting these steps to work? Open [an issue](https://github.com/StackExchange/Stacks/issues/new) with a `setup` label.
 
 ## Testing Stacks
-Stacks has implemented visual regression testing with [Backstop](https://github.com/garris/BackstopJS). To test if your new feature introduces visual regressions, run `npm run test` in a new Terminal window while Stacks is running. After the tests have run, a new browser window with any regressions will show. If the regressions are desired, you can run `npm run approve` to establish the new baseline.
+
+### Component Tests
+🚧 Work in Progress 🚧
+
+Component tests are written with [DOM Testing Library](https://testing-library.com/docs/dom-testing-library/intro).
+Please follow the library's principles and documentation to write tests.
+
+Stacks uses [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/) and [Playwright](https://modern-web.dev/docs/test-runner/browser-launchers/playwright/) to run tests in a real browser context
+
+Execute the component tests suite via running:
+```sh
+npm test
+```
+or if you prefer watch mode run:
+```sh
+npm run test:watch
+```
+
+### Visual Regression Tests
+🚧 Work in Progress 🚧
+
+This [Web Test Runner plugin](https://www.npmjs.com/package/@web/test-runner-visual-regression) is used to run visual regression tests. [DOM Testing Library](https://testing-library.com/docs/dom-testing-library/intro).
+Visual regression tests end with this suffix `*.visual.test.ts`.
+
+Execute the visual regression tests suite via running:
+```sh
+npm run test:visual
+```
+
+Update the visual baseline via:
+```sh
+npm run test:visual:update
+```
+
+Failing tests (including diffs) can be found under `screenshots/[browser]/failed/` folders.
+
+### Visual Regression Tests (Legacy)
+Stacks has implemented visual regression testing with [Backstop](https://github.com/garris/BackstopJS). To test if your new feature introduces visual regressions, run `npm run test:regression` in a new Terminal window while Stacks is running. After the tests have run, a new browser window with any regressions will show. If the regressions are desired, you can run `npm run approve` to establish the new baseline.
 
 Individual routes to test are found in [backstop.json](/backstop.json)
 

lib/test/tooltip.test.ts

@@ -0,0 +1,62 @@
+import { html, fixture, expect } from "@open-wc/testing";
+import { screen, waitForElementToBeRemoved } from "@testing-library/dom";
+import userEvent from "@testing-library/user-event";
+import "../ts/index";
+
+const user = userEvent.setup();
+
+describe("tooltip", () => {
+    it("should make the tooltip element visible on hover (after a delay)", async () => {
+        const trigger = await fixture(html`
+            <button
+                class="s-btn s-btn__filled"
+                role="button"
+                data-controller="s-tooltip"
+                title="tooltip content"
+                data-s-tooltip-placement="bottom-start"
+            >
+                Hover tooltip popover
+            </button>
+        `);
+
+        expect(screen.queryByRole("tooltip")).to.be.null;
+
+        await user.hover(trigger);
+        const tooltip = await screen.findByRole("tooltip");
+        expect(tooltip).to.be.visible;
+
+        await user.unhover(trigger);
+        await waitForElementToBeRemoved(() => screen.queryByRole("tooltip"));
+    });
+
+    it("should not flicker when the host contains an SVG and the user hover on it", async () => {
+        await fixture(html`
+            <button
+                class="s-btn"
+                role="button"
+                title="tooltip content"
+                data-controller="s-tooltip"
+                data-s-tooltip-placement="bottom-start"
+            >
+                <svg
+                    data-testid="svg"
+                    aria-hidden="true"
+                    class="bg-red-500"
+                    width="18"
+                    height="18"
+                    viewBox="0 0 18 18"
+                ></svg>
+                👈 Shouldn't flicker 🤷‍
+            </button>
+        `);
+        const button = screen.getByRole("button");
+        const svg = screen.getByTestId("svg");
+
+        await user.hover(button);
+        const tooltip = await screen.findByRole("tooltip");
+        expect(tooltip).to.be.visible;
+
+        await user.hover(svg);
+        expect(tooltip).to.be.visible;
+    });
+});

lib/test/tooltip.visual.test.ts

@@ -0,0 +1,31 @@
+import { html, fixture } from "@open-wc/testing";
+import { screen } from "@testing-library/dom";
+import userEvent from "@testing-library/user-event";
+import { visualDiff } from "@web/test-runner-visual-regression";
+import "../ts/index";
+
+const user = userEvent.setup();
+
+describe("tooltip", () => {
+    it("should not introduce visual regressions", async () => {
+        const wrapper = await fixture(html`
+            <div style="height: 100px; display: inline-block;">
+                <button
+                    class="s-btn s-btn__filled"
+                    role="button"
+                    data-controller="s-tooltip"
+                    title="tooltip content"
+                    data-s-tooltip-placement="bottom-start"
+                >
+                    Hover tooltip popover
+                </button>
+            </div>
+        `);
+
+        const trigger = screen.getByRole("button");
+        await user.hover(trigger);
+        await screen.findByRole("tooltip");
+
+        await visualDiff(wrapper, "tooltip");
+    });
+});

lib/ts/controllers/index.ts

@@ -1,8 +1,21 @@
 // export all controllers *with helpers* so they can be bulk re-exported by the package entry point
-export { ExpandableController } from './s-expandable-control';
-export { hideModal, ModalController, showModal } from './s-modal';
-export { TabListController } from './s-navigation-tablist';
-export { attachPopover, detachPopover, hidePopover, BasePopoverController, PopoverController, showPopover } from './s-popover';
-export { TableController } from './s-table';
-export { setTooltipHtml, setTooltipText, TooltipController } from './s-tooltip';
-export { UploaderController } from './s-uploader';
+export { ExpandableController } from "./s-expandable-control";
+export { hideModal, ModalController, showModal } from "./s-modal";
+export { TabListController } from "./s-navigation-tablist";
+export {
+    attachPopover,
+    detachPopover,
+    hidePopover,
+    BasePopoverController,
+    PopoverController,
+    showPopover,
+} from "./s-popover";
+export { TableController } from "./s-table";
+export { setTooltipHtml, setTooltipText, TooltipController } from "./s-tooltip";
+// uncomment and comment the line above to run the tests against version 1.3.0 of the tooltip and see them failing
+// export {
+//     setTooltipHtml,
+//     setTooltipText,
+//     TooltipController,
+// } from "./s-tooltip-1.3.0";
+export { UploaderController } from "./s-uploader";