`, then screenshot. Most components render differently in compact. 3. **Interactive/open state** — dropdown open, popover visible, focused, etc. ### Additional cases based on what the component supports Look at what the component can show and add cases accordingly: - **Item focus in dropdown** — open the picker, press ArrowDown to focus the first item, screenshot. Press again to focus a group header if present. - **Filtering** — type a character to filter suggestions, screenshot the narrowed list. - **Selected items / tokens** — pre-select items, screenshot the tokenized state. - **Value state** — when a component accepts `valueState`, write **three** `it` blocks per value state value: 1. **Basic** — component mounted with the value state prop, no interaction (screenshot at rest). 2. **Popover/dropdown open** — for components that have a dropdown or calendar popover (ComboBox, MultiComboBox, Select, DatePicker, DateRangePicker, DateTimePicker, MultiInput), open it and screenshot. The value state message strip appears inside the popover here. 3. **Focused, dropdown closed** — for the same components, open then close with Escape (or simply click the input area) so the component is focused but the dropdown is closed. A standalone value state message popover appears in this state, which has different rendering to the in-dropdown version. For Input and MultiInput (no dropdown), just click the input to focus. The full set of value state values is `Negative`, `Critical`, `Positive`, `Information`. `None` is the default and is already covered by the basic state test — do not add a separate case for it. Always include a `valueStateMessage` slot so the message strip renders. Applies to Input, MultiComboBox, Select, DatePicker, DateTimePicker, etc. - **No items** — empty list state (e.g. `` with no children, dropdown open). - **Wrapping / long content** — pass a very long text or many tokens to capture overflow/wrapping behaviour. ### What does NOT need its own test - Trivial prop changes that produce no visible difference. - States already covered by another `it`. There is no fixed maximum — cover what the component genuinely shows. ## Slot assignment Always assign slotted children as **child elements with a `slot` attribute**, never as JSX props on the parent component: ```tsx // WRONG — passing slot content as a JSX prop ...} footer={...} /> // CORRECT — slot attribute on the child element ...

Main content

