DEV Community: Sebastian Clavijo Suero

Podcast: QA Through the Lens of a Former PM Turned QA Engineer

Sebastian Clavijo Suero — Sat, 17 Oct 2026 18:38:27 +0000

I have been immersed in a lot of software stuff, some very good, some not that good. I was a software engineer for many years, but one of the roles where I learned more about product development was as a Product Manager after 5 years in that role.

I always was a quality advocate at heart, even during my developer phase, but I realized that I wanted to spend the rest of my career as a QA engineer, and building testing tools as an SDET that were not only useful but easy to use.

I invite you to watch the first 2 episodes of Ivan Davidov's podcast where we both discuss QA Through the Lens of a Former PM Turned QA Engineer (truly yours!) 🙂

Episode 1: Why Sprints Really Break, From a PM Turned QA (ft. Sebastian Clavijo)

Episode 2 (cont.): Fake It Till You Make It Is BS: A Staff QA's Career Rules

I hope you find it insightful and enjoy watching it.
PS: We had a lot of fun recording it! 😄

Cheers!

I'd love to hear from you! Please don't forget to follow me, leave a comment, or a reaction if you found this article useful or insightful. ❤️ 🦄 🤯 🙌 🔥

If you'd like to support my work, consider buying me a coffee or contributing to a training session, so I can keep learning and sharing cool stuff with all of you.
Thank you for your support!

Stop Guessing Where Your Accessibility Issues Are: Unleash the WICK-AG-Lens Chrome Extension to Target Them on the Spot 🎯

Sebastian Clavijo Suero — Tue, 06 Oct 2026 03:02:04 +0000

Table of Contents

ACT 1: EXPOSITION
ACT 2: CONFRONTATION
- Features Overview
  - 1. Show, Don't Just Tell (Visual Highlighting)
  - 2. The Separation of Concerns: Violations vs. Informative
  - 3. Strict WCAG Criteria Filtering
  - 4. Immediate Context & Interactive Panels
  - 5. Precision Element Locators
  - 6. Intuitive, Organized UI & Built-In Documentation
  - 7. Built for the Modern Web (Shadow DOM & Iframes)
  - 8. Zero-Friction Ticketing (One-Click Reporting)
- Audit Library and Ruleset
  - Tab 1: Violations and Warnings
  - Tab 2: Informative and Structure
- Limitations and Technical Bounds
ACT 3: RESOLUTION

ACT 1: EXPOSITION

Let's be brutally honest. For many teams, accessibility testing feels like eating vegetables. We know it matters. We want to do the right thing. But it almost always gets pushed to the very end of the meal (or sprint, either way). It becomes a chore, an afterthought, or worse, a massive QA bottleneck right before release.

Why? The feedback loop is broken.

Developers write code, push it, and maybe later a CI pipeline throws an error. Or a QA engineer logs a ticket with a vague description like, "Screen reader does not read this button." Then begins the tedious dance of inspecting the DOM, hunting for the exact element, and trying to remember the specific WCAG rule that was violated. The friction is incredibly high.

A while back, I introduced a Cypress plugin called wick-a11y, read the release article here. Think of it as your John Wick style ally for smashing accessibility barriers inside your E2E tests. It is great for guarding your pipeline. But what about before you even push your code? What if you could see accessibility issues as clearly as a glaring UI bug while you are actively developing?

Enter WICK-AG-Lens: Accessibility Inspector extension.

It is a brand new free and open-source Chrome browser extension designed to eliminate the friction between writing code and testing for accessibility. No more digging through console logs. No more guessing. Just immediate visual feedback directly within your page layout.

ACT 2: CONFRONTATION

Building an accessibility inspector is not just about throwing rules at a page. It is about how that information is presented to developers, QA testers, and accessibility professionals so they can actually use it. WICK-AG-Lens was engineered around a few core philosophies to drastically reduce your cognitive load.

Features Overview

1. Show, Don't Just Tell (Visual Highlighting)

Context is everything. Instead of printing a sterile list of errors in a DevTools console, WICK-AG-Lens draws highly visible bounding boxes and color-coded badges directly over the target elements on your page. Seeing a <button> without a label visually highlighted right where it sits in the layout immediately tells you how to fix it. Reading a console error requires mental translation.

2. The Separation of Concerns: Violations vs. Informative

A major source of fatigue in accessibility tooling is noise. To combat this, I divided the 40 independent audits into two distinct tabs: actionable violations and structural information checks.

Automated tools cannot understand intent. A script can easily verify that a focus path exists and check the order of tabindex attributes. But it takes a human to look at that highlighted path on the screen and realize the focus jumps wildly from the header, down to the footer, and back up to the main navigation. A machine sees valid code. A human sees a terrible user experience. By separating these tabs, developers can ruthlessly hunt real bugs in the Violations tab, while accessibility professionals and QA can explore the architecture in the Informative tab without the noise.

3. Strict WCAG Criteria Filtering

Not every project targets the same compliance standard. WICK-AG-Lens includes a dynamic filter bar allowing you to specifically toggle target WCAG Versions (2.0, 2.1, 2.2) and Conformance Levels (A, AA, AAA). The UI and execution engine will instantly adapt, hiding irrelevant audits or specific legend criteria (like differing AA vs. AAA contrast thresholds) so you only see exactly what you are testing for.

4. Immediate Context & Interactive Panels

Clicking on any badge on the page opens an interactive panel. This panel tells you exactly what the tool highlighted, why it is important for users with disabilities, and provides the exact CSS selector or logic applied to identify them.

5. Precision Element Locators

There is also a "View Elements" button in the DevTools panel. This opens a modal containing the list of all DOM elements identified by the accessibility audit. From there, you just click the crosshair icon next to an element and the extension instantly scrolls the affected element into view, marking it with a highly visible pulsating ring.

6. Intuitive, Organized UI & Built-In Documentation

The extension is designed for maximum configuration in a simple way. The panel utilizes expandable/collapsible category groups to keep your workspace clean and focused. It is fully keyboard-friendly. Plus, if you ever need a refresher on a rule, a complete documentation modal is embedded directly inside the extension, so no need to leave the browser or search a wiki to understand the technical bounds.

7. Built for the Modern Web (Shadow DOM & Iframes)

The modern web is a messy place. The scanner utilizes custom deep bottom-up traversal logic to pierce standard open web components to evaluate encapsulated markup. It also fully traverses the internal DOM of same-origin iframes, so you aren't left blind when inspecting complex widgets.

8. Zero-Friction Ticketing (One-Click Reporting)

QA engineers and testers spend half their lives writing bug tickets. WICK-AG-Lens includes a one-click reporting feature that instantly copies formatted text reports of all active audits and their findings directly to your clipboard. You just click the button, paste the clean text into Jira or GitHub, and move on.

Audit Library and Ruleset

WICK-AG-Lens performs 40 independent audits. Here is exactly what it is looking for under the hood:

Tab 1: Violations and Warnings

Keyboard Navigation

Unfocusable Clickables: Flags generic elements with onclick handlers lacking tabindex and role. Keyboard users cannot tab to or activate these elements.
- Severity: Critical
- WCAG Alignment: 2.1.1 Keyboard (2.0 A)
- Badge Output: "Unfocusable Clickable"
Disabled Focus Outlines: Parses page CSS via heuristic evaluation to find focusable elements where outline: none is applied on focus without a fallback. Sighted keyboard users rely entirely on focus rings.
- Severity: Critical
- WCAG Alignment: 2.4.7 Focus Visible (2.0 AA)
- Badge Output: "Disabled Focus Ring (Heuristic)"
Tabindex Violations: Flags elements with tabindex > 0, overriding natural DOM focus order and creating unpredictable navigation paths.
- Severity: Serious
- WCAG Alignment: 2.4.3 Focus Order (2.0 A)
- Badge Output: tabindex="{val}"
Accesskey Attributes: Flags explicit accesskey usage, which often conflicts with native browser or screen reader shortcuts.
- Severity: Moderate
- WCAG Alignment: 2.1.4 Character Key Shortcuts (2.1 A)
- Badge Output: accesskey="{val}"

Images & Media

Missing Alt Text: Flags <img> elements completely lacking an alt attribute. Screen readers will read the raw filename if missing.
- Severity: Critical
- WCAG Alignment: 1.1.1 Non-text Content (2.0 A)
- Badge Output: "Missing alt"
Uncaptioned Video: Flags <video> elements lacking nested <track> elements for captions.
- Severity: Critical
- WCAG Alignment: 1.2.2 Captions (Prerecorded) (2.0 A)
- Badge Output: "<video> (No Captions)"
Redundant Alt Text: Flags alt attributes containing words like "image" or "photo". Screen readers automatically announce images, making prefixes redundant.
- Severity: Minor
- WCAG Alignment: 1.1.1 Non-text Content (2.0 A)
- Badge Output: Redundant alt: "{text}"

Forms & Controls

Unlabeled Form Inputs: Flags form controls missing <label> wrappers, aria-label, or for attributes.
- Severity: Critical
- WCAG Alignment: 3.3.2 Labels or Instructions (2.0 A)
- Badge Output: "Unlabeled Input"
Empty Buttons: Flags buttons with no text, aria-label, or child image alt. Screen readers will only announce 'Button'.
- Severity: Critical
- WCAG Alignment: 4.1.2 Name, Role, Value (2.0 A)
- Badge Output: "Empty Button"
Placeholder as Label: Flags inputs relying solely on placeholders for their accessible name.
- Severity: Serious
- WCAG Alignment: 4.1.2 Name, Role, Value (2.0 A)
- Badge Output: "Placeholder as Label"

Links & Navigation

Empty Links: Flags <a> tags lacking readable text or accessible names.
- Severity: Critical
- WCAG Alignment: 2.4.4 Link Purpose (In Context) (2.0 A)
- Badge Output: "Empty Link"
Suspicious Link Targets: Flags anchor tags acting as buttons (href="#" or javascript:) without a button role, which breaks spacebar operability.
- Severity: Critical / Serious
- WCAG Alignment: 4.1.2 Name, Role, Value (2.0 A), 2.1.1 Keyboard (2.0 A)
- Badge Output: "Fake Button (JS)" or "Fake Button (#)"
Generic Link Text: Flags ambiguous link text like "Click Here" or "Read More" using exact word boundaries.
- Severity: Moderate
- WCAG Alignment: 2.4.4 Link Purpose (In Context) (2.0 A)
- Badge Output: Generic link: "{text}"
Unwarned New Window Links: Flags target="_blank" links lacking text or ARIA warnings, which unexpectedly disorients users.
- Severity: Moderate
- WCAG Alignment: 3.2.5 Change on Request (2.0 AAA)
- Badge Output: 'target="_blank" (No Warning)'

ARIA & Semantics

Focusable in Aria-Hidden: Flags elements that receive keyboard focus but are hidden from Assistive Technologies via aria-hidden="true" on the element or an ancestor, creating a "ghost focus" trap.
- Severity: Critical
- WCAG Alignment: 4.1.2 Name, Role, Value (2.0 A)
- Badge Output: "aria-hidden (Focusable)"
Invalid ARIA State: Flags elements marked with aria-invalid="true" indicating validation errors.
- Severity: Serious
- WCAG Alignment: 3.3.1 Error Identification (2.0 A)
- Badge Output: 'aria-invalid="true"'
Prohibited Author Names: Flags presentation or none roles that improperly contain aria labels, breaking semantics.
- Severity: Serious
- WCAG Alignment: 4.1.2 Name, Role, Value (2.0 A)
- Badge Output: Prohibited name on role="{role}"

Structure and Document

Auto-playing Media: Flags audio/video with autoplay enabled, which conflicts with screen reader announcements.
- Severity: Serious
- WCAG Alignment: 1.4.2 Audio Control (2.0 A)
- Badge Output: "Autoplay Media"
Heading Hierarchy Errors: Flags skipped sequential levels or fake structural classes to maintain logical document outlines.
- Severity: Moderate
- WCAG Alignment: 1.3.1 Info and Relationships (2.0 A)
- Badge Output: "{TAG} (Skipped)" or "Fake Heading"

Visual & Contrast

Text Color Contrast: Calculates the effective contrast ratio between visible text and its backing container, dynamically factoring in font-size and weight for large-text thresholds.
- Severity: Critical
- WCAG Alignment: 1.4.3 Contrast (Minimum) (2.0 AA), 1.4.6 Contrast (Enhanced) (2.0 AAA)
- Badge Output: AA Fail ({ratio}:1), AAA Fail ({ratio}:1), or Manual Check (Bg)

Tab 2: Informative and Structure

Keyboard Navigation

Tabindex (Comparison): Highlights all tabindex usages simultaneously to provide a visual map of the programmatic focus strategy.
- WCAG Alignment: 2.4.3 Focus Order (2.0 A)
- Badge Output: tabindex="{val}"
Display Focus Order: Traces and numbers the natural sequential path of focusable elements, dynamically flagging elements hidden from AT.
- WCAG Alignment: 2.4.3 Focus Order (2.0 A)
- Badge Output: #{counter}: <{tag}> or #{counter}: <{tag}> (Hidden from AT)

Images & Media

Display Image Alternatives: Extracts and visually prints the alt text for all <img> elements.
- WCAG Alignment: 1.1.1 Non-text Content (2.0 A)
- Badge Output: alt="{val}", alt="", or "Missing alt"
Captioned Video: Highlights video elements that correctly implement <track> captions.
- WCAG Alignment: 1.2.2 Captions (Prerecorded) (2.0 A)
- Badge Output: "<video> (Captioned)"
Iframe Context & Titles: Extracts explicitly defined titles from embedded iframes.
- WCAG Alignment: 4.1.2 Name, Role, Value (2.0 A)
- Badge Output: title="{title}", "Hidden Iframe", or "Missing Title"

Forms & Controls

Form Field Descriptions: Identifies supplemental instructional text linked to inputs via aria-describedby or title.
- WCAG Alignment: 3.3.2 Labels or Instructions (2.0 A)
- Badge Output: "aria-describedby" or "title"
Fieldsets & Captions: Highlights visual grouping containers and their titles.
- WCAG Alignment: 1.3.1 Info and Relationships (2.0 A)
- Badge Output: <{tag}>
Touch Target Sizes: Computes the exact width and height pixel boundaries of interactive elements to catch undersized targets.
- WCAG Alignment: 2.5.8 Target Size (Minimum) (2.2 AA), 2.5.5 Target Size (Enhanced) (2.1 AAA)
- Badge Output: {width}x{height}px

Links & Navigation

Warned New Window Links: Highlights target="_blank" links that correctly include accessible warnings.
- WCAG Alignment: 3.2.5 Change on Request (2.0 AAA)
- Badge Output: 'target="_blank" (Warned)'

ARIA & Semantics

ARIA Roles & Attributes: Maps all elements utilizing an explicit role definition.
- WCAG Alignment: 4.1.2 Name, Role, Value (2.0 A)
- Badge Output: role="{val}"
ARIA Live Regions: Maps dynamic aria-live injection containers.
- WCAG Alignment: 4.1.3 Status Messages (2.1 AA)
- Badge Output: aria-live="{val}"
Required Fields: Maps mandatory inputs enforced via HTML5 required or aria-required.
- WCAG Alignment: 3.3.1 Error Identification (2.0 A)
- Badge Output: "required" or 'aria-required="true"'
Aria-Expanded State: Maps expandable widgets, color-coded by true or false state.
- WCAG Alignment: 4.1.2 Name, Role, Value (2.0 A)
- Badge Output: aria-expanded="{val}"
Aria-Controls: Highlights elements that dictate the visibility of remote DOM elements.
- WCAG Alignment: 4.1.2 Name, Role, Value (2.0 A)
- Badge Output: "aria-controls"
Aria-Owns: Highlights elements establishing parent/child relationships outside the DOM tree.
- WCAG Alignment: 4.1.2 Name, Role, Value (2.0 A)
- Badge Output: "aria-owns"

Structure & Document

