Skip to main content

Getting Started with @qs/design-tests

Status: Stable This guide walks you through setting up visual regression testing for your project using @qs/design-tests.

Installation​

Install the package as a dev dependency:

pnpm add -D @qs/design-tests

Configuration​

Create a .designTests.js file in your project root:

module.exports = {
  projects: {
    myapp: {
      key: "myapp",
      name: "My Application",
      url: "http://localhost:6006", // Your Storybook or application URL

      // Optional: Test specific pages (for non-Storybook projects)
      pages: [
        { name: "Homepage", path: "/en/" },
        { name: "About", path: "/en/about" },
      ],

      // Optional: Filter which stories to test
      ignoreList: ["components/internal/*"],
    }
  },

  viewports: [
    { name: "mobile", width: 375, height: 812 },
    { name: "tablet", width: 768, height: 1024 },
    { name: "desktop", width: 1440, height: 900 },
  ],

  stability: {
    strategy: "advanced",
    waitForNetworkIdle: true,
    waitBeforeScreenshot: 1000,
  },
};

First Run​

Run the tests for the first time:

npx design-tests run --config .designTests.js

Since no baseline exists, the system will automatically create baseline images for all tests. You'll see output like:

📝 Project "myapp": Creating baseline (no existing baseline found)
🌐 Launching browser (headless: true)...
📸 Running tests...
  [1/150] ⏳ mobile | pages/homepage...
  [1/150] ✓ OK (2.3s)
  ...

📊 Test Results: 0 visual differences, 150 new baselines detected
✅ Report generated successfully!
   Passed: 0
   Failed: 0
   New: 150
   Deleted: 0

Commit Baseline​

Commit the newly created baseline images to your repository:

git add design-tests/baseline-images/
git commit -m "Add design tests baseline"
git push

Subsequent Runs​

On subsequent runs, the tests will compare against the baseline:

npx design-tests run --config .designTests.js

If everything matches:

🔍 Project "myapp": Comparing against baseline
...
📊 Test Results: 0 visual differences, 0 new baselines detected
✅ All tests passed - no visual differences

If there are visual changes:

🔍 Project "myapp": Comparing against baseline
...
📊 Test Results: 12 visual differences, 0 new baselines detected
⚠️  Build marked as UNSTABLE due to visual differences

Review the HTML report at design-tests/report/index.html to see the differences.

For consistent results across environments, use Docker:

# Add docker-compose.yml to your project
# Run tests in Docker
docker compose run --rm design-tests

This ensures pixel-perfect consistency with CI environments (Linux x86_64).

Next Steps​

Common Issues​

Tests fail immediately​

Make sure your application URL is accessible:

curl http://localhost:6006

Baseline images differ between local and CI​

Always use Docker for generating/updating baselines to ensure consistency:

docker compose run --rm design-tests

Too many screenshots​

Use ignoreList to exclude stories you don't want to test:

projects: {
  myapp: {
    ignoreList: [
      "internal/*",
      "examples/*",
      "deprecated/*"
    ]
  }
}