... ``` This matches how web component slots work in the DOM. Passing slot content as a prop bypasses the slot mechanism and will not render correctly. Use attribute selectors, not tag names: ```tsx cy.get("[ui5-multi-combobox]") // correct cy.get("ui5-multi-combobox") // wrong ``` The attribute selector matches the `[ui5-*]` marker that web components add to themselves and is more resilient to tag name changes. ## Triggering interactions Always prefer the existing custom commands over raw DOM queries — they already handle waiting and shadow DOM traversal correctly. ### Nested shadow DOM — date/time pickers `DatePicker`, `DateRangePicker`, and `DateTimePicker` render their text field as an internal `ui5-datetime-input` component, which has **its own shadow DOM**. The native `` is therefore two shadow levels deep. Use: ```tsx cy.get("[ui5-date-picker]") .shadow().find("ui5-datetime-input") .shadow().find("input") .realClick(); ``` `shadow().find("input")` on the outer picker element will fail with "Expected to find element: input, but never found it." ### Available custom commands (use these for interactions) | Component | Command | What it does | |---|---|---| | `DatePicker` | `.ui5DatePickerValueHelpIconPress()` | Opens the calendar popover | | `TimePicker` | `.ui5TimePickerValueHelpIconPress()` | Opens the time picker popover | | `Menu` | `.ui5MenuOpen()` | Opens the menu popover | | `Menu` | `.ui5MenuOpened()` | Asserts menu is open (use after open) | | `ColorPalettePopover` | `.ui5ColorPalettePopoverOpen()` | Opens the color palette popover | | `DynamicDateRange` | `.ui5DynamicDateRangeOpen()` | Opens the DDR popover | | `TabContainer` | `.ui5TabContainerOpenEndOverflow()` | Opens the overflow tab list | | `Dialog` | `.ui5DialogOpened()` | Asserts dialog is open | | `Popover` | `.ui5PopoverOpened()` | Asserts popover is open | | `ResponsivePopover` | `.ui5ResponsivePopoverOpened()` | Asserts responsive popover is open | For components without a custom command, use `realClick()`: ```tsx // Open a select dropdown cy.get("[ui5-select]").realClick(); // Open a multicombobox dropdown via its icon cy.get("[ui5-multi-combobox]").shadow().find("[icon]").realClick(); ``` After triggering the interaction, call `cy.screenshot()` immediately — no assertions needed. ## Complete example The example below covers the full range of meaningful visual states for MultiComboBox — the same states tested in the openui5 visual regression suite: basic, open, filtering, item focus, tokens, value state, no items. ```tsx import MultiComboBox from "../../../src/MultiComboBox.js"; import MultiComboBoxItem from "../../../src/MultiComboBoxItem.js"; describe("MultiComboBox visual", () => { it("basic state", () => { cy.mount( ); cy.screenshot(); }); it("dropdown open", () => { cy.mount( ); cy.get("[ui5-multi-combobox]").shadow().find("[ui5-icon]").realClick(); cy.get("[ui5-multi-combobox]").shadow().find("ui5-responsive-popover").ui5ResponsivePopoverOpened(); cy.screenshot(); }); it("filtering — type to narrow list", () => { cy.mount( ); cy.get("[ui5-multi-combobox]").realClick(); cy.realType("B"); cy.screenshot(); }); it("dropdown open — first item focused via arrow key", () => { cy.mount( ); cy.get("[ui5-multi-combobox]").shadow().find("[ui5-icon]").realClick(); cy.get("[ui5-multi-combobox]").shadow().find("ui5-responsive-popover").ui5ResponsivePopoverOpened(); cy.realPress("ArrowDown"); cy.screenshot(); }); it("with selected tokens", () => { cy.mount( ); cy.screenshot(); }); it("value state — Negative", () => { cy.mount( Error message ); cy.screenshot(); }); it("value state — Negative — dropdown open", () => { cy.mount( Error message ); cy.get("[ui5-multi-combobox]").shadow().find("[ui5-icon]").realClick(); cy.get("[ui5-multi-combobox]").shadow().find("ui5-responsive-popover").ui5ResponsivePopoverOpened(); cy.screenshot(); }); it("value state — Negative — focused", () => { cy.mount( Error message ); cy.get("[ui5-multi-combobox]").shadow().find("input").realClick(); cy.screenshot(); }); it("value state — Critical", () => { cy.mount( Warning message ); cy.screenshot(); }); it("value state — Critical — dropdown open", () => { cy.mount( Warning message ); cy.get("[ui5-multi-combobox]").shadow().find("[ui5-icon]").realClick(); cy.get("[ui5-multi-combobox]").shadow().find("ui5-responsive-popover").ui5ResponsivePopoverOpened(); cy.screenshot(); }); it("value state — Critical — focused", () => { cy.mount( Warning message ); cy.get("[ui5-multi-combobox]").shadow().find("input").realClick(); cy.screenshot(); }); it("value state — Positive", () => { cy.mount( Success message ); cy.screenshot(); }); it("value state — Positive — dropdown open", () => { cy.mount( Success message ); cy.get("[ui5-multi-combobox]").shadow().find("[ui5-icon]").realClick(); cy.get("[ui5-multi-combobox]").shadow().find("ui5-responsive-popover").ui5ResponsivePopoverOpened(); cy.screenshot(); }); it("value state — Positive — focused", () => { cy.mount( Success message ); cy.get("[ui5-multi-combobox]").shadow().find("input").realClick(); cy.screenshot(); }); it("value state — Information", () => { cy.mount( Info message ); cy.screenshot(); }); it("value state — Information — dropdown open", () => { cy.mount( Info message ); cy.get("[ui5-multi-combobox]").shadow().find("[ui5-icon]").realClick(); cy.get("[ui5-multi-combobox]").shadow().find("ui5-responsive-popover").ui5ResponsivePopoverOpened(); cy.screenshot(); }); it("value state — Information — focused", () => { cy.mount( Info message ); cy.get("[ui5-multi-combobox]").shadow().find("input").realClick(); cy.screenshot(); }); it("no items — empty dropdown open", () => { cy.mount(); cy.get("[ui5-multi-combobox]").shadow().find("[ui5-icon]").realClick(); cy.screenshot(); }); }); ``` ## What NOT to do - No `.should()` assertions — this is a visual test, not a functional one. - No interactions unrelated to the component's own UI (don't open a Dialog just to show the component inside it). - No extra wrapper components to "set up" the test — if the component needs a value, pass it as a prop directly. - No `cy.wait()` or arbitrary timeouts — if you need to wait for an open animation, use `.ui5ResponsivePopoverOpened()` (chained off the popover element found in shadow DOM) to verify the popup is open before screenshotting. ## Avoid dynamic / non-deterministic content Screenshots must be identical on every run. Anything that changes between runs will cause false diffs and make the test useless as a visual baseline. **Avoid:** - `BusyIndicator` — the spinner animation frame varies per run. - Any component that fetches or derives content at runtime (clocks, relative timestamps, random IDs shown in the UI). ### Freezing time for date/time components Any component that calls `new Date()` internally — to format a value, highlight today in a calendar, or derive a relative label — will produce different screenshots on different days. This includes: - `Calendar`, `SpecialCalendarDate` — today's cell is highlighted - `DatePicker`, `DateRangePicker`, `DateTimePicker` — today is highlighted in the open calendar - `DynamicDateRange` — operators like `TODAY`, `LASTDAYS`, `NEXTWEEKS` format to the current date **Always add a `beforeEach` that freezes `Date` using `cy.clock`:** ```tsx beforeEach(() => { cy.clock(new Date("Jan 15, 2024").getTime(), ["Date"]); }); ``` The second argument `["Date"]` is critical — it stubs **only** the `Date` constructor and leaves `setTimeout`/`setInterval` untouched. Without it, `cy.clock()` also freezes timers, which breaks UI5's async rendering and causes all tests to time out. Use `Jan 15, 2024` as the standard fixed date across all tests in this repo for consistency. For `Calendar` and `SpecialCalendarDate`, pass a fixed `timestamp` prop instead of (or in addition to) `cy.clock` — the `timestamp` prop pins which month is displayed: ```tsx // Jan 15, 2024 in epoch seconds ``` For `DynamicDateRange`, also import all option classes so they register themselves before the component renders: ```tsx import "../../../src/dynamic-date-range-options/Today.js"; import "../../../src/dynamic-date-range-options/SingleDate.js"; // ... all options used in the test ``` ## Running the test ```bash cd packages/main npx cypress run --component --browser chrome --spec cypress/specs/visuals/ComponentName.cy.tsx ``` Or open interactive mode: ```bash cd packages/main yarn test:cypress:open ```