Valid Heading Order: Maps the standard, sequential H1 to H6 structure.
- WCAG Alignment: 1.3.1 Info and Relationships (2.0 A)
- Badge Output: <{tag}>
Landmark Regions: Maps native HTML5 and ARIA structural containers.
- WCAG Alignment: 2.4.1 Bypass Blocks (2.0 A)
- Badge Output: <{role or tag}>
Table & Grid Structure: Highlights native tables, captions, headers, and custom div-based grids.
- WCAG Alignment: 1.3.1 Info and Relationships (2.0 A)
- Badge Output: <{tag}> or role="{role}"
Lists and List Items: Maps unordered, ordered, and glossary lists and children.
- WCAG Alignment: 1.3.1 Info and Relationships (2.0 A)
- Badge Output: <{tag}>
Language Definitions: Maps the root document language declaration alongside inline phonetic shifts.
- WCAG Alignment: 3.1.1 Language of Page (2.0 A), 3.1.2 Language of Parts (2.0 AA)
- Badge Output: "Missing Root Lang", Root lang="{val}", or lang="{val}"

Limitations and Technical Bounds

Before you dive in, it is important to understand the technical boundaries of what an automated browser extension can and cannot do:

Visibility & Occlusion: It strictly ignores hidden elements (display: none, inert, hidden, etc.) to perfectly match the native accessibility tree, but it cannot calculate 3D visual occlusion (e.g., an element covered by a high z-index modal).
Shadow DOM & Iframes: It successfully pierces open Web Components and same-origin iframes. Closed shadow roots and cross-origin iframes (like embedded third-party videos) remain inaccessible due to strict browser security policies.
Contrast Heuristics: Contrast is calculated via computed DOM styles. While it dynamically computes thresholds based on font size and weight, elements layered over complex images or CSS gradients are automatically flagged for 'Manual Check'.
Filter Isolation: WCAG version and conformance filters are strictly isolated. Selecting '2.2' does not automatically include '2.1' or '2.0'. You must explicitly check all versions and levels you wish to evaluate for your current analysis.

ACT 3: RESOLUTION

Accessibility is not just a checkbox to tick off before a release. It is about making the web work for everyone. But that doesn't mean the process of building accessible software has to be painful.

With wick-a11y guarding your Cypress pipelines and WICK-AG-Lens riding shotgun in your browser, you have a pretty solid duo to keep the noise down and the quality up. The goal is to catch these barriers early, fix them fast, and get back to building cool things.

Don't wait around. Install the extension, pull up your favorite notoriously inaccessible website, and watch the badges light up like a hit list. No bloated audits, just sharp, uncompromising accessibility inspection.

Install WICK-AG-Lens from the Chrome Web Store

The entire blueprint is open-source on GitHub at sclavijosuero/wick-ag-lens. If it gets the job done, pay the bounty with a star on the repository. Otherwise, I might be forced to call my friend Johnny to set things straight. 😎

Cheers!

I'd love to hear from you! Please don't forget to follow me, leave a comment, or a reaction if you found this article useful or insightful. ❤️ 🦄 🤯 🙌 🔥

You can also connect with me on my new YouTube channel: https://www.youtube.com/@SebastianClavijoSuero

If you'd like to support my work, consider buying me a coffee, and I get my boost to keep learning and sharing cool stuff with all of you.

Thank you for your support!

The Cypress i18n Mistake: Testing Words Instead of Meaning - i18next is your partner

Sebastian Clavijo Suero — Sun, 10 May 2026 20:42:28 +0000

A Better Way to Test Multilanguage Apps in Cypress

Table of contents

ACT 1: EXPOSITION
ACT 2: CONFRONTATION
- The Problem With Copy-Pasting Translations
- What if Cypress Could Be Polyglot?
- Let Me Introduce You to i18next, If You Haven’t Met It Yet
- Where Should the Translations Live?
- Creating a Small cy.init() and cy.t() Commands
- What About Fallbacks?
- Running the Same Test Across Multiple Languages
- A Small Example With a Language Switcher: cy.changeLanguage()
- Should We Use Translated Text to Click Buttons?
- When Exact Text Actually Matters
- A Healthier Mental Model
- Interpolation: When Translations Need Dynamic Values
- Namespaces: When One Translation File Is Not Enough
- i18next Can Do More Than Just Interpolation
ACT 3: RESOLUTION

ACT 1: EXPOSITION

There is a very common situation that appears when testing applications that support multiple languages.

At first, everything looks innocent.
You have an application in English, so you write something like this:

cy.contains('Login').click()
cy.contains('Welcome back').should('be.visible')

Easy enough, right?

Then, one day, the Product team says: “We are going international!”
And suddenly your application also supports Spanish.

So now you write:

cy.contains('Iniciar sesión').click()
cy.contains('Bienvenido de nuevo').should('be.visible')

Easy enough!

Then French arrives.
Then Portuguese.
Then German.
And how about Mandarin?

After that someone from UX changes "Welcome back" to "Good to see you again".

And of course, the Spanish translator decides that "Bienvenido de nuevo" should actually be "Qué bueno verte de nuevo".

So your Cypress test fails, and then you ask yourself the existential automation question:

Is my test failing because the application is broken, or because somebody "improved" the copy?

And that, my QA friend, is where the fun begins.

There are some articles about internationalization in Cypress, but surprisingly, not that many.

And as a multicultural and multilingual person, I have always been interested in how, a well-designed multilingual website, can connect with people across languages, cultures, and contexts, and in doing so, create a much bigger impact.

ACT 2: CONFRONTATION

The problem is not testing multilingual applications. Obviously, we absolutely should test them.

The problem (and big mistake) starts when we copy-paste translated text directly into our Cypress tests and pretend that this is a stable strategy.

This could be a typical test for creating a new project while also validating the messages shown to the user:

cy.contains('Nuevo proyecto').click()
cy.contains('Nombre del proyecto').type('Mi proyecto Cypress')
cy.contains('Crear proyecto').click()

cy.contains('Proyecto creado correctamente')
  .should('be.visible')

This looks simple!
But what are we really testing?

Are we testing that the login flow works?
Are we testing that the _Spanish _translation exists?
Are we testing that the exact copy has not changed?
Are we testing that the translator did not open the thesaurus with too much confidence?

Maybe all of the above?
That is the problem.

Do not get me wrong.

Using cy.contains() with visible text is not evil at all. Actually, I like it a lot when it is used with intention. It makes tests readable, and in many cases, it reflects how users experience the application.

But in a multilingual app, hardcoded translated strings can quickly become a maintenance nightmare.

The test is no longer expressing the meaning of the user journey. It is expressing one particular version of the translated words at one particular moment in time.

In other words: We are testing words instead of meaning.

The Problem With Copy-Pasting Translations

A very common Cypress approach for testing the login user journey would look something like this:

cy.visit('/login?lng=es')

cy.contains('Iniciar sesión').click()
cy.contains('Bienvenido de nuevo').should('be.visible')

This works.
Until it does not! 🤔

The moment the Spanish translation changes, the test breaks, even if the application is working perfectly.

Of course, sometimes this is exactly what we want. If the purpose of the test is to validate a very specific legal disclaimer, marketing text, warning message, or compliance-related copy, then yes, the exact words matter.

But for most application flows, the exact words are not the real behavior.
The behavior looks something like:

The app loads in Spanish.
The login button is translated.
The user can log in.
The welcome message is shown in the selected language.

That is the meaning. The translated string is only the visible representation of that meaning.

So the real question is: How can Cypress verify the meaning without copy-pasting every translated word?

What if Cypress Could Be Polyglot?

Imagine this.

Instead of telling Cypress to find one exact Spanish sentence, we ask Cypress to find whatever welcome means in Spanish, and then we assert that the application shows it.

Something like this:

cy.t('auth.welcome', { lng: 'es' }).then((text) => {
  cy.contains(text)
    .should('be.visible')
})

A command like cy.t('auth.welcome', { lng: 'es' }) would get the Spanish translation for the auth welcome message, and then we can use that value in the assertion.

Now the test is not responsible for knowing the final translated sentence. The test only knows the meaning, and that, after all, is what is actually relevant for the test.

The key:

auth.welcome

represents the meaning.

The language:

es

represents the locale we want.

And the translation system takes care of the rest. Definitely that would be a much better contract.

The test would no longer be saying find "Bienvenido de nuevo", but find whatever auth.welcome means in Spanish.

Let Me Introduce You to i18next, If You Haven’t Met It Yet

If your application already uses i18next, then you probably already have the concepts we need.

But, at a very basic level, i18next gives us two important things:

A way to initialize the translation system.
A way to resolve a translation key into actual text.

The initialization happens with the i18next.init() method. This method receives a configuration object where we define things like the current language, fallback language, and translation resources:

i18next.init(options, callback) // returns a Promise

Something like this:

i18next.init({
  lng: 'es', // Current language
  fallbackLng: 'en', // Fallback language to use if message key not found
  resources: {
    en: { // English translations
      translation: { // "translation" is the default namespace (we will see namespaces later)
        auth: {
          login: 'Login', // Message auth.login in 'en'
          welcome: 'Welcome back' // Message auth.welcome in 'en'
        }
      }
    },
    es: { // Spanish translations
      translation: {
        auth: {
          login: 'Iniciar sesión', // Message auth.login in 'en'
          welcome: 'Bienvenido de nuevo' // Message auth.welcome in 'en'
        }
      }
    }
  }
})

The callback function can be used for example to inform in the console if something went wrong loading:

i18next.init({
  lng: 'es',
  fallbackLng: 'en',
  ...
}, (err, t) => {
  if (err) return console.log('Something went wrong loading', err);
  t('key'); // -> same as i18next.t
});

Then we can use the i18next.t() method to resolve a translation key into the corresponding text. In simple terms, the method t() receives a message key and an optional configuration object:

i18next.t(key, options)

For example:

i18next.t('auth.welcome', { lng: 'es' })

So the idea is very simple: Let Cypress use the same translation mechanism that the application might already use.

Where Should the Translations Live?

Writing all translations directly inside i18next.init() could be very ugly, specially if we have a very large number of messages.

Something like the .init example we used above may be fine for a tiny demo, but in a real application, it makes much more sense for translations to live in separate files.

For example:

// src/locales/en.json - English file
{
  "auth": {
    "login": "Login",
    "welcome": "Welcome back"
  }
}

// src/locales/es.json - Spanish file
{
  "auth": {
    "login": "Iniciar sesión",
    "welcome": "Bienvenido de nuevo"
  }
}

This is cleaner for a few reasons:

First, maintenance: Translations change often. Keeping them in JSON files makes them easier to update without touching test logic.

Second, abstraction: The test does not need to know every word in every language. It only needs to know the key that represents the meaning.

Third, it works like a dictionary. To adding a third, fourth, or fifth language becomes much easier, and your tests can still work like a charm.

You are basically saying "For this language, this key means this sentence." And that is exactly what we want.

A translation file is our dictionary.
Cypress should ask the dictionary.
Cypress should NOT become the dictionary.

Creating a Small cy.init() and cy.t() Commands

Now let’s make this easier to use inside Cypress, of course, using custom commands!

We can create two commands:

cy.initI18n() to initialize the translation system.
cy.t() to translate a key.

They something like this:

// cypress/support/commands.js

import i18next from 'i18next' // Do not forget "npm install i18next" first :)

import enMsgs from '../../src/locales/en.json' // English "dictionary"
import esMsgs from '../../src/locales/es.json' // The Spanish one

// cy.init() command will receive the exact same arguments as i18next.init()
Cypress.Commands.add('initI18n', (options = {}, callback) => {
  return cy.wrap(
    i18next.init({
      lng: 'en', // Use English as the default language if no language is provided
      fallbackLng: 'en', // The fallback language will be English
      resources: {
        en: { translation: enMsgs }, // Provide the English translations
        es: { translation: esMsgs }, // And the Spanish translations
      },
      ...options, // Pass along any other options supported by i18next.init()
    }, callback),
    { log: false } // Do not show the wrap() command in the Cypress Log
  )
})

/ cy.t() command will receive the exact same arguments as i18next.t()
Cypress.Commands.add('t', (key, options = {}) => {
  // Get the translation for the provided key in the currently configured
  // language, and apply any i18next options if provided.
  return cy.wrap(i18next.t(key, options), { log: false })
})

Now our tests can use this:

describe('Login page', () => {
  beforeEach(() => {
    // Initialize our polyglot Cypress system and set Spanish as current language
    cy.initI18n({ lng: 'es' })

    cy.visit('/login?lng=es')
  })

  it('Shows the login experience in Spanish', () => {
    cy.t('auth.login').then((loginText) => {
      cy.contains(loginText).click()
    })

    cy.t('auth.welcome').then((welcomeText) => {
      cy.contains(welcomeText).should('be.visible')
    })
  })
})

This is much better!

And if the Spanish translation changes from "welcome": "Bienvenido de nuevo" to "welcome": "Qué bueno verte de nuevo", then no drama.

We change the message in the corresponding translation file, and the test itself does not need to change because the meaning did not change.

Only the wording changed, and wording is exactly what translation files are supposed to manage.

What About Fallbacks?

Another nice thing about using i18next is that we can also use its language fallback behavior. A fallback is basically what happens when the translation you asked for does not exist in the selected language.

For example, when we initialize our message system like this:

cy.initI18n({
  lng: 'es', // Selected language is Spanish
  fallbackLng: 'en' // Fallback language is English
})

This means that if the Spanish translation is missing, try English.

This can be useful when the application itself behaves this way. And that last sentence is important:

Your Cypress configuration should reflect your application behavior. If your app falls back to English, your Cypress translation helper should also fall back to English.
If your app does not allow missing translations, your test should probably be stricter.

We can also resolve the key using a specific language directly from the cy.t() command, regardless of the language currently initialized:

cy.t('auth.forgotPassword', { lng: 'es' })

Or use a default value when the key cannot be resolved:

// Passing as a second argument
cy.t('my.key', 'This is the default value');

// Or within the options object
cy.t('auth.forgotPassword', {
  defaultValue: 'Forgot password?'
})

Or even better, instead of hardcoding a default value in the test, you can provide an array of fallback keys as the first argument. If the first key cannot be resolved, i18next will try the next one, and so on:

cy.t(['auth.forgotPassword', 'common.help']);

The important part is that our custom cy.t() command does not need to know every possible option.

It simply passes the options to i18next.t(), because it has been defined like this:

Cypress.Commands.add('t', (key, options = {}) => {
  return cy.wrap(i18next.t(key, options), { log: false })
})

We can use the power of i18next without reinventing it inside Cypress, which is always nice.

Because reinventing things inside Cypress tests is how many horror stories begin.

Running the Same Test Across Multiple Languages

Once we have this setup, testing multiple languages becomes much cleaner.

Check out this code:

// Supported languages
const languages = ['en', 'es', 'fr']

// Iterate over all supported languages
languages.forEach((lng) => {
  describe(`Login page in ${lng}`, () => {
    beforeEach(() => {
      cy.initI18n({ lng })
      cy.visit(`/login?lng=${lng}`)
    })

    it(`Shows the translated login experience for language ${lng}`, () => {
      cy.t('auth.login').then((loginText) => {
        cy.contains(loginText).click()
      })

      cy.t('auth.welcome').then((welcomeText) => {
        cy.contains(welcomeText).should('be.visible')
      })
    })
  })
})

We are not duplicating the same test with different hardcoded strings.

Instead we are expressing the real intention:

For each supported language, the login page should render the expected translated content.

It is cleaner.
It is less code.
It is more scalable.

And most importantly, that is easier to maintain when your application inevitably keeps changing. Because it will.

Applications always change.
That is their favorite hobby.

A Small Example With a Language Switcher: cy.changeLanguage()

To change the current language in i18next without re-initializing, we can use the i18next.changeLanguage() method. This method is designed to switch languages at runtime and will automatically trigger a re-render of components if you are using bindings like react-i18next.

i18next.changeLanguage(lng, callback) // returns a Promise

We can use i18next.changeLanguage() through a new Cypress custom command, cy.changeLanguage():

// cy.changeLanguage() command will receive the exact same arguments as i18next.changeLanguage()
Cypress.Commands.add('changeLanguage', (lng, callback) => {
  return cy.wrap(
    i18next.changeLanguage(lng, callback),
    { log: false }
  )
})

Then running the same tests across multiple languages would be something like this:

