Skip to main content

Testing

Squeeze uses a combination of Playwright Component Tests and Vitest unit tests. Every change to how something looks should have a Playwright test. A change to how something works should have a unit test. While we don't have specific code coverage benchmarks, all component change PRs are expected to contain tests covering all new or updated scenarios.

Unit Tests (Vitest)​

These tests are for reusable low-level functions (like custom hooks, helpers, text formatters, etc.) or to test component inputs and outputs (like callbacks, or other non-visual parts of a component's API). They are written and run in Vitest. Each test meant to be run with Vitest needs a *.spec.* suffix.

This flavor of test is much faster than a Playwright test, so they should be preferred whenever possible.

Component Regression Tests (Playwright)​

The goal of these tests is to exercise pieces of UI just like a real user would in a browser, especially focused on what a user will see through screenshot comparisons. They are written and run in Playwright, which will verify each test in a variety of headless browsers. Each test meant to be run with Playwright has a *.bspec.* (browser spec) suffix.

Running with Docker​

Because rendering can differ slightly across platforms, Squeeze uses a Docker image to run its tests and generate screenshots in a way that matches how they run in CI. Before the first time you run the Playwright tests inside of Docker, you must run pnpm build:playwright:docker from packages/ui-components-web to build the container. Once the container is built, you can run the tests with pnpm test:component:docker from packages/ui-components-web.

Running without Docker​

Running component tests outside of Docker is slightly faster, but the screenshot results will differ from what you see in CI. Because of this, macOS screenshots aren't committed into source control. If you want to run component tests without Docker, you must first checkout main and run pnpm test:component --update-snapshots from packages/ui-components-web to build a baseline of screenshots. You'll need to repeat this anytime a new component test/screenshot is merged into main. Once you've established that baseline, checkout your development branch and run pnpm test:component from packages/ui-components-web.

Running with the --ui and --debug modes​

Playwright offers two great options for writing and debugging tests: UI Mode and Debug Mode. Passing one of these flags to either pnpm test:component or pnpm test:component:docker will enable the corresponding mode.

Capturing new screenshots​

If you've added a new component or changed the way one looks, you'll need to capture new screenshots. To do this, run pnpm test:component:docker --update-snapshots from packages/ui-components-web. This will run the tests in a headed browser and generate new screenshots. You'll need to commit these new screenshots to source control. This can take a while, so adding a .only to the *.bspec.tsx file you're working on can really speed things up!

Playwright Tips​

  • More CLI goodies
  • To use --ui or --debug in Docker, you have to install the X11 window server so that Docker can run in headed mode:
    • Docker Debugging for macOS
      • Install XQuartz: brew install --cask xquartz
      • Open XQuartz, go to Preferences -> Security, and check “Allow connections from network clients”
      • Restart your computer (restarting XQuartz might not be enough)
      • Start XQuartz with xhost +localhost (you may have to do this each time you restart your machine or close XQuartz)
      • Open Docker Desktop and edit settings to give access to /tmp/.X11-unix in Preferences -> Resources -> File sharing
    • Docker Debugging for Windows