Introduce Testing to Stacks

.gitattributes

@@ -0,0 +1 @@
+screenshots/** filter=lfs diff=lfs merge=lfs -text

.github/workflows/main.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [develop]
+  pull_request:
+    branches: [develop]
+
+jobs:
+  build-and-test:
+    name: Build and Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: ⬇️ Checkout
+        uses: actions/checkout@v3
+        with:
+          lfs: true
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 'lts/*'
+
+      - name: 🏗 Install and Build
+        run: |
+          npm ci
+          npx playwright install --with-deps
+          npm run build
+
+      - name: ▶️ Lint and Test
+        run: |
+          npm run lint
+          npm run test -- --config web-test-runner.config.ci.mjs
+
+      - name: ⬆️ Upload Visual Regression Test Results
+        uses: actions/upload-artifact@v3
+        if: failure()
+        with:
+          name: visual-regression-test-results
+          path: screenshots
+
+
+# cancel the jobs if another workflow is kicked off for the same branch
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true

.gitignore

@@ -81,8 +81,13 @@ dist/
 /backstop_data/bitmaps_test/
 /backstop_data/bitmaps_reference/
 /backstop_data/html_report/
+/screenshots/**/failed/**
 
 # GitHub Actions #
 ###############
 /.github/main.workflow
 .vscode/
+
+# JetBrains Editors #
+###############
+/.idea

.prettierignore

@@ -1,3 +1,5 @@
 *.md
 .vscode/
-dist/
+dist/
+# TODO: prettier is breaking less files while formatting
+*.less

.prettierrc

@@ -4,5 +4,6 @@
     "singleQuote": false,
     "quoteProps": "consistent",
     "trailingComma": "es5",
-    "printWidth": 80
+    "printWidth": 80,
+    "endOfLine": "auto"
 }

README.md

@@ -20,6 +20,8 @@ Stacks documentation can be found at https://stackoverflow.design/
 
 - [Using Stacks](#using-stacks)
 - [Building Stacks](#building-stacks)
+- [Linting Stacks](#linting-stacks)
+- [Testing Stacks](#testing-stacks)
 - [Bugs and feature requests](#bugs-and-feature-requests)
 - [Contributing](#contributing)
 - [License](#license)
@@ -32,8 +34,70 @@ 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.
 
+## Linting Stacks
+
+Run all lint suites by running:
+```sh
+npm run lint
+```
+
+Lint the styles (stylelint) by running:
+```sh
+npm run lint:css
+```
+Lint the typescript source code (eslint) via running:
+```sh
+npm run lint:ts
+```
+Lint the source code format (prettier) via running:
+```sh
+npm run lint:format
+```
 ## 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.
+
+Run all test suites by running:
+```sh
+npm test
+```
+### Unit/Component Tests
+
+Unit/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 unit/component tests suite by running:
+```sh
+npm run test:unit
+```
+or if you prefer watch mode run:
+```sh
+npm run test:unit:watch
+```
+
+### Visual Regression Tests
+
+**Prerequisit:** 
+In order to pull and upload baseline images you need to have `git lfs` installed in your local machine. Please follow [this guide](https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage) to install that.
+
+
+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 by 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:legacy: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 test:legacy:regression:update` to establish the new baseline.
 
 Individual routes to test are found in [backstop.json](/backstop.json)
 

lib/css/atomic/gap.less

@@ -40,5 +40,5 @@
 .gx0, .gx1, .gx2, .gx4, .gx6, .gx8, .gx12, .gx16, .gx24, .gx32, .gx48, .gx64,
 .gy0, .gy1, .gy2, .gy4, .gy6, .gy8, .gy12, .gy16, .gy24, .gy32, .gy48, .gy64,
 .g0, .g1, .g2, .g4, .g6, .g8, .g12, .g16, .g24, .g32, .g48, .g64 {
-  gap: var(--_gap-y, 0) var(--_gap-x, 0);
+    gap: var(--_gap-y, 0) var(--_gap-x, 0);
 }

lib/css/components/cards.less

@@ -11,7 +11,7 @@
         --_ca-bc: var(--bc-light);
 
         //  Dim only the first child card content
-         > * {
+        > * {
             opacity: 0.65;
         }
     }

lib/css/components/expandable.less

@@ -111,4 +111,4 @@
     -webkit-clip-path: var(--_ex-clip-path);
     clip-path: var(--_ex-clip-path);
     transition: clip-path 0s var(--_ex-transition-duration), -webkit-clip-path 0s var(--_ex-transition-duration);
-  }
+}

lib/css/components/inputs.less

@@ -609,34 +609,18 @@ fieldset {
     font-size: var(--fs-caption);
 }
 
-//  $$  SIZES
+//  $$  PADDING ADJUSTMENTS AND SIZES
 //  ----------------------------------------------------------------------------
 .s-input__sm,
 .s-textarea__sm,
 .s-select__sm > select {
     font-size: var(--fs-caption);
 }
-.s-input__md,
-.s-textarea__md,
-.s-select__md > select {
-    font-size: var(--fs-body3);
-}
-.s-input__lg,
-.s-textarea__lg,
-.s-select__lg > select {
-    font-size: var(--fs-title);
-}
-.s-input__xl,
-.s-textarea__xl,
-.s-select__xl > select {
-    font-size: var(--fs-headline1);
-}
 
-//  $$  PADDING ADJUSTMENTS WITHIN SIZES
-//  ----------------------------------------------------------------------------
 .s-input__md,
 .s-textarea__md,
 .s-select__md > select {
+    font-size: var(--fs-body3);
     padding-top: 0.5em;
     padding-bottom: 0.5em;
     border-radius: calc(var(--br-sm) + 1px);
@@ -650,13 +634,15 @@ fieldset {
 .s-input__lg,
 .s-textarea__lg,
 .s-select__lg > select {
+    font-size: var(--fs-title);
     padding: 0.45em 0.6em;
     border-radius: calc(var(--br-sm) + 1px);
 }
 
 .s-input__xl,
 .s-textarea__xl,
 .s-select__xl > select {
+    font-size: var(--fs-headline1);
     padding: 0.4em 0.5em;
     border-radius: var(--br-md);
 }

lib/css/components/pagination.less

@@ -1,5 +1,5 @@
 .s-pagination {
-   & &--item {
+    & &--item {
         --_pa-item-bg: transparent;
         --_pa-item-bc: var(--bc-medium);
         --_pa-item-fc: var(--fc-medium);

lib/css/components/popovers.less

@@ -17,15 +17,15 @@
     --_po-arrow-after-r: unset;
     --_po-arrow-after-t: unset;
     --_po-arrow-after-bs: unset;
-  
+
     // CONTEXTUAL STYLES
     .dark-mode({
         --_po-bg: var(--black-075);
         --_po-bc: var(--bc-light);
         --_po-bs: var(--bs-lg);
         --_po-arrow-fc: var(--black-075);
     });
-  
+
     // MODIFIERS
     &.is-visible {
         --_po-d: block;
@@ -34,7 +34,7 @@
         --_po-wmn: unset;
         --_po-w: auto;
     }
-  
+
     // CHILD ELEMENTS
     // Arrow
     &[data-popper-placement^="top"] > &--arrow,
@@ -128,14 +128,14 @@
         right: calc(var(--su8) * -1); // Compensate for s-popover's padding
         padding: var(--su8) !important;
     }
-  
+
     background-color: var(--_po-bg);
     border: 1px solid var(--_po-bc);
     box-shadow: var(--_po-bs);
     display: var(--_po-d);
     min-width: var(--_po-wmn);
     width: var(--_po-w);
-  
+
     border-radius: var(--br-md);
     color: var(--fc-dark);
     font-size: var(--fs-body1);
@@ -144,5 +144,4 @@
     position: absolute;
     white-space: normal; // Guard against popovers being in a container with white-space: nowrap. Without this, the content pops *out* of the popover.
     z-index: var(--zi-popovers);
-  }
-
+}

lib/test/s-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("s-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/s-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("s-tooltip", () => {
+    it("should not introduce visual regressions", async () => {
+        const wrapper = await fixture(html`
+            <div style="height: 100px; width: 160px; 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, "s-tooltip");
+    });
+});