const languages = ['en', 'es', 'fr']

before(() => {
  cy.initI18n({ lng: 'en' }) // Initialize i18next once, using English by default
})

languages.forEach((lng) => {
  beforeEach(() => {
    cy.changeLanguage(lng)
    cy.visit(`/login?lng=${lng}`)
  })

  it(``Shows the translated login experience for language ${lng}`e`, () => {
    cy.t('auth.login').then((loginText) => {
      cy.contains(loginText).click()
    })

    cy.t('auth.welcome').then((welcomeText) => {
      cy.contains(welcomeText).should('be.visible')
    })
  })
})

No need to execute the full cy.initI18n() process for each language.

We initialize it once in the before() hook, and then we simply switch the current language in the beforeEach() hook before each test.

Should We Use Translated Text to Click Buttons?

Well...

It depends.

I know, I know. That is the classic "let me sit comfortably on the fence" answer.

But hear me out.

If your intention is to verify that the translated button text appears on the page, then using the translated value makes sense:

cy.t('auth.login').then((loginText) => {
  cy.contains(loginText).should('be.visible')
})

But if your intention is simply to interact with the login button and continue the test flow, then a stable selector like data-cy or data-testid, IMO, is usually a better option:

cy.get('[data-cy="login-button"]').click()

This is the distinction I personally like:

Use selectors to interact with the elements in the DOM.
Use translations to verify the localized user experience.

In this case:

cy.get('[data-cy="login-button"]').click()

cy.t('auth.welcome').then((welcomeText) => {
  cy.contains(welcomeText).should('be.visible')
})

the test does not depend on the button text to perform the click. But it still verifies that the expected translated welcome message appears.

That is a nice balance.

And as we know, balance is usually where maintainable test automation lives. Somewhere between chaos and overengineering.

Remember: Do not hide bad selectors behind i18n!

When Exact Text Actually Matters

Now, before someone sharpens their keyboard in the comments, let me clarify something.

I never said: never assert exact translated text. That would be too extreme. And extreme rules in testing usually age like milk.

There are cases where exact text absolutely matters:

Legal disclaimers
Error messages with regulatory requirements
Payment warnings
Accessibility instructions
Medical, financial, or security-related messages
Marketing copy that must be approved
Any text where the exact wording is the actual requirement

In those cases, exact matching is not only valid, it is absolutely a must.
But then make it intentional.

If this is the approved legal text:

const expectedLegalText =
  'By continuing, you agree to the Terms and Conditions.'

Then we should explicitly verify the full text:

cy.get('[data-cy="legal-disclaimer"]')
  .should('have.text', expectedLegalText)

This test is clearly saying and the exact wording matters here.

And if you still want that text to come from the translation system, you can combine both ideas:

cy.t('legal.termsAndConditions').then((expectedLegalText) => {
  cy.get('[data-cy="legal-disclaimer"]')
    .should('have.text', expectedLegalText)
})

The important part is the intention.
The problem is not text assertions.
The problem is accidental text assertions.

There is a big difference.

A Healthier Mental Model

A multilingual Cypress test should not try to prove every word in every language on every screen.

That sounds heroic, but it usually becomes slow, noisy, and painful to maintain.

A better multilingual test answers questions like:

Did the application load the expected language?
Did the important user-facing messages come from the right translation keys?
Can the user complete the main flow in that language?
Does the app still behave correctly when the locale changes?

That is much more valuable than copy-pasting 200 translated strings into a spec file and hoping nobody touches them.

Because they will be touched. They always are!
Again... that is their favorite hobby. 😄

Interpolation: When Translations Need Dynamic Values

So far, our translations have been static, but real applications love dynamic text.

For example:

'Welcome, Sebastian'

Invoice 1234 was created successfully

In i18next, this is usually handled with interpolation. That means the translation has placeholders, and we provide the values later.

For example:

{
  "auth": {
    "welcomeUser": "Welcome, {{name}}"
  },
  "invoice": {
    "created": "Invoice {{invoiceId}} was created successfully"
  }
}

Then in Cypress, we do not need to change our custom command. Since cy.t() already passes the options object directly to i18next.t(), any interpolation values we provide are handled by i18next automatically.

cy.t('auth.welcomeUser', { name: 'Sebastian' }).then((text) => {
  cy.contains(text).should('be.visible')
})

That resolves to:

Welcome, Sebastian

And you can also pass the desired language along with the interpolation values:

cy.t('invoice.created', { invoiceId: 1234, lng: 'es' }).then((text) => {
  cy.contains(text).should('be.visible')
})

It would resolve to whatever the Spanish translation for invoice.created is, with {{invoiceId}} replaced by 1234.

It is also possible to provide positional values if your app also uses them:

{
  "checkout": {
    "step": "Step {{0}} of {{1}}"
  }
}

Then:

cy.t('checkout.step', {
  0: 2,
  1: 5
}).then((text) => {
  cy.contains(text).should('be.visible')
})

That resolves to:

Step 2 of 5

The nice part is that our cy.t() command does not need to know if the translation is static, interpolated, simple, or complex.

It simply delegates to i18next.

Use the translation library for translation logic.
Use Cypress for testing.

Everyone stays in their lane.

Namespaces: When One Translation File Is Not Enough

As applications grow, one giant translation file can become painful. Very painful.

For that i18next supports namespaces. A namespace lets you split translations by area, domain, or feature.

For example:

src/locales/en/auth.json
src/locales/en/common.json
src/locales/es/auth.json
src/locales/es/common.json

English auth.json:

{
  "login": "Login",
  "welcome": "Welcome back"
}

English common.json:

{
  "save": "Save",
  "cancel": "Cancel"
}

Then we can initialize our 'polyglot Cypress' like this:

import enAuth from '../../src/locales/en/auth.json'
import enCommon from '../../src/locales/en/common.json'
import esAuth from '../../src/locales/es/auth.json'
import esCommon from '../../src/locales/es/common.json'

cy.init({
  lng: en,
  resources: {
    en: {
      auth: enAuth, // namespace auth (English)
      common: enCommon, // namespace common (English)
    }, 
    es: {
      auth: esAuth, // namespace auth (Spanish)
      common: esCommon, // namespace common (Spanish)
    }
  }

  // This tells which namespace to by default when not provided one in .t()
  defaultNS: 'common', 

  // It is also good practice to list all available namespaces
  ns: ['auth', 'common'] 
})

Here, auth is the default namespace, that means:

cy.t('login')

will look in the auth namespace by default.

But if we want something from common namespace instead, we will do this:

cy.t('save', { ns: 'common' }).then((text) => {
  cy.contains(text).should('be.visible')
})

Or use the namespace prefix format:

cy.t('common:save').then((text) => {
  cy.contains(text).should('be.visible')
})

Although both approaches can work, personally, I like using the namespace prefix style:

cy.t('save', { ns: 'common' })

But the most important thing is consistency.

Pick one style.
And stick to the plan!

Future you will be grateful... probably. 😉

i18next Can Do More Than Just Interpolation

Interpolation is only one part of what i18next can do. It also supports other features that can be useful in real applications, such as:

Formatting: useful for numbers, and values that need locale-specific formatting.
Plurals: when text changes depending on quantity, like "1 item" vs "5 items".
Context: useful when the translation changes depending on additional context, such as tone, audience, or grammatical differences.

And I will repeat one more time: The nice thing is that our Cypress command does not need special logic for each one, since we pass the options directly to i18next.t()! 😉

If you want to become an i18next master and explore all its options and methods (there are a lot!) check the official site: https://www.i18next.com/

ACT 3: RESOLUTION

Testing multilingual applications is not just about running the same test in different languages.

It is about deciding what your test should actually care about.

If your test hardcodes every translated string, you may end up with a suite that fails every time copy changes, even when the product works perfectly.

But if your test uses the same i18next translation keys as the application, your assertions become closer to the real meaning of the product.

The key idea is simple: Test the meaning, not the hardcoded words.

Use stable selectors for interactions.
Use translation keys for localization assertions.
Use exact text only when exact text is truly the requirement.

Use interpolation, namespaces, fallbacks, plurals, formatting, and context through i18next, not through custom Cypress reinventions.

That small shift will make your multilingual Cypress tests cleaner, less repetitive, and much easier to maintain.

So, the next time you are about to copy-paste a Spanish, French, Portuguese, German, or Klingon translation into your Cypress spec, pause for a second and ask yourself:

Am I testing the product behavior, or am I just testing today’s wording?

Because in multilingual testing, words change. Meaning should not.

Cheers!

I'd love to hear from you! Please don't forget to follow me, leave a comment, or a reaction if you found this article useful or insightful. ❤️ 🦄 🤯 🙌 🔥

👉 My LinkedIn: linkedin.com/in/sebastianclavijosuero
👉 My projects and plugin repos: github.com/sclavijosuero
👉 You can also connect with me on my new YouTube channel: youtube.com/@SebastianClavijoSuero

If you are feeling especially generous and enjoy my articles, you can buy me a coffee or contribute to a training session. In both cases, my brain will definitely thank you for it! ☕😄

WICK-DOM-OBSERVER: The Deterministic Cypress Plugin for Fast Spinners, Blinking Toasts, Optional Overlays, and UI’s Most Wanted

Sebastian Clavijo Suero — Sun, 22 Mar 2026 07:21:22 +0000

Because the most dangerous UI behaviors are the ones that leave almost no trace.

ACT 1: EXPOSITION

There are some UI elements that seem to exist for one noble purpose only: to make your Cypress tests miserable.

I am talking about the spinner that appears and disappears so absurdly fast that by the time Cypress gets there, it is already gone.

The toast that politely informs the user that something happened, but only for a tiny and inconvenient window of time.

And, of course, the annoying modal or overlay that shows up on page load only when it feels like it, blocks the whole page, and leaves your test suite wondering whether it should close it... or pretend it never existed.

These are not exotic edge cases. These are real UI behaviors we deal with all the time.

And the worst part is not even testing them. The worst part is testing them reliably.

Because traditional approaches usually push you toward one of these painful paths:

cy.wait(500) and pray.
Force the UI to behave unnaturally just for the test.
Add network intercepts and cross your fingers, hoping that somehow will be enough.
Write fragile logic that still flakes the moment the DOM decides to move just a little faster than usual.
And do not even get me started on what happens when all that reaches your project’s notoriously unpredictable CI pipeline.

That is exactly why I built wick-dom-observer.

⭐⭐⭐⭐⭐ Its mission is simple: help Cypress detect and validate those rebel UI elements that appear too fast, disappear too fast, or appear only sometimes, without turning your tests into a dramatic mess. ⭐⭐⭐⭐⭐

ACT 2: CONFRONTATION

Two commands. Same mission. Different entry point.

When the UI feedback is triggered after a click, use clickAndWatchForElement().

When the element may appear on its own, use watchForElement().

1) `clickAndWatchForElement()`

Use this one when the testing event starts with a user action: clicking a button, link, icon, or anything else that kicks off a spinner, toast, modal, or overlay.

cy.get(subject).clickAndWatchForElement(config)
cy.get(subject).clickAndWatchForElement(config, options)
cy.get(subject).clickAndWatchForElement(config, position)
cy.get(subject).clickAndWatchForElement(config, position, options)
cy.get(subject).clickAndWatchForElement(config, x, y)
cy.get(subject).clickAndWatchForElement(config, x, y, options)

2) `watchForElement()`

Use this one when there is no click involved and the element may show up by itself, like page-load overlays, announcements, promos, or optional blocking panels.

cy.watchForElement(config)

The shared `config` object

Both commands use the same config shape:

{
  selector: '...',
  assert: ($el) => { ... },
  action: ($el) => { ... },      // optional
  timeout: 4000,                 // optional
  appear: 'optional',            // 'optional' | 'required'
  disappear: false,              // optional
  pollingInterval: 10,           // optional
  mustLast: 800,                 // optional
}

What each option does

selector → the element you want to watch in the DOM
assert → synchronous assertion callback executed when the element is found
action → optional synchronous callback to perform side effects after assert passes
timeout → max time to wait for appear / disappear phases
appear: 'optional' → valid if the element appears or not
appear: 'required' → fail if the element never shows up
disappear: false → validate appearance only; do not wait for disappearance
disappear: true → also wait for the element to go away
pollingInterval → how often the DOM is checked
mustLast → minimum time the element must remain visible in the DOM

Important: assert() and action() must stay synchronous.

No cy.get(), no cy.wrap(), no Cypress commands inside them.

This is plain JavaScript / jQuery territory.

The mental model

clickAndWatchForElement() = trigger the event, then watch the DOM
watchForElement() = just watch the DOM
mustLast = make sure the element did not vanish too quickly
disappear: true = validate the full lifecycle, not just the appearance

Case 1: The super-fast spinner that mocks your test

The Mark

You click a button to load data.

A spinner appears, a loading label is shown, the button is disabled for a moment, the spinner disappears, and then the data is displayed.

Sounds easy enough to test, right?

What if the spinner only shows for 200ms? Or 100ms? Better yet, 25ms?

Because if that spinner is fast enough, this classic pattern can betray you:

it('shows the loading spinner and then displays the data', () => {
  cy.visit('/your-page')

  cy.get('[data-cy="load-data-btn"]').click()

  cy.get('[data-cy="service-spinner"]').should('be.visible')
  cy.get('[data-cy="loading-label"]')
    .should('be.visible')
    .and('contain', 'Fetching latest campaign analytics')

  cy.get('[data-cy="load-data-btn"]').should('be.disabled')

  cy.get('[data-cy="service-spinner"]').should('not.exist')
  cy.get('[data-cy="loading-label"]').should('not.exist')
  cy.get('[data-cy="load-data-btn"]').should('be.enabled')

  cy.get('[data-cy="campaign-table"]').should('be.visible')
  cy.get('[data-cy="campaign-row"]').should('have.length.greaterThan', 0)
})

Why? Because Cypress starts looking after the click has already happened, and if the spinner had a very short life in the DOM, you may miss it entirely.

So now you have a flaky test for a UI behavior that absolutely happens.

The Takedown

const assertLoadCampaignDataSpinner = ($el) => {
  // The spinner must be visible when observed.
  expect($el).to.be.visible()

  // Move to a stable parent scope so we can inspect related elements
  // that participate in the same loading flow.
  const $root = $el.closest('body')

  // Validate the loading label shown while data is being fetched.
  const loadingLabel = $root.find('[data-cy="loading-row"] .loading-label')
  expect(loadingLabel).to.be.visible()
  expect(loadingLabel.text()).to.contain('Fetching latest campaign analytics')

  // Validate that the trigger button is temporarily disabled
  const loadDataBtn = $root.find('[data-cy="load-data-btn"]')
  expect(loadDataBtn).to.be.visible()
  expect(loadDataBtn.prop('disabled')).to.eq(true)
}

it('shows the loading spinner and then displays the data', () => {
  cy.visit('/modal-table-demo.html')

  // Click the trigger button and start observing the DOM beforehand to catch the spinner
  cy.get('[data-cy="load-data-btn"]').clickAndWatchForElement({
    // Element to observe after the click.
    selector: '[data-cy="service-spinner"]',

    // The spinner is expected to appear in this flow.
    appear: 'required',

    // The spinner is also expected to disappear before the command finishes.
    disappear: true,

    // Max time (ms) to wait for the spinner to appear or disappear.
    timeout: 5000,

    // Run the custom assertions while the spinner is present.
    assert: assertLoadCampaignDataSpinner,
  })

  cy.get('[data-cy="loading-label"]').should('not.be.visible')
  cy.get('[data-cy="load-data-btn"]').should('be.enabled')

  cy.get('[data-cy="campaign-table"]').should('be.visible')
  cy.get('[data-cy="campaign-row"]').should('have.length.greaterThan', 0)
})

Why the Hit Lands 👊

The key trick is that clickAndWatchForElement() starts observing before the click happens, and an additional secret sauce.

And that matters a lot.

Cypress is already playing its own game here: its command queue runs asynchronously and processes commands at its own pace, while plain JavaScript, jQuery, and the DOM keep moving on a different timeline. So if you click first and only then ask Cypress to check for the spinner, there is a very real chance the DOM already did its thing and moved on.

