Threshold for changes
The diffThreshold configuration option allows you to fine-tune the threshold for visual change between snapshots before Chromatic flags them. Sometimes, you need assurance to the sub-pixel; other times, you want to skip visual noise generated by non-deterministic rendering, such as anti-aliasing.
Setting the threshold
Chromatic’s default threshold is .063, which balances high visual accuracy with low false positives (for example, from artifacts like anti-aliasing). 0 is the most accurate. 1 is the least accurate.
If you need to customize how Chromatic identifies visual changes in your UI, add the diffThreshold configuration option to your tests. For example:
// Adjust this import to match your framework (e.g., nextjs, vue3-vite)
import type { Meta, StoryObj } from "@storybook/your-framework";
/*
* Replace the @storybook/test package with the following if you are using a version of Storybook earlier than 8.0:
* import { within } from "@storybook/testing-library";
* import { expect } from "@storybook/jest";
*/
import { expect, within } from "@storybook/test";
import { UserAccount } from "./UserAccount";
const meta: Meta<typeof UserAccount> = {
component: UserAccount,
title: "UserAccount",
parameters: {
// Sets the threshold for 0.2 at the component level for all stories.
chromatic: { diffThreshold: 0.2 },
},
};
export default meta;
type Story = StoryObj<typeof UserAccount>;
export const Default: Story = {
play: async ({ canvasElement }) => {
const canvas = within(canvasElement);
await expect(canvas.getByText("Welcome, username")).toBeInTheDocument();
},
};
chromatic.diffThreshold parameter can be set at story,
component, and project levels. This enables you to set project wide
defaults and override them for specific components and/or stories. Learn more » import { test, expect } from "@chromatic-com/playwright";
test.describe("User Profile Page", () => {
// Sets the threshold for 0.2 for this test.
test.use({ diffThreshold: 0.2 });
test("Successfully loads the user information ", async ({ page }) => {
await page.goto("/profile");
await expect(page.getByText("Welcome, username")).toBeVisible();
});
});
diffThreshold configuration option can be set at the
project level or the test level. This enables you to set project wide
defaults and override them for specific tests. Learn more » describe("User Profile Page", () => {
// Sets the threshold for 0.2 for this test.
it("Successfully authenticates user", { env: { diffThreshold: 0.2 } }, () => {
cy.visit("/profile");
cy.get("span").contains("Welcome, username");
});
});
diffThreshold configuration option can be set at the
project level or the test level. This enables you to set project wide
defaults and override them for specific tests. Learn more » Adjusting the diffThreshold configuration option allows Chromatic to detect subtle visual changes within your UI when snapshotted. While accurate for most common scenarios, it can lead to an inconsistent UI test. For example, setting the parameter to a value of 0.8 can be enough to prevent Chromatic from accurately detecting changes (e.g., positioning).
If you’re unsure which value will be enough, use our interactive diff tool that allows you to preview in real-time how adjusting the option impacts your UI tests.
Anti-aliasing
By default, Chromatic detects anti-aliased pixels and ignores them to prevent false positives. The diffIncludeAntiAliasing configuration option allows you to override this behavior when Chromatic does not flag a single pixel change but should.
To enable this feature and allow Chromatic to automatically detect anti-aliased pixels, adjust your tests to include the diffIncludeAntiAliasing option. For example:
// Adjust this import to match your framework (e.g., nextjs, vue3-vite)
import type { Meta, StoryObj } from "@storybook/your-framework";
/*
* Replace the @storybook/test package with the following if you are using a version of Storybook earlier than 8.0:
* import { within } from "@storybook/testing-library";
* import { expect } from "@storybook/jest";
*/
import { expect, within } from "@storybook/test";
import { UserAccount } from "./UserAccount";
const meta: Meta<typeof UserAccount> = {
component: UserAccount,
title: "UserAccount",
parameters: {
// Configures the component to include anti-aliasing in the diff calculation.
chromatic: { diffIncludeAntiAliasing: true },
},
};
export default meta;
type Story = StoryObj<typeof UserAccount>;
export const Default: Story = {
play: async ({ canvasElement }) => {
const canvas = within(canvasElement);
await expect(canvas.getByText("Welcome, username")).toBeInTheDocument();
},
};
chromatic.diffIncludeAntiAliasing parameter can be set at story,
component, and project levels. This enables you to set project wide
defaults and override them for specific components and/or stories. Learn more » import { test, expect } from "@chromatic-com/playwright";
test.describe("User Profile Page", () => {
// Configures this to include anti-aliasing in the diff calculation.
test.use({ diffIncludeAntiAliasing: true });
test("Successfully loads the user information ", async ({ page }) => {
await page.goto("/profile");
await expect(page.getByText("Welcome, username")).toBeVisible();
});
});
diffIncludeAntiAliasing configuration option can be set at the
project level or the test level. This enables you to set project wide
defaults and override them for specific tests. Learn more » describe("User Profile Page", () => {
// Configures this to include anti-aliasing in the diff calculation.
it("Successfully loads the user information", { env: { diffIncludeAntiAliasing: true } }, () => {
cy.visit("/profile");
cy.get("span").contains("Welcome, username");
});
});
diffIncludeAntiAliasing configuration option can be set at the
project level or the test level. This enables you to set project wide
defaults and override them for specific tests. Learn more » Troubleshooting
Why weren’t diffs found when a color or background changed?
Chromatic uses a threshold to determine how much must change between snapshots before they get flagged as visual changes. This prevents false positives due to anti-aliasing and other non-deterministic rendering artifacts.
However, our default threshold may miss subtle changes, such as nuanced changes to a background’s shade of gray. In this case, you may want to adjust the diffThreshold to be more accurate (lower value).
Find the suitable threshold for your UI using our interactive diff tool.