chore(css-modules): 🤖 support local visual regression testing via docker (#931)

* chore: 🤖 add pkg vite-plugin-static-copy

* chore: 🤖 use vite setup to copy css to distribution

* refactor: 💡 make static copy process common for cjs and esm

* docs: 📝 about css modules

* style: 💄 add Button css module

* style: 💄 assign css module to component Button

* chore: 🤖 add class-variance-authority and clsx

* style: 💄 migrate styled component to css modules

* style: 💄 migrate styled component to css modules

* refactor: 💡 token generator

* chore: 🤖 storybook support for css modules

* chore: 🤖 add button stories for each state, e.g. primary, secondary, etc

* chore: 🤖 add changeset

* chore: 🤖 remove comment

* chore: 🤖 update changeset

* chore: 🤖 declare css files as sideEffects

* refactor: 💡 make class utility libraries, e.g. cva; actual dependencies

* chore: 🤖 add TODO button

* style: 💄 possible typo, e.g. make similar bg size as others

* refactor: 💡 role button is redundant per the ARIA in HTML spec, add aria-busy={loading}

* chore: 🤖 format

* refactor: 💡 generate tokens, e.g. theme config shared file as json, remove generate quotes,e tc

* chore: 🤖 add TODO regarding removal of styled components for the future, e.g. remove babel plugins

* chore: 🤖 add migration note to changeset

* refactor: 💡 forward props (delegated)

* fix: 🐛 checkout design tokens from main

* fix: 🐛 if a consumer passes className, it would overwrite the variant classes

* fix: 🐛 avoid double colmns

* chore: 🤖 regenerate tokens

* fix: 🐛 replace missing by global focus token

* fix: 🐛 focus rings restored for keyboard users

* refactor: 💡 follow BEM naming convention

* chore: 🤖 include BEM rule in llm conventions

* fix: 🐛 empty token

* fix: 🐛 .button > span selector to explicit .button__label class

* chore: 🤖 format

* fix: 🐛 claude review, missing prefers-reduced-motion support for the shimmer animation.

* fix: 🐛 add line

* refactor: 💡 remove sideEffects redundancy

* fix: 🐛 package.json typo

* style: 💄 missing background repeat, as commented by claude PR

* fix: 🐛 Changed both attributes to use || undefined:
- aria-disabled={(disabled || loading) || undefined}
- aria-busy={loading || undefined} due to accessibility

* chore: 🤖 initial playwright Docker setup

* chore: 🤖 create docker ignore file

* chore: 🤖 update gitignore to filter out snapshots, e.g. darwin

* chore: 🤖 create a docker compose to ease orchestration

* chore: 🤖 update playwright-docker script port to 8282

* test: 💍 create button visual regression test covering all states

* docs: 📝 visual regression playwright setup

* fix: 🐛 bash syntax error in the playwright-docker script

* docs: 📝 visual regression docker requirement

* test: 💍 added the aria-busy assertion

* chore: 🤖 track visual regression snapshots

* test: 💍 preevnts shimmer animation from causing noin-deterministic screenshot comparisons

* chore: 🤖 removed docker stop block, and unused DOCKER_INSTANCE_NAME var. The docker rm -f playwright-ui command handles both stopping and removing the container

* refactor: 💡 added role="group" to ButtonGroupWrapper (semantically correct for a group of related buttons) and updated the test to use page.getByRole('group')

* docs: 📝 amend typo (separatily/separately)

* test: 💍 throw if null

* chore: 🤖 map source to docker

* fix: 🐛 button attribute values

* chore: 🤖 update snapshots

Author: punkbit

.dockerignore

@@ -0,0 +1,23 @@
+node_modules
+
+dist
+.storybook/out
+storybook-static
+
+playwright-report
+test-results
+
+.git
+.gitignore
+
+.idea
+.vscode
+*.swp
+*.swo
+
+.DS_Store
+Thumbs.db
+
+*.log
+*.md
+!README.md

.gitignore

@@ -14,10 +14,11 @@ tmp/*
 !.yarn/releases
 !.yarn/plugins
 
-**.ts-snapshots
 tests/**/*-actual.png
 tests/**/*-diff.png
+tests/**/*-darwin.png
 test-results
+playwright-report
 
 .install
 .vscode

.scripts/bash/playwright-docker

@@ -0,0 +1,36 @@
+#!/bin/bash
+
+COMMAND="${1:-test}"
+
+PORT="8282"
+
+if [[ "$COMMAND" = "update" ]]; then
+  docker compose \
+    -f docker-compose.playwright.yml \
+    run \
+    --rm update-snapshots
+elif [[ "$COMMAND" = "ui" ]]; then
+  docker rm -f playwright-ui 2>/dev/null
+
+  echo "🎭 Starting Playwright UI at http://localhost:$PORT..."
+
+  (sleep 3 &&
+    open "http://localhost:$PORT" 2>/dev/null ||
+    xdg-open "http://localhost:$PORT" 2>/dev/null) &
+
+  docker compose \
+      -f docker-compose.playwright.yml \
+      run \
+      --rm \
+      --service-ports \
+      --name playwright-ui \
+      ui
+elif [[ "$COMMAND" = "report" ]]; then
+  npx playwright show-report
+else
+  docker compose \
+    -f docker-compose.playwright.yml \
+    run \
+    --rm \
+    test
+fi

Dockerfile.playwright

@@ -0,0 +1,13 @@
+FROM mcr.microsoft.com/playwright:v1.58.2-noble
+
+WORKDIR /app
+
+RUN corepack enable && corepack prepare yarn@4.5.3 --activate
+
+COPY package.json yarn.lock .yarnrc.yml ./
+
+RUN yarn install
+
+COPY . .
+
+CMD ["yarn", "test:visual"]

docker-compose.playwright.yml

@@ -0,0 +1,31 @@
+services:
+  playwright:
+    build:
+      context: .
+      dockerfile: Dockerfile.playwright
+    volumes:
+      - ./src:/app/src
+      - ./tests:/app/tests
+      - ./playwright-report:/app/playwright-report
+      - ./test-results:/app/test-results
+      - ./.storybook:/app/.storybook
+    environment:
+      - CI=true
+    shm_size: 1gb
+
+  test:
+    extends: playwright
+    command: yarn test:visual
+
+  update-snapshots:
+    extends: playwright
+    command: yarn test:visual:update
+
+  ui:
+    extends: playwright
+    ports:
+      # NOTE: Match port number of `playwright-docker` script
+      - "8282:8282"
+    environment:
+      - CI=false
+    command: npx playwright test --ui-host=0.0.0.0 --ui-port=8282

docs/tests/playwright.md

@@ -11,12 +11,34 @@ Use Playwright when you need to:
 > [!TIP]
 > Use Playwright for rapid local development, (e.g. if you need fast feedback loop) and Chromatic for team reviews and CI/CD.
 
+## Requirements
+
+- [Docker](http://docker.com/)
+
 ## Visual regression testing locally
 
 Visual regression tests are operating system dependent.
 
 Screenshots generated on macOS will differ from Linux or Windows due to font rendering, anti-aliasing, and browser engine differences.
 
+To mitigate differences across operating systems, our visual regression tests are Dockerized for consistent visual regression testing.
+
+### Docker (Ubuntu Linux)
+
+All visual tests run in Docker (Ubuntu Linux) by default for consistency with CI:
+
+```sh
+yarn test:visual          # Run tests
+yarn test:visual:update   # Update snapshots
+yarn test:visual:ui       # UI mode (opens at http://localhost:8282)
+yarn test:visual:report   # View HTML report
+```
+
+> [!NOTE]
+> The port number is declared in the Docker compose and playwright-docker bash script, which should be in sync.
+
+Snapshots are saved with `-linux` suffix to match CI environments.
+
 For this reason at time of writing, the following snaptshots are ignored:
 
 ```sh
@@ -37,7 +59,7 @@ You MUST generate the snapshots you want to compare against. At time of writing,
 > If you are reading this document, you should be aware that this provides you with custom control for advanced needs only! It does not provide you with the setup for cross-operating system, e.g. docker linux.
 > This workflow does NOT expect you to store your favourite OS image/snapshots in the repository, it's for your own usage, or fast feedback loop only!
 
-To generate snapshots, you'll have to manually checkout/switch to the target commit in history and run the `test:visual` to generate it and return back to your ongoing feature branch. Alternatively, you can store snapshots separatily and place them at your need.
+To generate snapshots, you'll have to manually checkout/switch to the target commit in history and run the `test:visual` to generate it and return back to your ongoing feature branch. Alternatively, you can store snapshots separately and place them at your need.
 
 Hypothetically, you could use the following workflow to facilitate:
 

package.json

@@ -387,10 +387,10 @@
     "storybook:serve": "yarn dlx http-server .storybook/out",
     "test": "vitest",
     "test:chromatic": "yarn dlx chromatic",
-    "test:visual": "playwright test",
-    "test:visual:report": "playwright show-report",
-    "test:visual:ui": "playwright test --ui",
-    "test:visual:update": "playwright test --update-snapshots",
+    "test:visual": ".scripts/bash/playwright-docker",
+    "test:visual:report": ".scripts/bash/playwright-docker report",
+    "test:visual:ui": ".scripts/bash/playwright-docker ui",
+    "test:visual:update": ".scripts/bash/playwright-docker update",
     "test:watch": "DEBUG_PRINT_LIMIT=100000 vitest --watch",
     "typecheck": "tsc --noEmit"
   },

src/components/ButtonGroup/ButtonGroup.tsx

@@ -85,9 +85,10 @@ export const ButtonGroup = ({
 
   return (
     <ButtonGroupWrapper
+      {...props}
       $fillWidth={fillWidth}
       $type={type}
-      {...props}
+      role="group"
     >
       {buttons}
     </ButtonGroupWrapper>