That is why wick-dom-observer flips the sequence around: it prepares the observation flow first, performs the click, and then keeps observing the DOM to catch the exact moment the spinner appears and the exact moment it disappears.

What is the secret sauce? The MutationObserver interface.

It is the browser API designed to watch for changes in the DOM tree, which makes it a perfect fit for tracking fast UI elements.

In other words, this is not just about watching earlier. It is about watching on the right timeline.

So the example above using clickAndWatchForElement() validates the full user-facing behavior:

the spinner appears,
the loading label is visible and contains the expected text,
the action button is temporarily disabled,
and finally, the spinner disappears and the button is enabled again.

That is much closer to testing the real visual completion of the interaction than simply stubbing a network call and assuming everything on screen behaved correctly.

If you want to inspect how Cypress queued and executed everything around that flow, the cypress-flaky-test-audit plugin is a very good partner in crime.

If you feel even more reckless and want to understand how those two timelines actually interact — the Cypress queue and plain JavaScript — then you may want to venture into The Async Nature of Cypress: Don't Mess with the Timelines in Your Cypress Tests 'Dual-Verse'.

Case 2: The toast that tries to disappear before the witness sees it

The Mark

A toast is supposed to confirm that something important happened.

But if it appears and disappears too quickly, then from a user perspective it might as well have whispered the message into the void.

And from a testing perspective, this creates a second problem: it is not enough to prove the toast appeared. You may also want to prove it stayed visible long enough to actually matter.

That is exactly where mustLast enters the room.

The Takedown

// Assertion helper executed when the toast is detected.
// It validates the toast visibility and its success message.
const assertSuccessToast = ($el) => {
  // The toast must be visible while it is being observed.
  expect($el).to.be.visible()

  // The toast should contain the expected success message.
  expect($el.text()).to.contain('Campaign saved successfully')
}

it('validates that the success toast stays visible long enough', () => {
  cy.visit('/your-page')

  // Click the button and start observing the DOM beforehand
  // so the plugin can catch the toast as soon as it appears.
  cy.get('[data-cy="save-campaign-btn"]').clickAndWatchForElement({
    // Element to observe after the click.
    selector: '[data-cy="success-toast"]',

    // The toast is expected to appear in this flow.
    appear: 'required',

    // The toast is also expected to disappear before the command finishes.
    disappear: true,

    // Maximum time allowed for the full toast lifecycle.
    timeout: 8000,

    // Check the DOM very frequently so short-lived toasts are not missed.
    pollingInterval: 10,

    // Ensure the toast remains visible for at least 3 seconds.
    // This helps validate meaningful user-visible feedback, not just a blink.
    mustLast: 3000,

    // Run the custom assertions while the toast is present.
    assert: assertSuccessToast,
  })

  // After the lifecycle is complete, the toast should no longer exist in the DOM.
  cy.get('[data-cy="success-toast"]').should('not.exist')
})

Why the Hit Lands 🔨

This one is different from the spinner case.

With a spinner, the challenge is often just to catch it at all before it disappears.

With a toast, the challenge is more subtle: you also want to prove it did not vanish too soon. In other words, the problem is not merely appearance, but meaningful visibility.

That is exactly what mustLast is for.

So this test does not just verify that the toast showed up. It verifies something far more useful: that it stayed visible for at least a minimum amount of time before disappearing.

That is important, because a toast that flashes too fast may technically exist in the DOM, but from a UX perspective it is almost the same as not being there at all.

So in this case, clickAndWatchForElement() validates the full behavior:

the toast appears,
it contains the expected message,
it remains visible for at least the required duration,
and then it disappears.

That is far more aligned with actual user-facing feedback than just confirming that a success event happened somewhere in the background.

Case 3: The optional page-load overlay that shows up only when it feels like it

The Mark

Now let’s talk about one of the most annoying UI patterns ever created:

A modal / overlay / promo banner / “helpful” announcement panel that appears on page load only some of the time.

Sometimes it shows up.

Sometimes it does not.

When it does, it blocks the page, and you need to discard.
When it does not, your test should continue normally.

This is exactly the kind of behavior that makes tests nondeterministic if you handle it with normal Cypress assertions.

Because this will fail when the overlay does not exist:

cy.get('[data-cy="ad-overlay"]').should('be.visible')

And this is also not enough by itself:

cy.get('body').then(($body) => {
  if ($body.find('[data-cy="ad-overlay"]').length) {
    cy.get('[data-cy="close-ad-btn"]').click()
  }
})

That kind of conditional logic often becomes ugly, fragile, and inconsistent very quickly.

The Takedown

// This overlay is one of those annoying guests that may or may not show up.
// If it appears, handle it. If it does not, move on without failing the test.

it('handles an optional startup overlay without flaking', () => {
  cy.visit('/modal-table-demo.html')

  // Observe startup banner modal that may or may not appear on page load (about 50%)
  cy.watchForElement({
    // Element to observe in the DOM.
    selector: '[data-cy="ad-overlay"]',

    // The overlay may or may not appear, and both outcomes are valid
    appear: 'optional',

    // We do not require the plugin itself to wait for the overlay to disappear
    // as part of the command lifecycle
    disappear: false,

    // Maximum time to wait for the optional overlay to show up
    timeout: 1500,

    // Check the DOM very frequently so the plugin can catch the overlay
    // as soon as it appears
    pollingInterval: 10,

    // If the overlay appears, validate its visible state and confirm
    // the close button is present
    assert: ($el) => {
      // If the overlay appears, validate its visible state and confirm
      // the close button is present
      expect($el).to.be.visible()
      expect($el.find('[data-cy="close-ad-btn"]')).to.be.visible()
    },
    action: ($el) => {
      // Close the overlay via DOM click and verify the same it is no longer visible
      const closeBtnEl = $el.find('[data-cy="close-ad-btn"]')[0]
      if (closeBtnEl) closeBtnEl.click()
      expect($el).to.not.be.visible()
    },
  })

  // Rest of your test code
  cy.get('[data-cy="load-data-btn"]').should('be.visible')
  // [...]
})

Why the Hit Lands 🪏

This is where watchForElement() shines.

There is no click involved here. The command simply starts observing the DOM and waits to see whether the target element appears within the configured timeout.

And the crucial part is:

appear: 'optional'

That means both outcomes are valid:

if the overlay appears, the plugin runs the assert callback and then the action,
if the overlay never appears, the test still passes and continues normally.

This is huge, because it lets you model a truly real-world UI behavior without lying to the test and without introducing flaky branching logic.

Also, notice the action callback. That is very convenient here because when the overlay is actually found and validated, you can immediately close it in a deterministic way and unblock the rest of the page.

So instead of asking “will the overlay appear this time?”, your test says:

“If it appears, validate it and close it. If it does not, fine, move on.”

Case 4: The full real-world mess — optional overlay + required spinner flow

The Mark

Now let’s combine some of these problems into one realistic test flow.

You open a page.

Half of the time, an annoying overlay appears and blocks the page.

After dealing with that, the user clicks a button that triggers a loading spinner and a temporary loading state.

In other words:

one UI element is optional,
another one is required,
one appears automatically,
the other appears after a click,
and both need to be handled in one deterministic test.

This is the kind of scenario where many tests start becoming fragile little monsters.

The Takedown

// Assertion helper for the spinner/loading state.
// It validates the spinner itself plus the related UI signals.
const assertLoadCampaignDataSpinner = ($el) => {
  expect($el).to.be.visible()

  const $root = $el.closest('body')

  const labelFetching = $root.find('[data-cy="loading-row"] .loading-label')
  expect(labelFetching).to.be.visible()
  expect(labelFetching.text()).to.contain('Fetching latest campaign analytics')

  const loadDataBtn = $root.find('[data-cy="load-data-btn"]')
  expect(loadDataBtn).to.be.visible()
  expect(loadDataBtn.prop('disabled')).to.eq(true)
}

it('handles optional overlay and validates the spinner flow', () => {
  // Open the demo page that contains both behaviors:
  // an optional blocking overlay on load and a spinner triggered by a button click.
  cy.visit('/modal-table-demo.html')

  // First, watch for the optional overlay that may or may not appear on page load.
  // If it appears, validate it and close it so the rest of the test can continue.
  cy.watchForElement({
    selector: '[data-cy="ad-overlay"]',
    appear: 'optional',
    disappear: false,
    timeout: 1500,
    pollingInterval: 10,
    assert: ($el) => {
      expect($el).to.be.visible()
      expect($el.find('[data-cy="close-ad-btn"]')).to.be.visible()
    },
    action: ($el) => {
      const closeBtnEl = $el.find('[data-cy="close-ad-btn"]')[0]
      if (closeBtnEl) closeBtnEl.click()
      expect($el).to.not.be.visible()
    },
  })

  // Then, trigger the load-data action and observe the spinner lifecycle.
  // The spinner is required to appear and later disappear, while the custom
  // assertion helper validates the loading state during that window.
  cy.get('[data-cy="load-data-btn"]').clickAndWatchForElement({
    selector: '[data-cy="service-spinner"]',
    appear: 'required',
    disappear: true,
    timeout: 10000,
    assert: assertLoadCampaignDataSpinner,
  })

  // Finally, confirm the loading flow completed successfully
  // and the UI returned to its interactive state.
  cy.get('.loading-label').should('not.be.visible')
  cy.get('[data-cy="load-data-btn"]').should('be.enabled')
})

Why the Hit Lands 🪦

This example is the one I like the most because it represents the kind of ugly, imperfect, wonderfully realistic UI flow we often have to automate.

The plugin allows each moving part to be described according to its real behavior:

1) The overlay is treated as optional

It may appear or not, and the test remains stable in both cases.

2) The spinner is treated as required

Once the user clicks the button, the spinner must show up, pass the assertions, and disappear correctly.

3) The test still reflects what the user experiences

This is not a fake synchronization trick.

It is validating actual DOM behavior that the user would perceive:

a blocking overlay may interrupt the flow,
the user closes it,
the user click a button
then a loading state appears,
then it goes away,
then the UI becomes interactive again.

You are testing that the interface behaved properly under realistic conditions.

And yes, that includes those fast DOM transitions that traditional Cypress chaining can miss.

ACT3: RESOLUTION

Some UI elements are simply built like tiny rebels.

They show up too fast.

They disappear too fast.

They block your page unexpectedly.

They appear only half the time.

And then they sit there, very proudly, making your tests flaky and your patience shorter.

This is where wick-dom-observer turns those flaky little ghosts into observable DOM evidence.

It gives Cypress a much better chance to deal with these troublesome UI behaviors in a deterministic and elegant way, without forcing you into cy.wait(...) nonsense, awkward conditionals, intersects, or synthetic workarounds that do not really test real user experience.

So if your application contains:

fast spinners,
short-lived toasts,
startup overlays,
optional modals,
or any UI element that behaves like it does not respect authority...

then this plugin was made for you.

Because sometimes what your test suite really needs is not more waiting, not more retries, and definitely not more hope.

It needs a proper DOM observer.

You can find the plugin here:

GitHub repo: https://github.com/sclavijosuero/wick-dom-observer
npm: https://www.npmjs.com/package/wick-dom-observer

I'd love to hear from you! Please don't forget to follow me, leave a comment, or a reaction if you found this article useful or insightful. ❤️ 🦄 🤯 🙌 🔥

You can also connect with me on my new YouTube channel: https://www.youtube.com/@SebastianClavijoSuero

If you'd like to support my work, consider buying me a coffee or contributing to a training session, so I can keep learning and sharing cool stuff with all of you.
Thank you for your support!

WICK-A11Y v3.0.1: Cypress v16 Ready - Upgrade Without Fear (Fully Backward Compatible)

Sebastian Clavijo Suero — Sun, 15 Mar 2026 00:15:52 +0000

ACT 1: EXPOSITION

Ok, Cypress v16 is coming, and our always-friendly Cypress environment variables are going to be revamped.

Why? Security reasons. Cypress.env() variables are exposed in the browser, so they could potentially be accessed by "anyone."

Starting in Cypress v15.10.0, two new types of environment variables have been introduced: cy.env() (for private stuff) and Cypress.expose() (for non-sensitive information). The almighty Cypress.env() has been deprecated and will be gone starting in Cypress v16.

This article is not meant to explain what the change is in detail, or how you can migrate your existing Cypress framework to the new environment model. For that, you can (and will) find extremely helpful information in:

Cypress official documentation: Migrating away from Cypress.env() and Environment Variables & Secrets
Gleb Bahmutov's article: Migrating From Cypress.env To cy.env and Cypress.expose Methods.

However, because of this change, many open-source community plugins that rely on env variables for configuration or usage will need to be updated for the new environment variable model.

And the powerful and beloved plugin WICK-A11Y for accessibility in Cypress is no different, because it uses a couple of environment variables for configuration: enableAccessibilityVoice and generateReport.

ACT 2: CONFRONTATION

Since both of those environment variables are not storing sensitive information, they totally could be exposed ones. No biggie.

However, in your wick-a11y configuration inside your Cypress framework, you might have configured those variables in your cypress.env.json file, just like you may have done with all the other env variables in your system. Yeah, why not!

The thing is, in Cypress’s new env variable model, anything configured in cypress.env.json is automatically considered a private env variable.

That means it would need to be read with cy.env(), which is actually a Cypress command that can only be executed within a hook or a test.

So yeah, forget about accessing anything you defined in your cypress.env.json synchronously at the beginning of your test suite using the old Cypress.env() like:

const apiUrl = Cypress.env('apiUrl') // Will disappear

And no, you cannot do this either:

const apiUrl = cy.env('apiUrl') // Ouch. Right, it is a Cypress command!

You can only access environment variables asynchronously if they were defined as exposed variables in cypress.config.js under the expose property, or passed through the CLI with the --expose parameter.

Yeah... it makes sense, but this is not clearly warned anywhere in the Cypress documentation, so I learned it the hard way while migrating wick-a11y to be ready for Cypress v16.

And that was... interesting.

The thing is, wick-a11y, to do its wicked magic, accesses those two environment variables (enableAccessibilityVoice and generateReport) inside a Cypress event, not inside a Cypress hook or test.

This means they cannot be accessed using the cy.env() command, and instead have to be accessed synchronously with Cypress.expose().

Again, no biggie. I can make them exposed variables, but this might become an little inconvenience for YOU, my friend, using wick-a11y.

If you have configured those env variables in your wick-a11y implementation inside cypress.env.json and/or passed them through the CLI as --env parameters, then for wick-a11y to use them as exposed variables, you would need to move them into cypress.config.js or pass them through the CLI as --expose parameters instead.

And that means changing your CLI script definitions, messing around with your Cypress configuration, and cleaning up your cypress.env.json.

To avoid that, I prepared the wick-a11y accessibility plugin to accept both environment variables (enableAccessibilityVoice and generateReport) as either exposed or non-exposed. And that’s totally fine, because these are just configuration variables, no secrets hiding in the shadows here.

That means... you can migrate your project to Cypress v15.10.0 (or v16.0 when it comes out) while using the wick-a11y plugin WITHOUT ANY CHANGE in your Cypress framework.

WICK-A11Y v3.0.1 is fully backward compatible for Cypress v15.10.0 projects moving forward.

No fear! 🙂

Note that wick-a11y v3.0.1 is not intended for Cypress versions prior to 15.10.0.

ACT3: RESOLUTION

So, if you are already on Cypress v15.10.0+ and using the open-source wick-a11y accessibility plugin for Cypress... come on... install wick-a11y v3.0.1!

More cool features are coming soon in wick-a11y v3.

I also have updated the wick-a11y-sample-project to use Cypress v15.11.0 and wick-a11y v3.0.1

Cheers!

I'd love to hear from you! Please don't forget to follow me, leave a comment, or a reaction if you found this article useful or insightful. ❤️ 🦄 🤯 🙌 🔥

You can also connect with me on my new YouTube channel: https://www.youtube.com/@SebastianClavijoSuero

If you'd like to support my work, consider buying me a coffee or contributing to a training session, so I can keep learning and sharing cool stuff with all of you.
Thank you for your support!

Cypress.Promise.all() and cy.mapChain(): Two Hidden Gems for Cypress You Won’t Let Go Once You Try Them

