From 9d41f9226e3d979ef62e7f5f4a60cda3fa61a8b1 Mon Sep 17 00:00:00 2001
From: divya jindel <divya.jindel@sage.com>
Date: Thu, 7 May 2026 14:57:58 +0100
Subject: [PATCH] test(step-flow): refine testing suite

---
 .../step-flow/step-flow-test.stories.tsx      | 222 +++++++++++-
 src/components/step-flow/step-flow.pw.tsx     | 326 +-----------------
 .../step-flow/step-flow.stories.tsx           |   5 +-
 3 files changed, 228 insertions(+), 325 deletions(-)

diff --git a/src/components/step-flow/step-flow-test.stories.tsx b/src/components/step-flow/step-flow-test.stories.tsx
index fd63ec16ab..6914a8db19 100644
--- a/src/components/step-flow/step-flow-test.stories.tsx
+++ b/src/components/step-flow/step-flow-test.stories.tsx
@@ -1,11 +1,27 @@
-import React from "react";
+import React, { useState, useRef } from "react";
+import Button from "../button";
+import Form from "../form";
+import Dialog from "../dialog";
 import Typography from "../typography";
-import { StepFlow, StepFlowProps } from ".";
+import Textarea from "../textarea";
+import Box from "../box";
+import Icon from "../icon";
+import Image from "../image";
+import pointSvg from "../../../.assets/point.svg";
+import {
+  StepFlow,
+  StepFlowTitle,
+  StepFlowHandle,
+  Steps,
+  StepFlowProps,
+} from ".";
+import { StoryFn } from "@storybook/react";
 
 export default {
   title: "Step Flow/Test",
   parameters: {
     info: { disable: true },
+    themeProvider: { chromatic: { theme: "sage" } },
     chromatic: {
       disableSnapshot: true,
     },
@@ -115,3 +131,205 @@ export const DefaultWithAriaDescribedBy = () => (
 );
 
 DefaultWithAriaDescribedBy.storyName = "Default with aria-describedby";
+
+export const AllChromaticScenarios = () => {
+  const titleNodeWithIcon = (
+    <Box display="flex" alignItems="center" gap="8px">
+      <Icon type="bin" />
+      <StepFlowTitle titleString="Step title" />
+    </Box>
+  );
+
+  const titleNodeWithSROnlyTitle = (
+    <Box display="flex" alignItems="center" gap="8px">
+      <StepFlowTitle
+        titleVariant="h2"
+        titleString="Step title"
+        screenReaderOnlyTitle="Step Title with a pointer image"
+      />
+      <Image alt="" src={pointSvg} decorative size={50} />
+    </Box>
+  );
+
+  return (
+    <Box
+      display="grid"
+      gridTemplateColumns="repeat(2, minmax(0, 1fr))"
+      gap="32px"
+      p={4}
+    >
+      <Box>
+        <Typography mb={2} fontWeight="700">
+          Default
+        </Typography>
+        <StepFlow
+          title="Step title"
+          titleVariant="h2"
+          currentStep={1}
+          totalSteps={6}
+        />
+      </Box>
+
+      <Box>
+        <Typography mb={2} fontWeight="700">
+          Title Node
+        </Typography>
+        <StepFlow
+          title={titleNodeWithIcon}
+          titleVariant="h2"
+          currentStep={1}
+          totalSteps={6}
+        />
+      </Box>
+
+      <Box>
+        <Typography mb={2} fontWeight="700">
+          Title Node – Screen Reader Only Title
+        </Typography>
+        <StepFlow
+          title={titleNodeWithSROnlyTitle}
+          currentStep={1}
+          totalSteps={6}
+        />
+      </Box>
+
+      <Box>
+        <Typography mb={2} fontWeight="700">
+          Category
+        </Typography>
+        <StepFlow
+          category="Main goal"
+          title="Step title"
+          currentStep={1}
+          totalSteps={6}
+          titleVariant="h2"
+        />
+      </Box>
+
+      <Box>
+        <Typography mb={2} fontWeight="700">
+          Show Progress Indicator
+        </Typography>
+        <StepFlow
+          category="Main goal"
+          title="Step title"
+          currentStep={1}
+          totalSteps={6}
+          showProgressIndicator
+          titleVariant="h2"
+        />
+      </Box>
+
+      <Box>
+        <Typography mb={2} fontWeight="700">
+          Show Total Steps
+        </Typography>
+        <StepFlow
+          category="Main goal"
+          title="Step title"
+          currentStep={5}
+          totalSteps={6}
+          showProgressIndicator
+          titleVariant="h2"
+        />
+      </Box>
+
+      <Box>
+        <Typography mb={2} fontWeight="700">
+          Show Close Icon
+        </Typography>
+        <StepFlow
+          category="Main goal"
+          title="Step title"
+          currentStep={1}
+          totalSteps={6}
+          showCloseIcon
+          onDismiss={() => undefined}
+          titleVariant="h2"
+        />
+      </Box>
+    </Box>
+  );
+};
+
+AllChromaticScenarios.storyName = "All Chromatic Scenarios";
+AllChromaticScenarios.parameters = {
+  chromatic: { disableSnapshot: false },
+};
+
+export const ExampleImplementationWithTitleNode: StoryFn = () => {
+  const lowestStep = 1;
+  const highestStep = 3;
+
+  const [isOpen, setIsOpen] = useState(true);
+  const [step, setStep] = useState(lowestStep);
+  const stepFlowHandle = useRef<StepFlowHandle>(null);
+
+  const stepTitles = ["Step title 1", "Step title 2", "Step title 3"];
+
+  function handleClick(clickType: string) {
+    stepFlowHandle.current?.focus();
+
+    if (clickType === "Back") {
+      setStep(step > lowestStep ? step - 1 : step);
+    } else {
+      setStep(step < highestStep ? step + 1 : step);
+    }
+  }
+
+  const titleNode = (
+    <Box display="flex" alignItems="center">
+      <Icon type="bin" />
+      <StepFlowTitle titleString={stepTitles[step - 1]} />
+    </Box>
+  );
+  return (
+    <>
+      <Button onClick={() => setIsOpen(true)}>Open Dialog</Button>
+      <Dialog
+        open={isOpen}
+        showCloseIcon={false}
+        aria-label="Step flow example with title node"
+        title={
+          <StepFlow
+            category="Main goal"
+            title={titleNode}
+            currentStep={step as Steps}
+            totalSteps={highestStep}
+            ref={stepFlowHandle}
+            showProgressIndicator
+            showCloseIcon
+            onDismiss={() => setIsOpen(false)}
+            mb="20px"
+            titleVariant="h2"
+          />
+        }
+      >
+        <Form
+          stickyFooter
+          leftSideButtons={
+            <Button buttonType="tertiary" onClick={() => handleClick("Back")}>
+              Back
+            </Button>
+          }
+          rightSideButtons={
+            <Button
+              buttonType="primary"
+              onClick={() => handleClick("Continue")}
+            >
+              Continue
+            </Button>
+          }
+        >
+          <Typography>
+            This is an example of a Dialog with a Form as content, with a Step
+            Flow to help users complete tasks in a specific order.
+          </Typography>
+          <Textarea label="Textarea label" onChange={() => {}} value="" />
+        </Form>
+      </Dialog>
+    </>
+  );
+};
+ExampleImplementationWithTitleNode.storyName =
+  "Example Implementation with title node";
diff --git a/src/components/step-flow/step-flow.pw.tsx b/src/components/step-flow/step-flow.pw.tsx
index 8ba96fa2ef..77a5c7a2b0 100644
--- a/src/components/step-flow/step-flow.pw.tsx
+++ b/src/components/step-flow/step-flow.pw.tsx
@@ -1,301 +1,10 @@
 import React from "react";
-import { test, expect } from "../../../playwright/helpers/base-test";
-import {
-  checkAccessibility,
-  getDesignTokensByCssProperty,
-} from "../../../playwright/support/helper";
-import {
-  StepFlowComponent,
-  StepFlowComponentWithStepFlowTitleNode,
-  StepFlowComponentWithRefAndButtons,
-  StepFlowComponentWithRefAndButtonsAndStepFlowTitleNode,
-} from "./components.test-pw";
-
-import { StepFlowTitle, Steps } from ".";
-
-import {
-  stepFlowProgressIndicator,
-  stepFlowCategoryText,
-  stepFlowTitleTextWrapper,
-  stepFlowTitleText,
-  stepFlowVisuallyHiddenTitleText,
-  stepFlowProgressIndicatorBar,
-  stepFlowLabel,
-  stepFlowDismissIcon,
-} from "../../../playwright/components/step-flow";
-
-import { button } from "../../../playwright/components";
-
-import { CHARACTERS } from "../../../playwright/support/constants";
-
-const testData = [CHARACTERS.DIACRITICS, CHARACTERS.SPECIALCHARACTERS];
-
-test.describe("Prop checks for StepFlow component", () => {
-  testData.forEach((stringVals) => {
-    test(`should render with the category prop, when the prop's value is ${stringVals}`, async ({
-      mount,
-      page,
-    }) => {
-      await mount(<StepFlowComponent category={stringVals} />);
-
-      await expect(stepFlowCategoryText(page)).toHaveText(stringVals);
-    });
-  });
-
-  testData.forEach((stringVals) => {
-    test(`should render with the title prop, when the prop's value is ${stringVals}`, async ({
-      mount,
-      page,
-    }) => {
-      await mount(<StepFlowComponent title={stringVals} />);
-
-      await expect(stepFlowTitleText(page)).toHaveText(stringVals);
-    });
-  });
-
-  (["h1", "h2"] as const).forEach((titleVariants) => {
-    test(`should render with the titleVariant prop, when the prop's value is ${titleVariants}`, async ({
-      mount,
-      page,
-    }) => {
-      await mount(
-        <StepFlowComponent title="foo" titleVariant={titleVariants} />,
-      );
-
-      await expect(page.locator(titleVariants)).toContainText("foo");
-    });
-  });
-
-  (["h1", "h2"] as const).forEach((titleVariants) => {
-    test(`should render with the titleVariant prop passed to the 'StepFlowTitle' sub component, when the prop's value is ${titleVariants}`, async ({
-      mount,
-      page,
-    }) => {
-      await mount(
-        <StepFlowComponent
-          title={
-            <StepFlowTitle titleString="foo" titleVariant={titleVariants} />
-          }
-        />,
-      );
-
-      await expect(page.locator(titleVariants)).toContainText("foo");
-    });
-  });
-
-  test("should render the correct element when 'showProgressIndicator' is true", async ({
-    mount,
-    page,
-  }) => {
-    await mount(<StepFlowComponent showProgressIndicator />);
-
-    await expect(stepFlowProgressIndicatorBar(page)).toBeVisible();
-  });
-
-  (
-    [
-      [1, 1],
-      [2, 1],
-      [2, 3],
-    ] as [Steps, Steps][]
-  ).forEach(([totalSteps, currentStep]) => {
-    test(`should render the correct label when the 'totalSteps' prop is passed as ${totalSteps} and 'currentStep' is ${currentStep}`, async ({
-      mount,
-      page,
-    }) => {
-      await mount(
-        <StepFlowComponent totalSteps={totalSteps} currentStep={currentStep} />,
-      );
-
-      if (totalSteps >= currentStep) {
-        await expect(stepFlowLabel(page)).toHaveText(
-          `Step ${currentStep} of ${totalSteps}`,
-        );
-      } else {
-        await expect(stepFlowLabel(page)).toHaveText(
-          `Step ${totalSteps} of ${totalSteps}`,
-        );
-      }
-    });
-  });
-
-  (
-    [
-      [1, 1],
-      [2, 1],
-      [2, 3],
-    ] as [Steps, Steps][]
-  ).forEach(([totalSteps, currentStep]) => {
-    test(`should render the correct visually hidden title when the 'totalSteps' prop is passed as ${totalSteps} and 'currentStep' is ${currentStep}, and the category and title props are also passed`, async ({
-      mount,
-      page,
-    }) => {
-      const category = "foo";
-      const title = "bar";
-
-      await mount(
-        <StepFlowComponent
-          totalSteps={totalSteps}
-          currentStep={currentStep}
-          category={category}
-          title={title}
-        />,
-      );
-
-      if (totalSteps >= currentStep) {
-        await expect(stepFlowVisuallyHiddenTitleText(page)).toHaveText(
-          `${category}. ${title}. Step ${currentStep} of ${totalSteps}.`,
-        );
-      } else {
-        await expect(stepFlowVisuallyHiddenTitleText(page)).toHaveText(
-          `${category}. ${title}. Step ${totalSteps} of ${totalSteps}.`,
-        );
-      }
-    });
-  });
-
-  ([1, 2, 3, 4, 5, 6, 7, 8] as Steps[]).forEach((totalSteps) => {
-    test(`should render the correct amount of progress indicators when the 'totalSteps' prop is passed as ${totalSteps}`, async ({
-      mount,
-      page,
-    }) => {
-      await mount(
-        <StepFlowComponent totalSteps={totalSteps} showProgressIndicator />,
-      );
-
-      expect(await stepFlowProgressIndicator(page).count()).toEqual(totalSteps);
-    });
-  });
-
-  test("should render the correct element when 'showCloseIcon' is true", async ({
-    mount,
-    page,
-  }) => {
-    await mount(<StepFlowComponent showCloseIcon />);
-
-    await expect(stepFlowDismissIcon(page)).toBeVisible();
-  });
-
-  test("background colour token should be correct when 'showCloseIcon' is true and the indicator is in progress", async ({
-    mount,
-    page,
-  }) => {
-    await mount(
-      <StepFlowComponent
-        currentStep={1}
-        totalSteps={1}
-        showProgressIndicator
-      />,
-    );
-
-    const backgroundColorToken = await getDesignTokensByCssProperty(
-      page,
-      stepFlowProgressIndicator(page),
-      "background-color",
-    );
-
-    expect(backgroundColorToken[0]).toBe("--colorsUtilityYin090");
-  });
-
-  test("background colour token should be correct when 'showCloseIcon' is true and the indicator is completed", async ({
-    mount,
-    page,
-  }) => {
-    await mount(
-      <StepFlowComponent
-        currentStep={2}
-        totalSteps={3}
-        showProgressIndicator
-      />,
-    );
-
-    const backgroundColorToken = await getDesignTokensByCssProperty(
-      page,
-      stepFlowProgressIndicator(page).nth(0),
-      "background-color",
-    );
-
-    expect(backgroundColorToken[0]).toBe("--colorsSemanticPositive500");
-  });
-
-  test("background colour should be correct when 'showCloseIcon' is true and the indicator is not completed", async ({
-    mount,
-    page,
-  }) => {
-    await mount(
-      <StepFlowComponent
-        currentStep={2}
-        totalSteps={3}
-        showProgressIndicator
-      />,
-    );
-
-    const backgroundColorToken = await getDesignTokensByCssProperty(
-      page,
-      stepFlowProgressIndicator(page).nth(2),
-      "background-color",
-    );
-
-    expect(backgroundColorToken[0]).toBe("--colorsActionDisabled600");
-  });
-});
-
-test.describe("Event checks for StepFlow component", () => {
-  test("should call onDismiss callback when a click event is triggered", async ({
-    mount,
-    page,
-  }) => {
-    let callbackCount = 0;
-    await mount(
-      <StepFlowComponent
-        showCloseIcon
-        onDismiss={() => {
-          callbackCount += 1;
-        }}
-      />,
-    );
-    await stepFlowDismissIcon(page).click();
-
-    expect(callbackCount).toBe(1);
-  });
-});
-
-test.describe("Ref checks for StepFlow component", () => {
-  test("should focus on title DOM element when a focus ref is passed", async ({
-    mount,
-    page,
-  }) => {
-    await mount(<StepFlowComponentWithRefAndButtons />);
-
-    await expect(stepFlowTitleTextWrapper(page)).not.toBeFocused();
-    await button(page).nth(1).click();
-
-    await expect(stepFlowTitleTextWrapper(page)).toBeFocused();
-  });
-
-  test("should focus on title DOM element when a focus ref is passed, and a node is passed to `title` with the `StepFlowTitle` as a descendant", async ({
-    mount,
-    page,
-  }) => {
-    await mount(<StepFlowComponentWithRefAndButtonsAndStepFlowTitleNode />);
-
-    await expect(stepFlowTitleTextWrapper(page)).not.toBeFocused();
-    await button(page).nth(1).click();
-
-    await expect(stepFlowTitleTextWrapper(page)).toBeFocused();
-  });
-});
+import { test } from "../../../playwright/helpers/base-test";
+import { checkAccessibility } from "../../../playwright/support/helper";
+import { stepFlowDismissIcon } from "../../../playwright/components/step-flow";
+import { StepFlowComponent } from "./components.test-pw";
 
 test.describe("Accessibility tests for StepFlow component", () => {
-  test("should pass accessibility checks when a node is passed to`title` with the `StepFlowTile` as a descendant", async ({
-    mount,
-    page,
-  }) => {
-    await mount(<StepFlowComponentWithStepFlowTitleNode />);
-
-    await checkAccessibility(page);
-  });
-
   test("should pass accessibility checks when component is rendered with required props", async ({
     mount,
     page,
@@ -305,33 +14,6 @@ test.describe("Accessibility tests for StepFlow component", () => {
     await checkAccessibility(page);
   });
 
-  test("should pass accessibility checks when component is rendered with a ref and buttons", async ({
-    mount,
-    page,
-  }) => {
-    await mount(<StepFlowComponentWithRefAndButtons />);
-
-    await checkAccessibility(page);
-  });
-
-  test("should pass accessibility checks when component is rendered with a ref and buttons and a node is passed to `title` with the `StepFlowTile` as a descendant", async ({
-    mount,
-    page,
-  }) => {
-    await mount(<StepFlowComponentWithRefAndButtonsAndStepFlowTitleNode />);
-
-    await checkAccessibility(page);
-  });
-
-  test("should pass accessibility checks when 'showProgressIndicator' is true", async ({
-    mount,
-    page,
-  }) => {
-    await mount(<StepFlowComponent showProgressIndicator />);
-
-    await checkAccessibility(page);
-  });
-
   test("should pass accessibility checks when 'showProgressIndicator' is true and there are completed, not completed and in-progress indicator steps", async ({
     mount,
     page,
diff --git a/src/components/step-flow/step-flow.stories.tsx b/src/components/step-flow/step-flow.stories.tsx
index ea1002be4a..26424ef440 100644
--- a/src/components/step-flow/step-flow.stories.tsx
+++ b/src/components/step-flow/step-flow.stories.tsx
@@ -28,7 +28,10 @@ const meta: Meta<typeof StepFlow> = {
   argTypes: {
     ...styledSystemProps,
   },
-  parameters: { controls: { disabled: true } },
+  parameters: {
+    controls: { disabled: true },
+    chromatic: { disableSnapshot: true },
+  },
   decorators: [
     (Story, context) => {
       const isExampleImplementation = context.name?.includes("Example");