Merge pull request #549 from chromaui/docs_ignore_elements_changes

Docs: Ignore tests adjustments

src/content/guides/config-with-story-params.md

@@ -9,7 +9,7 @@ sidebar: { order: 7, label: Config via params }
 
 When using Chromatic with Storybook, you can control the snapshot capturing behavior through Storybook parameters. [Parameters](https://storybook.js.org/docs/api/parameters#story-parameters) are static metadata that can be attached at the story, component (meta), and project (global) levels.
 
-This guide will show you how to configure Chromatic features like [`diffThreshold`](/docs/threshold), [`forcedColors`](/docs/media-features), [`disableSnapshot`](/docs/ignoring-elements), and more using Storybook parameters.
+This guide will show you how to configure Chromatic features like [`diffThreshold`](/docs/threshold), [`forcedColors`](/docs/media-features), [`disableSnapshot`](/docs/ignoring-elements#ignore-tests), and more using Storybook parameters.
 
 ## Story level parameters
 

src/content/snapshot/troubleshooting-snapshots.md

@@ -27,7 +27,7 @@ It's essential that your components and stories render in a **consistent** fashi
 
 - **UI takes time to render**: UI can take extra time to "settle" into it's final orientation. Add a [delay](/docs/delay) to take a snapshot after waiting a period of time. Note that this technique can make the UI rendering inconsistency less obvious in snapshots, but it won't eliminate the underlying issue in how UI renders.
 
-- **Intentional randomness**: Some stories may render unpredictably intentionally. If this is the case you may want to [ignore the story](/docs/ignoring-elements) from UI Tests and move on.
+- **Intentional randomness**: Some stories may render unpredictably intentionally. If this is the case you may want to [ignore the story](/docs/ignoring-elements#with-storybook) from UI Tests and move on.
   If you still need inconsistent elements for local development purposes inside Storybook, you can use `isChromatic()` exported from [our package](/docs/ischromatic) to apply the solutions above only when in the Chromatic environment.
 
 ## Debug snapshot rendering

src/content/snapshotOptions/ignoring-elements.mdx

@@ -0,0 +1,166 @@
+---
+layout: "../../layouts/Layout.astro"
+title: Ignore tests and elements
+description: Learn how you can tell Chromatic to ignore changes for certain elements
+sidebar: { order: 4, label: Ignore elements }
+---
+
+import ParamsCallout from "../../components/ParamsCallout.astro";
+
+import IntegrationSnippets from "../../components/IntegrationSnippets.astro";
+
+# Ignore tests and elements
+
+Sometimes a component's appearance changes every render or contains content like video and [animation](/docs/animations) that is impossible to test consistently. This will trigger visual changes even when the component code hasn't changed. Ignore tests or DOM elements to tell Chromatic to skip them when looking for changes.
+
+## Ignore tests
+
+By default, Chromatic captures snapshots for all your UI components, whether you're testing with Storybook or with the E2E integration (i.e., [Playwright](/docs/playwright) or [Cypress](/docs/cypress)), ensuring your UI remains consistent at all times. However, you may want to ignore specific tests that are irrelevant or cause false positives. 
+
+### With Storybook
+
+If you're running tests with Storybook, you can enable the ` disableSnapshot` option to configure Chromatic to ignore stories and prevent them from being snapshotted. This is useful if you're adopting Chromatic incrementally and want to turn off snapshotting for specific stories or work with components that could contain dynamic content or animations that may trigger unwanted visual changes.
+
+```ts title="src/components/NotFound.stories.ts|tsx"
+// 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 { NotFound } from "./NotFound";
+
+const meta: Meta<typeof NotFound> = {
+  component: NotFound,
+  title: "NotFound",
+  parameters: {
+    // Disables Chromatic's snapshotting on a component level
+    chromatic: { disableSnapshot: true },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof NotFound>;
+
+export const Default: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText("Page not found")).toBeInTheDocument();
+  },
+};
+```
+
+<ParamsCallout name="disableSnapshot" integration="storybook" />
+
+### With Playwright or Cypress
+
+By default, Chromatic's Playwright and Cypress integrations run tests and captures a snapshot at the end of each E2E test; either it passes or fails. However, if you've enabled targeted snapshots with [Playwright](/docs/playwright/targeted-snapshots) or [Cypress](/docs/cypress/targeted-snapshots) to pinpoint visual changes when the test reaches a specific point, you can opt out of the automated snapshotting process by enabling the `disableAutoSnapshot` configuration option. This is useful when capturing snapshots at specific points in your test, such as when a particular element is visible or when a specific action is performed.
+
+{/* prettier-ignore-start */}
+
+<IntegrationSnippets>
+  <Fragment slot="playwright" visible="true">
+    ```ts title="tests/NotFound.test.js|ts"
+    import { expect, takeSnapshot, test } from "@chromatic-com/playwright";
+
+    test.describe("Not found", () => {
+      test.use({
+        disableAutoSnapshot: true, // Disables the automated snapshot generated at the end of the test
+      })
+      test("should show a 404 page", async ({ page }, testInfo) => {
+        await page.goto("/404");
+
+        await expect(page).toHaveTitle("Page not found");
+
+        await takeSnapshot(page, 'Initial 404 page', testInfo);
+
+        // Interacts with the page by clicking the "Go back" button 
+        await page.getByRole("button", { name: "Go back" }).click();
+
+        await takeSnapshot(page, 'Home page loaded', testInfo);
+      });
+    });
+    ```
+    <ParamsCallout name="disableAutoSnapshot" integration="playwright" />
+  </Fragment>
+  <Fragment slot="cypress" visible="true">
+    ```ts title="cypress/e2e/NotFound.spec.js|ts"
+    describe("Not found", () => {
+      it("should show a 404 page", { env: { 
+        disableAutoSnapshot: true // Disables the automated snapshot generated at the end of the test
+      }}, () => {
+        cy.visit("/404");
+
+        cy.title().should("equal", "Page not found");
+
+        cy.takeSnapshot('Initial 404 page');
+
+         // Interacts with the page by clicking the "Go back" button 
+        cy.get("button").contains("Go back").click()
+
+        cy.takeSnapshot('Home page loaded');
+      });
+    });
+    ```
+    <ParamsCallout name="disableAutoSnapshot" integration="cypress" />
+  </Fragment>
+</IntegrationSnippets>
+
+{/* prettier-ignore-end */}
+
+
+## Ignore DOM elements
+
+To ignore specific elements in your UI, add the `.chromatic-ignore` class or `data-chromatic="ignore"` attributes to the elements you want Chromatic to skip. Enabling these attributes notifies Chromatic's diffing algorithm to disregard the pixels when running your UI tests and comparing snapshots for visual changes, including the element's bounding box and position (e.g., width, height, and relative positioning).
+
+```tsx title="src/components/VideoComponent.ts|tsx"
+import React from "react";
+
+interface VideoPlayerProps {
+  src: string
+  datePublished?: string
+}
+
+export const VideoPlayer: React.FC<VideoPlayerProps> = ({
+  src,
+  datePublished = new Date().toLocaleString(),
+}) => {
+  return (
+    <div>
+      <video data-chromatic="ignore" src={src} controls>
+        Your browser does not support video tags.
+      </video>
+      <p className="chromatic-ignore">Published on: {datePublished}</p>
+    </div>
+  )
+}
+```
+
+---
+
+## Frequently asked questions
+
+<details>
+
+<summary>Why isn't an element with <code>data-chromatic="ignore"</code> being ignored?</summary>
+
+Adding the `data-chromatic="ignore"` attribute instructs the diffing algorithm to disregard pixels within the bounding box of the ignored element. However, dimension changes of this element still trigger a change.
+
+Ensure that both the baseline and new snapshots maintain the exact dimensions, such as width, height, and relative positioning.
+
+![Chromatic will not trigger a change because the dimensions of the ignored element remain the same, even though the contents have changed.](../../images/ignore-but-still-changes.png)
+
+![Chromatic will trigger a change because the dimensions of the ignored element have changed.](../../images/ignore-no-changes.png)
+
+</details>
+
+<details>
+<summary>Why are disabled stories still listed?</summary>
+
+If you enable the `disabledSnapshot` configuration option to prevent your stories from being snapshotted, Chromatic will continue to index them and display them in the Library view. However, the "Snapshot" tab will no longer be visible in the UI for these stories. To remove the story altogether, you will need to delete it from your Storybook.
+
+</details>

src/content/storybook/setup.mdx

@@ -316,11 +316,11 @@ Chromatic builds and runs Storybook flawlessly _most of the time_, but we're not
 <details>
 <summary>Why is my build failing with the message <code>Cannot run a build with no stories</code>?</summary>
 
-This happens if certain stories were disabled via the [`chromatic: { disable: true }`](/docs/ignoring-elements#ignore-stories) option at a higher level.
+This happens if certain stories were disabled via the [`chromatic: { disable: true }`](/docs/ignoring-elements#with-storybook) option at a higher level.
 
 To solve this you can:
 
-1. Remove the top-level [`chromatic: { disable: true }`](/docs/ignoring-elements#ignore-stories) option
+1. Remove the top-level [`chromatic: { disable: true }`](/docs/ignoring-elements#with-storybook) option
 1. Enable snapshots for specific stories
 1. Run `yarn storybook-build` locally and fix the issues in your stories