Sebastian Clavijo Suero — Wed, 21 Jan 2026 03:55:43 +0000

Cleaner async patterns for sharper Cypress tests!

ACT 1: EXPOSITION

Most of us (if not all) are familiar with the JavaScript Array map() method. There is hardly anything better when you want to process or transform every element of an array into a new one based on a transformation function.

const array = [1, 3, 5, 7];

const newArray = array.map(x => x * x + 2)
// Expected output: Array [3, 11, 27, 51]

This example is trivial, of course, but that transformation function can be anything, from a simple calculation to something like a 90° clockwise matrix rotation. You name it!

I am sure many of us are also familiar with a very similar concept, but this time in the Cypress world. I am talking about the fantastic cy.map() command from the multifaceted cypress-map plugin by Gleb Bahmutov.

You pass a Cypress chainable (yielding an array or a jQuery object) as the subject, apply a JavaScript function to its yielded value, and it returns a new chainable whose elements are the result of that transformation. It can also map each object directly to one of its properties.

cy.wrap([1, 3, 5, 7])
  .map(x => x * x + 2)
// Expected output: Cypress Chainable [3, 11, 27, 51]

But what if what you want to apply to all the elements of the subject chainable is not a function, but another Cypress command? Or worse… what if you want to merge the results of multiple custom commands into a single output?

Yeah… now we’re talking. 😏

ACT 2: CONFRONTATION

A few months ago, I was working on a new plugin to handle internationalized messages in a Cypress framework (I will probably write an article about it in the future).

Without going into too much detail, it leverages the powerful JavaScript library i18next to manage multilingual message files, fallback languages, fallback translations, and many other features that simplify the often cumbersome task of multilingual management.

To provide a bit of context, translations for a given message ID and its arguments were returned by a Cypress custom command in the plugin, along with support and helper utilities for multilingual assertions.

You define all the translations of a message for each supported language, and then use a command like cy.getIntlMessage() to retrieve the appropriate one from those resources for the desired language.

// Messages definition
i18next.init({
    lng: 'en-US ',
    resources: {
        'en-US': {
            translation: {
                "hello": "Hello.",
                "my.age": "My age… {{age}} years!",
                "tell.me.your.age": "How old are you, {{name}}?",
            }
        },
        'es-ES': {
            translation: {
                "hello": "Hola.",
                "my.age": "Mi edad… ¡{{age}} años!",
                "tell.me.your.age": "¿Cual es tu edad, {{name}}?",
            }
        },
        'el-GR': {
            translation: {
                "hello": "Γεια σου.",
                "my.age": "Η ηλικία μου… {{age}} χρονών!",
                "tell.me.your.age": "Πόσων χρονών είσαι, {{name}};",
            }
        },
        // Rest of languages [...]
    }
    // Rest of i18next properties [...]
})

So a call to cy.getIntlMessage() like this:

// "my.age" is the message key, age is the interpolation key
cy.getIntlMessage("my.age", { lng: "es-ES", age: 100 })

It would yield a Cypress chainable holding the value "Mi edad… ¡100 años!" (in plain English: "My age… 100 years!")

And something like:

// "tell.me.your.age" is the message key, name is he interpolation key
cy.getIntlMessage("tell.me.your.age", { lng: "el-GR", name: "Toúla" })

It would yield a Cypress chainable holding the text "Πόσο χρονών είσαι, Toúla;" (or in English: "What's your age, Toúla?")

Nice, right?

Now let’s say we need to concatenate multiple internationalized messages into a single string when the translations come from a custom command, maybe to make an assertion or to fill an input field.

How would you do it?

"Hmmm..." 🤔

Using The All Times "Classic" Way

Given that Cypress code runs asynchronously in its own command queue, the chainable returned by a Cypress command cannot be stored in a regular JavaScript variables like:

// Forget about it! 🚫
const myAge= cy.getIntlMessage("my.age", { lng: "es-ES", age: 100 })

const tellMeYourAge = cy.getIntlMessage("tell.me.your.age", { lng: "el-GR", name: "Toúla" })

This is a big no-no in Cypress, and if you somehow still don’t believe me, check out my article "The Async Nature of Cypress: Don't Mess with the Timelines in Your Cypress Tests 'Dual-Verse'".

Sure, you can store the value in a Cypress alias or yield it to the next chained command:

// Stored in an alias (a single message)
cy.getIntlMessage("my.age", { lng: "es-ES", age: 100 }).as("myAgeMsg")

But how can you combine two messages returned by cy.getIntlMessage() into a single one?

"Why, you ask? That should be pretty easy-peasy!" 🥱

Yeah… fair enough. I bet most Cypress automation folks would instinctively write something like this:

cy.getIntlMessage("my.age", { lng: "es-ES", age: 100 })
  .then(message1 =>
    cy.getIntlMessage("tell.me.your.age", { lng: "el-GR", name: "Toúla" })
      .then(message2 => `${message1} ${message2}`)
  ).then(text => cy.log(text))

// Output in Cypress log: "Mi edad… ¡100 años! Πόσων χρονών είσαι, Toúla;"

The classic way!

Or, if you decide to go the alias route:

cy.getIntlMessage("my.age", { lng: "es-ES", age: 100 }).as("myAgeMsg")
cy.getIntlMessage("tell.me.your.age", { lng: "el-GR", name: "Toúla" }).as("tellMeYourName")

cy.get("myAgeMsg")
  .then(message1 =>
    cy.get("tellMeYourName")
      .then(message2 => `${message1} ${message2}`)
  ).then(text => cy.log(text))

// Output in Cypress log: "Mi edad… ¡100 años! Πόσων χρονών είσαι, Toúla;"

We could even create a custom Cypress command to simplify the concatenation, something like:

// Command to concat intl messages
Cypress.Commands.add('concatIntlMessages_classic'), (arg1, arg2) => {
  return
    cy.getIntlMessage(...arg1)
      .then(msg1 =>
        cy.getIntlMessage(...arg2)
          .then(msg2 => `${msg1} ${msg2}`)
    )
})

cy.concatIntlMessages_classic(
  ["my.age", { lng: "es-ES", age: 100 }],
  ["tell.me.your.age", { lng: "el-GR", name: "Toúla" }]
).then(text => cy.log(text))

// Output in Cypress log: "Mi edad… ¡100 años! Πόσων χρονών είσαι, Toúla;"

With the Cypress command, the test code looks cleaner. Very nice!

Ehhh… I’d say cleaner-ish.

"Why is that?" 🤨

And here is where I become the buzzkill…
What if it is not two messages, but three?
Four?
Five?

"Hmmm… just keep going. Nest as many .then() calls as you need!" 🥱🥱

So… let me get this straight.
You are suggesting we create a command chain that just keeps going…?
Something that, for four messages, looks like this:

Cypress.Commands.add('concatIntlMessages_classic_fantastic4', (arg1, arg2, arg3, arg4) => {
  return cy.getIntlMessage(...arg1)
    .then(msg1 =>
      cy.getIntlMessage(...arg2)
        .then(msg2 =>
          cy.getIntlMessage(...arg3)
            .then(msg3 =>
              cy.getIntlMessage(...arg4)
                .then(msg4 => `${msg1} ${msg2} ${msg3} ${msg4}`)
            )
        )
    )
})

cy.concatIntlMessages_classic(
  ["hello", { lng: "en-US" }],
  [" 🙂 "],
  ["my.age", { lng: "es-ES", age: 100 }],
  ["tell.me.your.age", { lng: "el-GR", name: "Toúla" }]
).then(text => cy.log(text))

// Output in Cypress log: "Hello. 🙂 Mi edad… ¡100 años! Πόσων χρονών είσαι, Toúla;"

I do not think so. I’m pretty sure we can do better than that.

Using Cypress.Promise.all()

Cypress.Promise.all is Cypress’s version of Promise.all, built on Bluebird. It lets you run multiple asynchronous operations at the same time and waits until all of them finish (or stops as soon as one fails).

You can learn about Cypress.Promise utility in the Cypress product documentation https://docs.cypress.io/api/utilities/promise. However, you will not find dedicated section showing Cypress.Promise.all, so let’s talk about that here.

At its core, Bluebird’s Promise.all() takes an iterable (usually an array) of Promises and returns one single Promise:

If every Promise resolves, the returned Promise resolves with an array of results (same order as the input).
If any Promise rejects, the returned Promise immediately rejects with the first error.

And that is exactly what we need to concatenate multiple translated messages returned by a Cypress command: gather them all, then merge them into a single string. After all, Cypress chainables walk, talk, and quack like promises. And that is precisely the universe in which Cypress.Promise.all was born. It takes an array of Cypress commands invocations, and returns a Premise that resolves to an array containing all resolved results, in order.

So let’s summon a custom command that does what we need:

Cypress.Commands.add('concatIntlMessages_promiseAll', (...commands) => {
  return cy.wrap(
    Cypress.Promise.all(commands),
    { log: false }
  ).then((text) => text.join(' '))
})

And the test code that uses it ends up looking something like this:

cy.concatIntlMessages_promiseAll(
  cy.getIntlMessage("hello", { lng: "en-US" }),
  [" 🙂 "],
  cy.getIntlMessage("my.age", { lng: "es-ES", age: 100 }),
  cy.getIntlMessage("tell.me.your.age", { lng: "el-GR", name: "Toúla" }),
).then(text => cy.log(text))

// Output in Cypress log: "Hello. 🙂 Mi edad… ¡100 años! Πόσων χρονών είσαι, Toúla;"

Let’s break this thing down plain and simple.

In the test code, we pass to our custom command cy.concatIntlMessages_promiseAll() a mix of inputs: several cy.getIntlMessage() chainables and even plain synchronous values (like [" 🙂 "] - why not?).
Cypress.Promise.all(commands) waits until every item has "settled" into a resolved value, then yields an array of results in the same order.
Finally, our .then((text) => text.join(' ')) concatenates that array into a single string, which is yielded as the result of the custom command.

"There you go!"

DISCLAIMER: I borrowed the line from My Big Fat Greek Wedding and the image from The New York Times article.

"Anything else?"

Please, be patient, we are not quite done yet.

Using cy.mapChain()

This Cypress command, cy.mapChain(), is available in the cypress-map plugin, and it was not familiar to me until quite recently. Once I stumbled upon it, I was pretty upset I had not discovered it earlier. That is what happens when you don’t read a plugin’s documentation all the way to the end. You miss these little gems!

After this "mea culpa", we are going to know what this command ("not a query!" as the own author stated) does:

It processes each element of the provided array-like chainable (an array or a jQuery object) individually, applies Cypress command functions to each one, and returns an array-like chainable with the same number of elements.

"What?! Apply a Cypress command? Not a regular function?" 🫨

Actually, you can also use synchronous, or even asynchronous, functions as well! 🤯

Cool, right? So, in a few words, it is like a cy.map() command whose mapping function can run Cypress commands, and it does not yield a result until all elements have been processed.

And to me, it seems like we could use this precisely to concatenate the results of our multiple cy.getIntlMessage() calls.

So the new custom command, and its invocation in a test, could look something like this:

// Custom command using cy.mapChain()
Cypress.Commands.add('concatIntlMessages_mapChain', (...args) => {
  // args should be arrays like ["hello", {lng:...}]
  return cy.wrap(args, { log: false })
    .mapChain(arg => cy.getIntlMessage(...arg))
    .then(messages => messages.join(' '))
})

// Command invocation
cy.concatIntlMessages_mapChain(
  ["hello", { lng: "en-US" }],
  [" 🙂 "],
  ["my.age", { lng: "es-ES", age: 100 }],
  ["tell.me.your.age", { lng: "el-GR", name: "Toúla" }],
 ).then(text => cy.log(text))

// Output in Cypress log: "Hello. 🙂 Mi edad… ¡100 años! Πόσων χρονών είσαι, Toúla;"

In the test code, we call cy.concatIntlMessages_mapChain() with several arguments, each representing the input needed to retrieve an internationalized message (for example, a message key, its language and options). These arguments define what messages we want and in which order.
Inside the custom command, cy.mapChain() is the key player. It takes that wrapped list of arguments and processes them one by one, running a Cypress command cy.getIntlMessage() for each element instead of a plain JavaScript function.
Finally, once mapChain() has processed all elements, the resulting array of messages is joined into a single string with .then((text) => text.join(' ')), and yielded as the result of the custom command.

cy.mapChain() waits until all those Cypress commands have finished and then yields an array with all the resolved values, in the same order, to be combined in this case in single message string.

And again... "there you go!"

⚠️ DISCLAIMER: Yeah, sorry! Using the same image twice in the same article might be a bit much for some, but I couldn’t help myself. I really love the movie, and especially Gus Portokalos. Still, probably not quite as powerful as what we’ll get in John Wick: Chapter 5. 😄

"Ok, fine. You win." 😜

ACT3: RESOLUTION

Ok, we have finally reached the end of our Greek movie detour, where we learned new expressions in all three languages and, along the way, a couple of really útiles Cypress εργαλεία.

Cypress.Promise.all() is ideal when we want to run multiple Cypress commands and wait for all of them to finish, with all the yielded values returned as an array-like chainable.

cy.mapChain() excels when we want to apply a custom command to all the elements of an array-like Cypress chainable and yield the results, also as an array-like chainable.

Cypress.Promise.all() and cy.mapChain(), although quite different in how they work, both helped solve the same problem, just with a little imagination.

One approaches it from the Promise side, coordinating multiple async operations and resolving them together, while the other stays firmly in Cypress territory, transforming values as they move through the command chain. Different mental models, same outcome: cleaner, more expressive tests.

You can find the examples of this article in GitHub here.

Now it is up to you to decide how you want to use them to make your automation experience a bit more pleasant.

Or maybe not... Your call, no judgment. 😊

And... "THERE YOU GO!!!" (one last time)

😆

I'd love to hear from you! Please don't forget to follow me, leave a comment, or a reaction if you found this article useful or insightful. ❤️ 🦄 🤯 🙌 🔥

You can also connect with me on my new YouTube channel: https://www.youtube.com/@SebastianClavijoSuero

If you are feeling especially generous and enjoy my articles, you can buy me a coffee or contribute to a training session. In both cases, my brain will definitely thank you for it! ☕😄

CYPRESS-FLAKY-TEST-AUDIT: thriving in the Cypress 'Dual-Verse' for once!

Sebastian Clavijo Suero — Fri, 02 Jan 2026 01:37:00 +0000

When flaky tests stop being random and start being a pattern, it is time to stop guessing and start auditing. This is the story of how to make peace with Cypress’ Dual-Verse... and actually win.

ACT 1: EXPOSITION

At some point in every Cypress project, a test fails.

You re-run it.
It passes.

You shrug, blame CI, and move on with your life.

Then it happens again. And again. And somehow only on Tuesdays, only in CI, or only when Mercury is in retrograde.

Welcome back to the Cypress Dual-Verse: the place where synchronous JavaScript and Cypress’ asynchronous command queue coexist peacefully… until they absolutely don’t.

If this sounds familiar, you are not alone. In one of my previous articles, I went deep (very deep) into why Cypress behaves this way and how mixing sync JS with async commands can quietly sabotage your tests:

👉 The Async Nature of Cypress: Don’t Mess With the Timelines

I definitely wanted to write an article about how this asynchronous command queue works, but I wanted to approach it in a way that is easier to understand and more intuitive, without sacrificing depth or the practical knowledge you actually need to tackle it effectively.

That is when I came up with the idea of presenting it as a quirky 'dual-universe' concept, using a very visual diagram so you can clearly see what is going on behind the scenes.

For a long time after publishing the article, a (somewhat crazy) idea kept spinning in my head… What if I could see a visual representation while implementing and running those rebellious tests that keep failing or behaving flakily, tests where I can’t quite put my finger on why, but I strongly suspect (and I’m usually right) that race conditions are to blame?

But man! This is not an easy task. It would mean diving deep into low-level test details and command interactions, then somehow turning all that chaos into something clear, understandable, and fully portable to a CI/CD pipeline.

And why stop there? Why not visualize it all with intuitive graphs (like in the 'dual-verse' article) that the human brain can actually enjoy digesting?

After all… you know the saying: a 🖼️ is worth more than a thousand long 📜📜📜. 😅

That is where CYPRESS-FLAKY-TEST-AUDIT plugin comes in.

ACT 2: CONFRONTATION

Flaky tests rarely announce themselves politely.

They don’t fail everywhere.
They don’t fail consistently.
And they definitely don’t fail when you are watching.

Most of the time, the root cause is subtle:

Cypress commands mixed with sync control flow
State captured too early
Variables that look populated… but aren’t (yet)
Assertions running outside the Cypress command chain

In other words: Dual-Verse violations.

The problem? These patterns are easy to write and painfully hard to spot, especially once your test suite grows beyond a handful of specs, or when you are staring at code written by someone else.

Presenting `cypress-flaky-test-audit`!

This plugin does one simple but powerful thing:

It scans your Cypress tests as they run and shows you (clearly and intuitively, no kidding!) what is running at every moment and exactly where things go wrong, making flakiness-prone patterns much easier to spot.

Not hypotheticals.
Not style opinions.
Real "this will bite you later" code smells.

And as someone wise once said…
"No gimmicks. No AI. Just the information you need to understand why a test is flaky". 🙂

It doesn’t rewrite your tests.
It doesn’t block your CI.

It simply shines a flashlight into the dark corners of your test suite.

You can run it locally, in CI, or as part of a quality gate, and decide how strict you want to be.

What the plugin actually does (and how that helps you)

Unlike a static pattern detector or flake predictor, cypress-flaky-test-audit gives you runtime insights into what your tests *actually did*, command by command.

In other words, it does not guess where flakiness might be; it shows you exactly what happened when your tests ran.

At a practical level, it provides:

🧠 Per-command execution details

For every Cypress command in a run, you get:

the exact execution order
timing information
how many retries happened
whether each command passed or failed

You can immediately see which commands took longer than expected, retried often, or didn’t execute at all. This is much more actionable than a static linter.

Why it helps:

When a test flops in CI but works locally, you can compare these metrics and see what changed, instead of guessing.

⏱ Timing and latency observations

The plugin highlights command durations — which can be telling when:

network responses are slow
UI takes time to load
intermittent server delays impact your tests

Why it helps:

Instead of "this fails sometimes", you see "this command took 4× longer in CI than locally."

🔁 Retry tracking

Cypress retries certain commands automatically, and you can now see:

which commands retried
how many times
whether retries eventually succeeded or still failed

This is especially useful for flaky assertions or slow elements.

Why it helps:

You will stop writing defensive cy.wait() hacks and start understanding when and why Cypress is retrying under the hood.

🚦 Clear pass/fail status per command

Every command is annotated with its success/failure state in the audit output, giving you:

confidence this test truly passed
insight into hidden failures that were masked by retries

Why it helps:

No more "it failed once but passed twice so I think it’s fine". You actually see the results, not just the final green light.

🔍 Comparing retries within the same test run

And this is my personal favorite!

One of the most underrated features is the ability to compare what happened between retries of the same test, especially when the first attempt fails and the retry somehow passes (ah yes… CI/CD, we meet again). 😅

Instead of seeing a single green checkmark and moving on, the audit lets you inspect:

what commands ran in the failed attempt
what commands ran in the successful retry
timing differences between both executions
commands that retried more aggressively in one attempt than the other

Why it helps:

Because "it passed on retry" is not a root cause.

By comparing both attempts side by side, you can spot subtle timing shifts, delayed elements, or network-dependent behavior that only shows up under certain conditions, all without re-running the test or adding guesswork.

This is where flaky tests stop being mysterious and start being debuggable.

In short, cypress-flaky-test-audit turns your test run into an observable timeline rather than a black box. Instead of hoping something is flaky, you get real data on what Cypress did and where your timing assumptions broke down.

How this actually helps you (and where you see the results)

All this data would be pointless if it stayed hidden.

CYPRESS-FLAKY-TEST-AUDIT is intentionally noisy in the right places and visual where it matters, so you can consume the results in whatever way fits your workflow.

Here is how.

🖥 Browser console output

During test execution, the plugin logs detailed audit information directly in the browser console.

You can see:

each Cypress command as it executes (in the precise order)
timing and retry information
which test retry you are currently looking at
subtle differences between attempts

Why this helps:

When debugging locally, you don’t need to leave the test runner. You can watch the Dual-Verse unfold in real time.

🧾 Terminal output (CI-friendly)

The same audit information is also available in the terminal output, making it CI-friendly by default.

This means:

no screenshots required
no guesswork when a test flakes in CI
actionable logs even when the test eventually passes on retry

Why this helps:

Because flaky tests don’t stop being flaky just because the pipeline turned green.

📊 HTML test audit report (where everything clicks)

This is where things really come together.

The plugin generates an HTML audit report that visualizes for a test suite:

every test
every retry
every command
execution timelines per attempt
pass/fail status and duration
what gets executed, and what is never reached

Each retry is displayed individually, and when a test fails first and passes on retry, you can compare both executions side by side.

And yes, if this looks familiar, that is intentional.

The graphs purposely resemble the ones used in The Async Nature of Cypress: Don’t Mess with the Timelines in Your Cypress Tests 'Dual-Verse', because they are designed to expose exactly the same thing: what Cypress did VS when you thought it did it.

Why this helps:

Seeing both timelines next to each other turns flakiness from a feeling into evidence. Timing gaps, delayed commands, and retry-heavy steps stop hiding behind a green checkmark.

In short, the plugin does not just tell you that a test retried. It shows you how each retry actually behaved, across the browser, the terminal, and a visual report that makes the Dual-Verse impossible to ignore.

You can interact with a fully functional HTML report here: https://sclavijosuero.github.io/samples/flaky-demo.html

Who this is for (and who it is not)

This is for you if:

You maintain a medium-to-large Cypress test suite.
You’ve seen tests fail in CI but magically pass locally.
You’ve ever said "just re-run it" and felt a tiny bit guilty.
You want guardrails, not lectures, around Cypress async behavior.
You’re a new QA engineer getting started with Cypress or a seasoned professional, because we all write flaky tests at some point, specially after we forget (again) about the Cypress 'Dual-Verse' gotcha.

This is probably not for you if:

You’re just getting started with Cypress and only have a handful of tests.
You’re intentionally ignoring Cypress’ command queue (no judgment… okay, maybe a little).
Your tests are already rock-solid and boring in the best possible way.

ACT3: RESOLUTION

The goal here is not to shame your tests.
We have all written code that works perfectly… until it doesn’t.

The real win is shifting from:
"Why is this flaky?"
to
"We know exactly where flakiness comes from."

Once you internalize and fully understand the Cypress execution model and back it up with automated auditing, something nice happens:

Tests become predictable
CI becomes boring (the good kind)
Failures start meaning something again

That is what I mean by thriving in the Cypress Dual-Verse.

Not fighting Cypress.
Not outsmarting it.
Just respecting the timeline, and letting a tool point out when you don’t.

Where to find it?

I'd love to hear from you! Please don't forget to follow me, leave a comment, or a reaction if you found this article useful or insightful. ❤️ 🦄 🤯 🙌 🔥

You can also connect with me on my new YouTube channel: https://www.youtube.com/@SebastianClavijoSuero

If you'd like to support my work, consider buying me a coffee or contributing to a training session, so I can keep learning and sharing cool stuff with all of you.
Thank you for your support!

WICK-A11Y v2.3.0: A Dazzling New Report, WCAG 2.2 AAA, and More Goodies

Sebastian Clavijo Suero — Mon, 08 Sep 2025 07:45:13 +0000

ACT 1: EXPOSITION

Yes, it was time to make a major improvement to the cooler plugin at the Round Table: the wicked 'Mr. Wick-A11y'.

So I’m not going to bore you with blah, blah, blah 📜📜📜,... let’s get straight to the point. 🎯

ACT 2: CONFRONTATION

There are a bunch of cool new features!

Support of WCAG 2.2 AAA

Yep, we've got the whole enchilada, enabling accessibility analyses all the way up to WCAG 2.2 AAA (whatever axe-core® supports).

Image from https://www.sweans.com

Mega Revamp of the HTML Report

Improved design and usability.
Fully mobile-responsive.
The report itself is WCAG 2.2 AAA compliant (or as close as possible).
Full keyboard navigation (no mouse required). 🚫🐭

Want proof?

Okay, this is what the old report looked like:

And this is the design of the new, dazzling report:

Pretty sassy, eh? That’s a mood!

Improved Reported Selectors

Uses data-cy, data-testid, data-test, data-qa, and data-test-id selectors for accessibility violations when available.

Cypress v15+

Supercharged Cypress support! WICK-A11Y v2.2.0+ now fully embraces Cypress v15.0.0+ powerful new features and its improved Cypress runner.

Image from https://www.cypress.io/blog

ACT3: RESOLUTION (wick-a11y 2.3.0)

Final word from our friend Wick: WCAG 2.2 AAA locked, HTML revamp in place, and a report that seals the deal. The web just got upgraded. The web just got upgraded.

You find it here https://www.npmjs.com/package/wick-a11y, and here https://github.com/sclavijosuero/wick-a11y!

Cheers, my QA friends!

Come on, friend! Follow me, leave a comment, or leave a reaction. Please don’t be shy! ❤️ 🦄 🤯 🙌 🔥

Also on my new YouTube channel: https://www.youtube.com/@SebastianClavijoSuero

Want to support my work? Buy me a coffee or chip in for a training, so I can keep learning and sharing cool stuff. Thanks for the support!

WICK-A11Y v2.2.0 x CYPRESS v15: Parabellum for Axe-ssibility Barriers

Sebastian Clavijo Suero — Mon, 01 Sep 2025 00:52:46 +0000

(Cover image from pexels.com by Bruna Sonore)

ACT 1: EXPOSITION

It has been just over a year since the WICK-A11Y open‑source accessibility plugin for Cypress saw the light, and became one of the most powerful and beloved tools in the Cypress community for fighting accessibility barriers in web apps.

Since then, there have been 14 releases, keeping the plugin at the top of accessibility tooling for Cypress test frameworks.

(Image from pexels.com by icon0 com)

And now, the brand‑new wick‑a11y v2.2.0 is fully supported in Cypress v15, just 10 days after the new Cypress version was officially released.

That’s because I saw this coming even before Cypress 15 dropped. I already knew two things:

The latest cypress‑axe v1.6.0 supported up to Cypress 14, so a new release of the library was likely imminent (they typically keep pace with the latest Cypress within days).
The Cypress Runner UX was going to change, and to keep wick‑a11y’s voice‑feedback feature working, I would need to dive back into the Runner UI.

As of Aug 30, 2025, Wick‑A11y v2.2.0 is live for Cypress v15.

ACT 2: CONFRONTATION

✨ What's new?

Basically 3 things:

All the existing wick-a11y capabilities are fully supported in Cypress v15:
- Comprehensive Accessibility Analysis
- Easy to Use and Highly Configurable
- Summary of Violations
- Detailed Violation Information
- Custom Styling
- Interactive Console
- HTML Reports
- Terminal Reports
- Voice Feedback
Support for cypress-axe v1.7.0.
Bug fixes:
- Fixed an issue where violation screenshots could not be copied to the HTML report folder when test folders were deeply nested.
- Other minor fixes.

👀 What's look like?

Still looks very cool, probably even cooler! 😎

Cypress Log and Interactive console

HTML Report

Voice Feedback

🤔 How to use it?

Just install the new wick-a11y v2.2.0 as a Dev Dependency in your Cypress v15 project (a new project or an existing one):

npm install wick-a11y -D

⚙️ Compatibility?

✔️ Wick‑a11y v2.2.0 is for Cypress v15+ projects, due to voice‑feedback dependencies on the new Cypress Runner UI.

✔️ Use wick‑a11y v2.1.0 for Cypress v14.x, which includes the latest patches and features for that line.

✔️ And wick‑a11y v1.4.0 or earlier for Cypress v12.x & v13.x.

ACT3: RESOLUTION

Now you have no excuse not to incorporate accessibility analysis into your Cypress v15 projects, because wick‑a11y v2.2.0 is:

More amazing than a flaky test turning green on the first try.
Cooler than John Wick in a tailored Kevlar suit tipping the Continental concierge.
More powerful than a High Table decree.
And kinder to screen readers than a perfectly labeled form, because that’s exactly what you’ll ship (or quite close).

Where to find:

npm: https://www.npmjs.com/package/wick-a11y
Github: https://github.com/sclavijosuero/wick-a11y
Video Tutorial: https://www.youtube.com/watch?v=WpdrXU-6xzc

⭐⭐⭐ Also, I want to give a special thanks to Peter M Souza Jr for his continuous contributions to keeping wick‑a11y robust and reliable.
You rock, man! 🤘

I'd love to hear from you! Please don't forget to follow me, leave a comment, or a reaction if you found this article useful or insightful. ❤️ 🦄 🤯 🙌 🔥

You can also connect with me on my new YouTube channel: https://www.youtube.com/@SebastianClavijoSuero

If you'd like to support my work, consider buying me a coffee or contributing to a training session, so I can keep learning and sharing cool stuff with all of you.
Thank you for your support!

The Almighty PLAYWRIGHT-SCHEMA-VALIDATOR: The Unstoppable Triumvirate Playwright + AJV + Zod

Sebastian Clavijo Suero — Mon, 04 Aug 2025 01:13:35 +0000

ACT 1: EXPOSITION

It's here! At last, the invincible PLAYWRIGHT-SCHEMA-VALIDATOR has arrived to impose the "Schema Peace" on any rebellious API that dares exist on this side of the Rubicon.

And it’s here wielding two powerful weapons: the classic AJV gladius and the newly forged, sharp ZOD trident.

But don’t be deceived, citizen! The PLAYWRIGHT-SCHEMA-VALIDATOR remains fully backward compatible with its venerable predecessor, the PLAYWRIGHT-AJV-SCHEMA-VALIDATOR, and allies seamlessly with the PW-API-PLUGIN to deliver an even more glorious display of schema violations, worthy of the Playwright Senate itself!

Let us behold how this almighty triumvirate can make your API testing as effortless and triumphant as a Roman victory parade.

ACT 2: CONFRONTATION

Sorry, my QA friend, I just couldn't resist! I am captivated by the Roman era, both the early Republic and the later Empire, so I had to theme this blog around that glorious epoch when so many boundaries were shattered.

And that is precisely what the PLAYWRIGHT-SCHEMA-VALIDATOR plugin sets out to do: shatter any wall that dares stand between you and flawless API validation.

New Features Available

With this new plugin, you will benefit from new features such as:

Full support for the AJV validator (for plain JSON schemas, Swagger documents, and OpenAPI schemas) as well as the ZOD validator (for Zod schemas).
Consistent display of schema validation errors, regardless of whether you use AJV or ZOD.
Ability to configure custom styles to present schema violations according to your team’s preferences (including icons and HEX colors).
Complete backward compatibility and support for all existing features found in its predecessor, playwright-ajv-schema-validator.

Complete List of Features

But if you want to know the full list of features included in the playwright-schema-validator plugin, here they are:

✔️ Function validateSchema() (and alias validateSchemaAjv()) performs a JSON Schema Validation and reports errors in the responses of network requests.

⭐ Schemas are provided as JSON objects.
⭐ Supports Plain JSON schemas, OpenAPI 3.x schema documents and Swagger 2.0 schema documents.
⭐ Utilizes the core-ajv-schema-validator, leveraging the Ajv JSON Schema Validator.

✔️ Fuction cy.validateSchemaZod() identifies and reports Zod schema validation errors in the responses of network requests.

⭐ Schemas are provided as Zod objects.
⭐ Uses the core-zod-schema-validator, leveraging the Zod Schema Validator.

✔️ The functions process the responses provided by Playwright API requests.

✔️ Provides a user-friendly view of schema errors and mismatches between the validated data and the JSON schema, clearly highlighting where each validation error occurred and the exact reason for the mismatch:

⭐ Total number of schema errors.
⭐ Full list of schema errors as provided by Ajv or Zod depending on the selected function.
⭐ A nested tree view of the validated data, clearly indicating the errors and where they occurred in an easy-to-understand format.

✔️ Allow custom styles (icons and text colors) to match the user's preferences for distinguishing schema errors.

✔️ Presents results to the user in a consistent format, regardless of whether the AJV Schema Validator or ZOD Validator is used.

✔️ Environment variables:

⭐ DISABLE_SCHEMA_VALIDATION to disable schema validation in your tests even when function validateSchema() is present.
⭐ LOG_API_UI to enable the display of API call details in Playwright UI and Trace Viewer .

⭐ LOG_API_REPORT to enable the display of API call details in HTML Report .

⭐ Integrates seamlessly with the pw-api-plugin but also works independently with standard Playwright API requests.

How to Migrate

To upgrade your Playwright framework from PLAYWRIGHT-AJV-SCHEMA-VALIDATOR to the new PLAYWRIGHT-SCHEMA-VALIDATOR, you only need to:

1) Uninstall the previous plugin:

npm uninstall playwright-ajv-schema-validator

2) Install the new plugin:

npm install -D playwright-schema-validator

3) Replace previous imports in your project:

Replace:

import { validateSchema } from 'playwright-ajv-schema-validator';

With:

import { validateSchema } from 'playwright-schema-validator';

No major refactoring required, just update your imports!

You can continue using the validateSchema() function with AJV schemas as before.
For AJV validation, you now also have the option to use the new validateSchemaAjv() alias.
For ZOD schema validation, the plugin provides the new validateSchemaZod() function.

Some Examples

Example 1: `validateSchemaAjv()` using Playwright standard API requests and overriding `issuesStyles`

    test('Should validate schema AJV of POST "/store/order" for Playwright standard API and custom Styles override', async ({ request, page }) => {
        const issuesStyles = {
            iconPropertyError: '🟦', colorPropertyError: '#5178eb',
            iconPropertyMissing: '🟪', colorPropertyMissing: '#800080'
        }

        const requestBody = {
            "id": 0,
            "petId": 0,
            "quantity": 0,
            "shipDate": "2024-01-01T00:57:29.231Z",
            "status": "placed",
            "complete": false
        }

        const responsePost = await request.post(`https://petstore.swagger.io/v2/store/order`,
            {
                data: requestBody,
                headers: { 'Content-type': 'application/json; charset=UTF-8'},
            }
        );

        expect(responsePost.status()).toBe(200)
        const responseBodyPost = await responsePost.json()

        await validateSchemaAjv(
            { page },
            responseBodyPost,
            petStoreSwaggerErrors,
            { endpoint: '/store/order', method: 'post', status: 200 },
            issuesStyles
        );
    });

Example 2: `validateSchemaAjv()` using `pw-api-plugin` with `pwApi` class

    test('Should validate schema of POST "/store/order" for pw-api-plugin and pwApi', async ({ request, page }) => {
        const requestBody = {
            "id": 0,
            "petId": 0,
            "quantity": 0,
            "shipDate": "2024-01-01T00:57:29.231Z",
            "status": "placed",
            "complete": false
        }

        const responsePost = await pwApi.post({ request, page }, `https://petstore.swagger.io/v2/store/order`,
            {
                data: requestBody,
                headers: {
                    'Content-type': 'application/json; charset=UTF-8',
                },
            }
        );

        expect(responsePost.status()).toBe(200)
        const responseBodyPost = await responsePost.json()

        await validateSchemaAjv(
            { page },
            responseBodyPost,
            petStoreSwaggerErrors,
            { endpoint: '/store/order', method: 'post', status: 200 }
        );
    });

Example 3: `validateSchemaZod()` using `pw-api-plugin` with `axiosApi` class

    test('Should validate schema ZOD of GET "/pet/findByStatusr" for pw-api-plugin and axiosApi and overriding `issuesStyles', async ({ request, page }) => {
        const responseGet = await axiosApi.get({ page }, `https://petstore.swagger.io/v2/pet/findByStatus?status=pending`,
            {
                findByStatusReq: { 'Content-Type': 'application/json' }
            }
        )

        expect(findByStatusReq.status()).toBe(200);
        const responseFindByStatus = await findByStatusReq.json();

        await validateSchemaZod(
            { page },
            responseBodyGet,
            petStoreSwaggerErrors
        );
    })

PLAYWRIGHT-SCHEMA-VALIDATOR: Just One Marvel in the Joyful Empire of the Wicked Schema Validators

If you want to perform schema validations not only in Playwright projects but also in any other Node projects, or even in Cypress, I have you covered!

Over time, I have created the Wicked Schema Validators ecosystem.

With this, you have all the weapons you need to conquer any API testing battlefield!

ACT3: RESOLUTION

Migrating to PLAYWRIGHT-SCHEMA-VALIDATOR is so effortless that, if you’re doing API testing in your Playwright framework, there’s really no excuse not to take advantage of this powerful plugin. 😅

Simply cross the Rubicon, and the empire of seamless API testing will be yours:

I'd love to hear from you! Please don't forget to follow me, leave a comment, or a reaction if you found this article useful or insightful. ❤️ 🦄 🤯 🙌 🔥

You can also connect with me on my new YouTube channel: https://www.youtube.com/@SebastianClavijoSuero

If you'd like to support my work, consider buying me a coffee or contributing to a training session, so I can keep learning and sharing cool stuff with all of you.
Thank you for your support!

The 'second' most abused (and misused) Cypress command ever: cy.contains()

Sebastian Clavijo Suero — Sat, 21 Jun 2025 06:02:14 +0000

(Cover image from pexels.com by Levi Damasceno)

ACT 1: EXPOSITION
ACT 2: CONFRONTATION
- What is .contains()?
  - It has a Dual Nature
  - It is a Cypress query
  - Some Overlooked Options
  - Selector Support
  - Contains with input[type="submit"] Element
- 12+1 Misuses of .contains() – some might even call it abuse
  - 1. Unnecessary Use of .should('exist') Assertion
  - 2. Misinterpreting Partial Matching
  - 3. Ignoring Whitespace Issues
  - 4. Ignoring Case-sensitivity Issues
  - 5. Assuming .contains() Returns All Matching Elements
  - 6. Using it for Too Broad Element Searches (VERY IMPORTANT!)
  - 7. Relying on .contains() for Only Visible Elements
  - 8. Relying on cy.contains Instead of Declarative Selectors
  - 9. Using .contains() Against Non-Readable or Elements
  - 10. Misuse of .contains() in Assertions for Non-Text Elements
  - 11. Misunderstanding .contains() with Dynamic Content
  - 12. Misuse of .contains() Accessing a Shadow DOM Element
  - 12+1. Chaining Incorrectly Multiple .contains()
- Diferences: .contains() vs .should('contains.text') vs .should('have.text')
- Preference Order When Looking for Elements
- New: .findOne() in Gleb Bahmutov's cypress-map Plugin
ACT3: RESOLUTION

ACT 1: EXPOSITION

About a year ago, I wrote an article about how cy.wait(TIME) is the most abused Cypress command ever, and it quickly sparked an interesting conversation among my fellow QAs.

When I asked which other Cypress command was excessively used but equally misunderstood or misused, the response was quite unanimous: cy.contains().

While I still firmly believe cy.wait(TIME) is the reigning champion of infamous commands in Cypress, I must admit that cy.contains() earns a solid silver medal.

Do not get me wrong, cy.contains() is one of my favorite and most powerful commands in the Cypress arsenal. But much like John Wick, it’s a double edged weapon, capable of incredible precision, yet risky if not handled correctly. This misuse frequently results in failing or flaky tests, making its misuse both widespread and often tricky to catch.

So yes, cy.contains() (amazing but often poorly executed), deserves, in my opinion, its spot as runner-up in the "most abused/misused Cypress commands" debate!

ACT 2: CONFRONTATION

What is `.contains()`?

According to the official Cypress documentation, it is used to get the DOM element containing the text. DOM elements can contain more than the desired text and still match.

In other words, it yields one DOM element that contains the passed substring.

It has a Dual Nature

It has a dual nature because it can start a new Cypress chain (searching the entire document for the content):

// Start a chain (search entire document)
cy.contains('my text')`

or use an existing chain (querying inside the DOM tree of the specified yielded element):

// Use an existing chain (search restricted within element with id 'list')
cy.get('#list').contains('my text')

It is a Cypress query

You must know that .contains() is a Cypress query that retries until all the chained assertions pass and the element exists in the DOM or until the timeout expires according to the defaultCommandTimeout in cypress.config.js. But this can be overridden with the timeout option.

// Timeout override in millisecs
cy.contains('my text', { timeout: 10000 })`

Because .contains() is a Cypress query, it not only retrieves the element matching the text but also performs an implicit assertion that the element must exist.

Some Overlooked Options

.contains() supports the log and timeout options, like many other Cypress commands and queries, but there are a couple of very important options that are often overlooked:

matchCase: To check case sensitivity. By default, it is true, meaning the match is case-sensitive.

// It will also find "My TEXT"
cy.contains('my text', { matchCase: false })`

includeShadowDom: To include in the match elements within the shadow DOM. With this option you can directly target elements within the Shadow DOM without using the .shadow() command explicitly. By default, it uses the includeShadowDom option in the cypress.config.js, or false if not specified.

// Includes elements inside Shadow DOM.
cy.contains('my text', { includeShadowDom: true })`

Note: A shadow DOM element is a hidden subtree attached to a regular DOM element, isolating its HTML and CSS from the main document to prevent conflicts and enable reusable, self-contained web components.

I would like you to try to remember these two options matchCase and includeShadowDom, as they’re going to come up again later.

Selector Support

An important thing to know about .contains() is that you can provide a selector to narrow and accelerate the search. When a selector is provided, it will return the DOM element that matches the selector, and either itself or one of its children matches the specified text.

For example, for this HTML:

<form>
  <label>Enter Password</label>
  <input id="password" placeholder="Enter your password"
         type="password">
</form>

If we execute a .contains() on the document using the text "Password":

// Obtains the <label> element that contains "Password" as text
cy.contains("Password")

Alternatively, if we execute a .contains() using the HTML tag form as the selector and the text "Password":

// Obtains the <form> element that contains "Password" in its DOM tree
cy.contains("form", "Password")

⚠️ Notice that, in the last case, although the element with the text "Password" is the <label>, .contains() will return the <form> element because it is the provided selector, and it contains a child with the text "Password" in its DOM tree.

Contains with `input[type="submit"]` Element

There is an interesting case with .contains() where it can find an <input> element with the attribute type="submit" and the attribute value contains the provided text.

For example, with the following HTML:

<div id="main">
  <form>
    ...
    <input type="submit" value="Send" />
  </form>
</div>

This command will execute successfully:

// It will find the <input> element of type submit with text "Send"
cy.contains("Send")

This is because input[type='submit'] is an element that behaves like a <button>, with its text in the value attribute. Therefore, .contains() also includes this specific type of element in the search.

Ok, now that we understand the theory, using .contains() in our test shouldn’t be too hard, right? 😎

Well, most likely not.

But what if I told you that this mighty command is, unfortunately, often misused in Cypress tests, making them flakily unpredictable?

Don’t believe me? 🩳🔥
Alright, let me explain!

12+1 Misuses of `.contains()` – some might even call it abuse

1. Unnecessary Use of `.should('exist')` Assertion

Misuse
Unnecessarily chaining the assertion .should('exist') after .contains() to ensure the element is present in the DOM.

// Chaining `.should('exist')` after `.contains()` is unnecessary
cy.contains('my text').should('exist');

Better Practice
Do not include .should('exist'), as .contains() is a Cypress query (like .get()) and automatically waits for the element to exist and be in an actionable state.

// Directly use `.contains()`
cy.contains('my text')

2. Misinterpreting Partial Matching

Misuse
Users may not realize cy.contains() performs partial text matching by default, leading to unintended behavior.

// Matches both "Add to Cart" and "Address".
cy.contains('Add')

Better Practice
If you want an exact match, you can use a regular expression with special characters: start-of-string ^ and end-of-string $.

// Ensures it matches the whole word 'Add'
cy.contains(/^Add$/)

If you want to find an element that contains an exact text match, and part of the text comes from a dynamic variable, you can use new RegExp() to handle the dynamic value:

// Exact match for "John Wick"
let who = "Wick"
cy.contains(new RegExp(`^John ${who}$`))

3. Ignoring Whitespace Issues

Misuse
Passing text that doesn't account for formatting, such as extra spaces and newlines.

// Fails due to extra spaces after the word "Cart"
cy.contains('Add to Cart   ')

Better Practice

Trim or format the text properly.

// Avoid trailing/leading spaces
const text = ' Add to Cart  '.trim()
cy.contains(text)

Or better yet, be precise in matching.

// Precise matching
cy.contains('Add to Cart')

4. Ignoring Case-sensitivity Issues

Misuse
Passing text that doesn't account for casing issues. By default .contains() is case-sensitive.

// Only finds an element with the exact text "add to cart" in all lowercase
cy.contains('add to cart')

Better Practice

If you want to find an element with the text "add to cart" regardless of its letter casing, you can use matchCase option.

// Enables case-insensitive matching
cy.contains('add to cart', { matchCase: false })

You could also write a regular expression to achieve the same goal of case-insensitive matching:

// Also enables case-insensitive matching
cy.contains(/add to cart/i);

5. Assuming `.contains()` Returns All Matching Elements

Misuse
Beginners often assume that .contains() retrieves all the elements that match the specified text, whereas it actually only selects the first matching element in the DOM.

For example, if your DOM contains multiple matching elements with the word "Enter":

<label>Enter Username</label>
<label>Enter Password</label>

Then this command will find only the first <label> element matching the text:

// Will find and return only the first <div> that contains "Enter",
// and that would be <label>Enter Username</label>
cy.contains('Enter')

Better Practice
To get all elements that contains the substring you can use cy.get() with :contains() jquery selector extension.

// Retrieves all elements in the DOM that contain the text "Enter"
cy.get(':contains("Enter")')

6. Using it for Too Broad Element Searches (VERY IMPORTANT!)

Misuse
Relying on cy.contains() without narrowing the context can cause the command to match unintended elements.

// Consider any element including text "Password" on the DOM
cy.contains('Password')

If there are multiple elements with the text "Password" on the page, this can lead to selecting the wrong element.

Better Practice

Let's consider the following HTML:

<form>
  <label>Enter Password</label>
  <input id="password" placeholder="Enter your password" type="password">
</form>

Approach A: Use a parent element or container to scope the search.

// Scoped to <form> or children elements within the <form> that match the text
cy.get('form').contains('Password') // Yields the <label> element

In this case:

cy.get('form') selects all <form> elements in the DOM.
Within these <form> elements, cy.contains('Password') finds a child element matching the text "Password" (in this case, the <label> element).

This approach is useful for constraining the scope of searchable elements before filtering by text.

Approach B: Leverage .contains() with a selector.

// Scope only to <form> elements that match the provided text itself or
// within one of their children
cy.contains('form', 'Password');  // Yields the <form> element

In this other case:

Finds the first <form> element anywhere in the whole DOM that contains the text "Password" within its DOM tree.

This is very useful for a quick search if you are looking for any <form> in the DOM that contains an element matching the text.

7. Relying on `.contains()` for Only Visible Elements

Misuse
Assuming that .contains() will only locate visible elements while ignoring hidden ones.

// The element containing 'Hidden Text' will be found even if the text is hidden
cy.contains('Hidden Text')

Beginners may mistakenly believe that .contains() will locate only elements that are visible. However, it will return the first element in the DOM that contains the specified text, regardless of its visibility.

Better Practice

To ensure you're working only with visible elements, you can use the :visible pseudo-selector.

Directly as part of a CSS selector:

Example 1.

// It will return a visible <div> element that contains the text "Username"
// or a child element within a visible <div> that contains the text "Username"
cy.get('div:visible').contains('Username')

Example 2.

// It will return a <div> element that contains the text "Username"
// or a <div> element whose child contains the text "Username"
cy.contains('div:visible', 'Username')

⚠️ Important: Note the nuance! Both might look similar, but they are slightly different and could yield completely different elements or even pass or fail the implicit assertion depending on the DOM tree under the <div> element.

Used in a .filter() command:

// It will return a visible <div> element that contains the text "Username"
// or a child element within a visible <div> that contains the text "Username"
cy.get('div').filter(':visible').contains('Password')

8. Relying on `cy.contains` Instead of Declarative Selectors

Misuse
Overusing .contains() instead of targeting elements by data attributes or selectors leads to brittle tests.

// It breaks if the text changes to something like "Remove"
cy.contains('Delete').click()

Better Practice
Utilize data attributes or stable semantic selectors.

// Robust and still readable (clearly we are targeting the 'delete' button)
cy.get('[data-cy="delete-btn"]').click()

9. Using `.contains()` Against Non-Readable or Elements

Misuse
Attempting to use .contains() with non-readable elements, such as <input> or <textarea>.

If your DOM includes an <input> element like this:

<input id="username" class="form-control" 
       placeholder="Enter your username" type="text">

And the user enters the text "John Wick" into the input field:

A .contains() command searching for "John Wick" in the <input> element will not find it:

cy.contains('input', 'John Wick') // This will fail

Better Practice
Use cy.get() for non-readable elements like <input>.

cy.get('input').should('have.value', 'John Wick') // This will pass

10. Misuse of `.contains()` in Assertions for Non-Text Elements

Misuse
Using .contains() to locate structural attributes (like value, alt or placeholder) instead of visible text.

If your DOM includes an <button> element like this:

<button id="submit-btn" alt="Submit Button">Submit</button>

The following will not work:

// This will fail because "Submit Button" is an alt attribute, not a visible text
cy.contains('button', 'Submit Button')

Better Practice
Use cy.get() for non-standard-text elements, like <alt> attribute.

cy.get('button').should('have.attr', 'alt', 'Submit Button');

11. Misunderstanding `.contains()` with Dynamic Content

Misuse
Failing to account for dynamically loaded content, causing intermittent errors.

// This might timeout if the assertion is made prematurely
cy.contains('Loading...').should('not.exist');

Better Practice
Chain .contains() with cy.wait() or cy.intercept() to handle async loading.

cy.intercept('GET', '/api/items').as('getItems');
cy.wait('@getItems');
cy.contains('Loaded Content').should('exist');

12. Misuse of `.contains()` Accessing a Shadow DOM Element

Misuse
If you attempt to access a Shadow DOM element while testing a standard DOM page without explicitly indicating to Cypress to account for shadow elements, it will not locate them.

A Shadow DOM element is part of a hidden DOM tree attached to a standard DOM element (known as the shadow host). This feature allows the encapsulation of styles and scripts, preventing them from influencing or being influenced by the rest of the document.

For example, consider this HTML with a Shadow DOM component that includes a button:

...
  <my-shadow-component>
    #shadow-root
    <button class="my-button">Click Me</button>
  </my-shadow-component>
...

If we try to locate the with text "Click Me" using .contains():

// This will not work because the button is inside a Shadow DOM
cy.contains('Click Me').click();

Better Practice
Use the includeShadowDom option set to true within .contains() to automatically traverse Shadow DOM boundaries.

// This will locate and interact with the <button> element inside the Shadow DOM
cy.contains('Click Me', { includeShadowDom: true }).click();

If you want to include Shadow DOM elements in all searches across your project, you can configure it globally in the cypress.config.js file by setting the includeShadowDom option to true. This way, you don’t need to include it in every .contains() call.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  // Other configuration options...
  includeShadowDom: true,
  // Additional options...
})

Alternatively, you can use the .shadow() command to traverse shadow DOM boundaries:

// This will locate and interact with the <button> element inside the Shadow DOM
cy.get('my-shadow-component')
  .shadow()
  .contains('Click Me')
  .click();

12+1. Chaining Incorrectly Multiple `.contains()`

Misuse
Sometimes, users do not realize that when performing a .contains() query, the yielded element may have changed. If you chain a second .contains(), the subsequent query will be applied to the element returned by the first .contains() and not to the original search context.

If we have this html:

...
<div id="#container">
   <label>User</label>
   <input id="username" placeholder="Enter your username" type="text"/>
   <label>Password</label>
   <input id="username" placeholder="Enter your password" type="password"/>
</div>
...

The chained contains() will fail the test:

// The second contains will fail
cy.get('#container').contains('User').contains('Password')

Why is that?

The first .contains('User') will locate the <label> element with the text "User".
The second .contains('Password') will be applied to the element returned by the first .contains(), which is a <label> element, and not the original element yielded by cy.get('#container').
As a result, the second .contains() query will fail.

Better Practice
Avoid chaining .contains() unless you are absolutely sure that the subsequent .contains() query will operate within the DOM tree of the element yielded by the first .contains().

// This test will pass
cy.get('#container').as('container')
cy.get('@container').contains('User')
cy.get('@container').contains('Password')

Diferences: `.contains()` vs `.should('contains.text')` vs `.should('have.text')`

Something I have noticed during my time working with Cypress is that quite a number of people, especially newer users, confuse the differences between .contains(), .should('contains'), and .should('have.text').

While they may seem quite similar at first glance, each has its own specific purpose and behavior that can significantly impact your test cases.

.contains('a_text'): Cypress query used to locate elements containing specific text within them. It searches the entire or part of the DOM (and optionally shadow DOM) to find elements with either partial or exact text. It’s primarily a selector.

// Finds any element that contains the exact text "Submit"
cy.contains('Submit').click();

.should('contains.text', 'a_text'): Assertion that checks if an element’s text includes a specific substring. It is not used to locate elements, but rather to validate that a particular element has text that contains the expected value. Other alias: contain.text, includes.text, and include.text.

// Asserts the element with class .greeting contains "Welcome" within its text
cy.get('.greeting').should('contains.text', 'Welcome');

.should('have.text', 'a_text'): Stricter assertion used to validate that an element’s text exactly matches the expected value.

// Asserts the text of the element with class .greeting is exactly "Welcome User"
cy.get('.greeting').should('have.text', 'Welcome User');

Preference Order When Looking for Elements

Cypress gives top priority to a selector when it is explicitly provided in the .contains() call.

If no selector is specified, Cypress defaults to selecting elements higher in the DOM tree when they are:

<input[type='submit']>
<button>
<a>
<label>

This means that if the element containing the text is a inside a element, .contains() will yield the <label> element instead of the <span>.

For example, in the following HTML:

...
<form>
  <label>
    <span>User</span>
    <input name="user" />
  </label>
</form
...

If we search for the element that contains the text "User":

// Yields the <label>, not the <span>
cy.contains('User').find('input')

New: `.findOne()` in Gleb Bahmutov's cypress-map Plugin

One week prior to when this article was written, Gleb Bahmutov introduced a new Cypress query .findOne() to his cypress-map plugin.

This new query finds one DOM element that exactly matches the provided text.

For the following HTML:

...
<div id="tools">
  <label>Mallet</label>
  <label>Power Hammer</label>
  <label>Hammer</label>
  <label>Sledgehammer</label>
</div>
...

The .findOne() command for the text "Hammer":

// It will yield <label>Hammer</label>
cy.get('#tools').findOne('Hammer')

This would be equivalent to using a regular expression for an exact match in a .contains():

// It will yield <label>Hammer</label>
cy.get('#tools').contains(/^Hammer$/)

The advantage of this command .findOne() is that it makes it much easier to find an element when the text is dynamic:

const type = 'Power'

// It will yield <label>Power Hammer</label>
cy.get('#tools').findOne(`${type} Hammer`)

And no need to use the cumbersome RegExp:

const type = 'Power'
// It will yield <label>Power Hammer</label>
cy.get('#tools').contains(new RegExp(`^${type} Hammer$`))

You can find a video about how to use .findOne() at this link.

ACT3: RESOLUTION

Well... Do you believe me now when I said at the beginning of this article that people abuse (or misuse) .contains() in many different ways?

Let me tell you, there are plenty of other ways to mess with this powerful Cypress query, but I stopped at 12+1 since this article is already quite lengthy. Besides, I really like the mystical number 13, and that's because I'm not superstitious (that might bring bad luck)! 😄

I'd love to hear from you! Please don't forget to follow me, leave a comment, or a reaction if you found this article useful or insightful. ❤️ 🦄 🤯 🙌 🔥

You can also connect with me on my new YouTube channel: https://www.youtube.com/@SebastianClavijoSuero

If you'd like to support my work, consider buying me a coffee or contributing to a training session, so I can keep learning and sharing cool stuff with all of you.
Thank you for your support!

Meet the New CYPRESS-SCHEMA-VALIDATOR: When ZOD Joined Forces with AJV for the Ultimate Validation Duo!

Sebastian Clavijo Suero — Mon, 09 Jun 2025 05:07:51 +0000

ACT 1: EXPOSITION

I am thrilled to introduce the new CYPRESS-SCHEMA-VALIDATOR plugin, the ultimate successor to CYPRESS-AJV-SCHEMA-VALIDATOR! Combining all the power of AJV schema validation from its predecessor and now also featuring ZOD Schema Validation, and new features. 🔥 🔥 🔥

The CYPRESS-SCHEMA-VALIDATOR is fully backward-compatible with the previous version, and continues to integrate smoothly with leading Cypress API plugins like @bahmutov/cy-api and cypress-plugin-api.

This new version represents a significant leap forward in flexibility, usability, and debugging efficiency.

ACT 2: CONFRONTATION

🤔 What’s New?

Support for Both AJV and ZOD Validators: Choose between AJV and ZOD for schema validation, offering versatility for diverse workflows.

Terminal Display of Schema Errors: Schema errors are now shown directly in the terminal during run mode, simplifying debugging.

Customizable Styles: Add a personalized touch by using custom icons and HEX colors to better distinguish validation issues.

Consistent Error Format: Enjoy unified error formatting, regardless of the validator selected (AJV or ZOD), for seamless and clear reporting during testing.

⏮️ Fully Backward Compatible?

AFFIRMATIVE! 🤟🤟🤟

🛸 How Do I Migrate?

Upgrading your Cypress framework from CYPRESS-AJV-SCHEMA-VALIDATOR to the new CYPRESS-SCHEMA-VALIDATOR is as simple as this:

1) Uninstall the previous plugin:

npm uninstall cypress-ajv-schema-validator

2) Install the new plugin:

npm install -D cypress-schema-validator

3) Replace previous imports in your project:

Replace:

import 'cypress-ajv-schema-validator'

With:

import 'cypress-schema-validator'

✔️ What About the existing `.validateSchema()` Command In My Code?

No worries, you don’t need to refactor your test cases beyond the imports!

The .validateSchema() command still works with AJV schemas.
A new alias, .validateSchemaAjv(), is also available for AJV validation.
Additionally, the plugin introduces .validateSchemaZod() for ZOD schema validation.

That's it, NO DRAMA-LAMA! 🦙🦙🦙

If you're looking for drama, check out my article series: The Test Drama: Cypress and Playwright, Who Steals the Show? 😁

ACT3: RESOLUTION

Don't wait! Upgrade your Cypress framework with the new CYPRESS-SCHEMA-VALIDATOR and enjoy unparalleled flexibility for schema validations using two of the most powerful validators available today: AJV and ZOD (plus many other perks).

You can find it in:

I'd love to hear from you! Please don't forget to follow me, leave a comment, or a reaction if you found this article useful or insightful. ❤️ 🦄 🤯 🙌 🔥

You can also connect with me on my new YouTube channel: https://www.youtube.com/@SebastianClavijoSuero

If you'd like to support my work, consider buying me a coffee or contributing to a training session, so I can keep learning and sharing cool stuff with all of you.
Thank you for your support!

DEV Community: Sebastian Clavijo Suero

Podcast: QA Through the Lens of a Former PM Turned QA Engineer

Stop Guessing Where Your Accessibility Issues Are: Unleash the WICK-AG-Lens Chrome Extension to Target Them on the Spot 🎯

ACT 1: EXPOSITION

ACT 2: CONFRONTATION

Features Overview

1. Show, Don't Just Tell (Visual Highlighting)

2. The Separation of Concerns: Violations vs. Informative

3. Strict WCAG Criteria Filtering

4. Immediate Context & Interactive Panels

5. Precision Element Locators

6. Intuitive, Organized UI & Built-In Documentation

7. Built for the Modern Web (Shadow DOM & Iframes)

8. Zero-Friction Ticketing (One-Click Reporting)

Audit Library and Ruleset

Tab 1: Violations and Warnings

Tab 2: Informative and Structure

Limitations and Technical Bounds

ACT 3: RESOLUTION

The Cypress i18n Mistake: Testing Words Instead of Meaning - i18next is your partner

A Better Way to Test Multilanguage Apps in Cypress

ACT 1: EXPOSITION

ACT 2: CONFRONTATION

The Problem With Copy-Pasting Translations

What if Cypress Could Be Polyglot?

Let Me Introduce You to i18next, If You Haven’t Met It Yet

Where Should the Translations Live?

Creating a Small cy.init() and cy.t() Commands

What About Fallbacks?

Running the Same Test Across Multiple Languages

A Small Example With a Language Switcher: cy.changeLanguage()

Should We Use Translated Text to Click Buttons?

When Exact Text Actually Matters

A Healthier Mental Model

Interpolation: When Translations Need Dynamic Values

Namespaces: When One Translation File Is Not Enough

i18next Can Do More Than Just Interpolation

ACT 3: RESOLUTION

WICK-DOM-OBSERVER: The Deterministic Cypress Plugin for Fast Spinners, Blinking Toasts, Optional Overlays, and UI’s Most Wanted

ACT 1: EXPOSITION

ACT 2: CONFRONTATION

1) clickAndWatchForElement()

2) watchForElement()

The shared config object

What each option does

The mental model

Case 1: The super-fast spinner that mocks your test

The Mark

The Takedown

Why the Hit Lands 👊

Case 2: The toast that tries to disappear before the witness sees it

The Mark

The Takedown

Why the Hit Lands 🔨

Case 3: The optional page-load overlay that shows up only when it feels like it

The Mark

The Takedown

Why the Hit Lands 🪏

Case 4: The full real-world mess — optional overlay + required spinner flow

The Mark

The Takedown

Why the Hit Lands 🪦

1) The overlay is treated as optional

2) The spinner is treated as required

3) The test still reflects what the user experiences

ACT3: RESOLUTION

WICK-A11Y v3.0.1: Cypress v16 Ready - Upgrade Without Fear (Fully Backward Compatible)

ACT 1: EXPOSITION

ACT 2: CONFRONTATION

ACT3: RESOLUTION

Cypress.Promise.all() and cy.mapChain(): Two Hidden Gems for Cypress You Won’t Let Go Once You Try Them

ACT 1: EXPOSITION

ACT 2: CONFRONTATION

Using The All Times "Classic" Way

Using Cypress.Promise.all()

Using cy.mapChain()

ACT3: RESOLUTION

CYPRESS-FLAKY-TEST-AUDIT: thriving in the Cypress 'Dual-Verse' for once!

ACT 1: EXPOSITION

ACT 2: CONFRONTATION

1) `clickAndWatchForElement()`

2) `watchForElement()`

The shared `config` object

Presenting `cypress-flaky-test-audit`!

Example 1: `validateSchemaAjv()` using Playwright standard API requests and overriding `issuesStyles`

Example 2: `validateSchemaAjv()` using `pw-api-plugin` with `pwApi` class

Example 3: `validateSchemaZod()` using `pw-api-plugin` with `axiosApi` class

What is `.contains()`?

Contains with `input[type="submit"]` Element

12+1 Misuses of `.contains()` – some might even call it abuse

1. Unnecessary Use of `.should('exist')` Assertion

5. Assuming `.contains()` Returns All Matching Elements

7. Relying on `.contains()` for Only Visible Elements

8. Relying on `cy.contains` Instead of Declarative Selectors

9. Using `.contains()` Against Non-Readable or Elements

10. Misuse of `.contains()` in Assertions for Non-Text Elements

11. Misunderstanding `.contains()` with Dynamic Content

12. Misuse of `.contains()` Accessing a Shadow DOM Element

12+1. Chaining Incorrectly Multiple `.contains()`

Diferences: `.contains()` vs `.should('contains.text')` vs `.should('have.text')`

New: `.findOne()` in Gleb Bahmutov's cypress-map Plugin