Forem: Sebastian Clavijo Suero

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!

Stand Out in the QA Crowd: Just Do You, but 'wick' Style!

Sebastian Clavijo Suero — Mon, 12 May 2025 04:15:30 +0000

(Cover image from pexels.com by Photos by ERRN)

ACT 1: Why am I writing this article?

Over the past year, I have been approached numerous times by people from various continents who aspire to become QA professionals. Many of them wanted to know what they could do to become great QA Engineers.

In essence, they were asking how they could Stand Out in the QA Crowd.

But how could I tell these individuals what they should do? Frankly, I wasn’t entirely sure, as I’m still carving out my own path in this competitive, ever-evolving, yet fascinating QA world. These are people who are placing their trust in you and your judgment to guide their professional careers. That’s a huge responsibility.

So, I shared with them the same principles I have strived to uphold throughout my personal and professional life. I believe these values are universally applicable and can genuinely help you shine in today’s highly competitive market, regardless of the profession or role you pursue. And that’s what this article is all about.

However, to effectively apply these principles, long time ago I realized I needed to embrace something that could be captured in one simple yet powerful phrase:

Just Do You!

This seemingly simple yet often challenging approach is what will give you the courage to uphold these principles and truly make you stand out in the crowd.

To do justice to this mindset, I will share with you, my friend, the raw, unfiltered, straightforward—and sometimes even blunt—version of my thoughts, to get it real!

So, if you’re not particularly open to hearing thoughts that might push you out of your comfort zone, this might be the perfect moment to pause and redirect your focus to something else. 🙂

ACT 2: Let’s Get Real—No Sugar Coating

Just Do You

OK, let me be completely honest to be fair...

Most of the time, this approach has served me tremendously well, helping me achieve great success, overcome significant challenges, and earn the respect of many peers.

However, there have been instances where it didn’t work as effectively as I had hoped. Sometimes it was because I didn’t implement it in the most effective way, and in many other cases, I genuinely believe no approach would have worked—whether due to external factors beyond my control or certain personalities where nothing could have made a difference.

So, why should I change to please others?

Exactly, just do you! But that doesn’t mean you have a free pass to do whatever you want or to shirk your responsibilities.

What it truly means is to gift the world the best version of you. Your core values must be strong and unwavering if you aim to succeed in anything.

We all know the expression "Fake it Until You Make It". It has unfortunately become very popular, especially among people navigating today’s market but lacking solid technical or interpersonal skills. Too often, it is used as an excuse to avoid putting in the extra effort required beforehand to truly fulfill the demands of any position.

But let me tell you what I think about that phrase, which is becoming a way of life for many... It's BS! Pure, unfiltered, and odorous BS! 😏

Sorry if I am too graphic, but yes, it is BS, no matter how many flies are trying to sell it to you, or even eat it themselves... Ewww! As we say in my home country, it is just pure 'caca de vaca' 🐄💩.

So instead of faking it, don’t wait for "some day" to make it, just do it! No tomorrow, not in one week... but NOW!

Yes, it might sound cliché —like a well-known sports brand slogan— but it is a mindset you must embrace and commit to fully. Believe me, pretending won’t take you far. People are sharp and perceptive, and most can spot a fake from miles away.

It might not be easy, I know. But I truly believe most people are capable of doing what they put their mind to. They just need to realize their own potential and learn how to overcome their fear to give it their all. If you want to succeed, you cannot hold back.

But still... YOU NEED TO BE YOU. If you’re quirky, don’t be afraid to embrace it. If your mind works differently or you approach problems in unconventional ways, that’s not a flaw, it is a strength. It makes you unique. Unique people achieve unique things, often in ways that others might label as unorthodox or even weird, but that’s perfectly OK. Just do (the better side of) you.

You don’t have to be quirky if that’s not who you are. But if you are, embrace it. What truly matters to most companies—especially those worth working for—isn’t necessarily how you do your work, but that you deliver results and ensure high quality. These companies do want to trust you, but you must prove yourself worthy of that trust. Often, they’re not overly concerned with originality or unconventional methods. However, those traits can work in your favor, helping you stand out and be remembered, turning your quirkiness into a valuable asset rather than a liability.

You’ll encounter companies or individuals who may not embrace your uniqueness, and that’s perfectly fine. Chances are, you don’t align with their rigid perspective either, and that’s OK too. Move on! As my mother often says: "You didn’t grow up there, and they didn’t shape who you are". So again, why change for them?

Actually, in some cases, your individuality might give you a head start in standing out from the crowd, but let’s be real—it won’t be enough on its own. You still need to deliver on your responsibilities.

And for that, there is one thing you absolutely have to embrace with every fiber of your being: You need to Truly Care!

Truly Care

The best professionals genuinely care about the work they do or the projects they contribute to, and they show it. They don’t fake it! They take full ownership, treating their work as more than just a way to fulfill a job description or earn a paycheck. They possess an innate drive to feel proud at the end of the day about what they have accomplished.

You don’t? Then maybe it’s time to reconsider your career path and seek a role where your lack of care will not impact the lives of so many around you.

QA is a role of immense responsibility. We are the guardians of user experience, ensuring our product's integrity and preserving our company’s reputation!

Let me tell you a story about something that happened to me many years ago.

It was early March in Sevilla, my beautiful hometown. Some of you might find it familiar… Perhaps because of Game of Thrones? 😉

I had just joined a new startup company in Spain less than a week earlier. Their offices were located in the garage of the founder’s house in Madrid.

At the same time, I was preparing for a big life change—I was about to get married that summer, though my fiancée was still in the US. Believe me, switching from a well established company to a brand-new startup operating out of a garage, especially when you’re about to get married, might seem like a bold move. But I knew it was the right choice for the future of my new family.

On my fifth day, while working from home until they set up an office in Sevilla, I got a call from the Founder-CEO-Director-PR-HR of my new company, let's call her M. Well, when a company operates out of a garage, one person often has to wear many hats! 😄

I still remember it like it was just yesterday. She said:

"Sebastian—told me, M—, I need you to come to Madrid for three months to work at the offices of a new client. Well… they’re not exactly our client, but I want them to be (it was one of the largest telecom companies in the country back then).

But… how can I put this... —surprised me, M— Everything’s a mess! We’re not working directly for the client but for a consulting company they hired. This company already has three so-called expert consultants on-site, but they have no idea how to solve the client’s problem. So, they’re subcontracting us to get the job done. And by 'us,' I mean you.

But I should also tell you that on-site—continued, M—, there are a couple of official consultants for the product the client is using. However, they’ll only be there for one more week, so you’ll have, at most, three days to overlap with them.

They told me they’re leaving because everything is in shambles—warned me, M—. The code has been meddled with by too many hands, none skilled enough to preserve its integrity. On top of that, they believe there are too many external companies involved, each with conflicting interests."

Honestly, they weren’t wrong. Counting my company, there were now four external companies, plus the client’s own resources, working on this project. 🤦‍♂️

Can you guess what words crossed my mind?

Exactly! "This is pure 'caca de vaca'" 🐄💩

I could smell it, even from 533 kilometers away, all the way from Sevilla to Madrid! Sorry for being too graphic again! 😁

I’m not going to lie to you... she had me scared. All of a sudden, I wasn’t so sure anymore if joining this startup was the best decision for me and the new family I was about to build. Man, I was really in a pickle!

Three days later, there I was (Sebastian) on the AVE (the high-speed train originally built for the Universal Expo '92) racing toward the Wild Wild Madrid to face... I really had no idea what I was about to face. The only thing I knew for certain was that I had been hired to do a job in a multimillion-dollar project, and both my company and the client were counting on me. Uff, no joke!

After being met with a certain dose of cynicism by the consultants from the company we were contracted by (who, by the way, had already been there for over six months), I was finally introduced to the client. I could feel their apprehension and the frustration of a project that had been stagnating for nine months. Even more unsettling was their certainty that nobody who had shown up so far was capable of getting things done. They genuinely didn’t know who they could trust anymore.

What could I possibly say to this person that he hadn’t already heard from the countless others who had come across the project?

I sympathized with them. How could I show them that I genuinely wanted to help, that I truly did care about them?

So, I simply told them what I could honestly do given the circumstances: "OK, let me take a look at what’s there, and we’ll talk again in a week."

The Method to Support the Principles

I give you a hint: Follow the the Bold Brick Road! 😄

In situations like that, there are basically two things you can do:
You can try to keep a low profile, letting the days and weeks slip by while giving the impression that you’re busy and productive;
Or, you can slap your palm on the table (when no one’s looking) and declare loud and clear: 'Here I am, baby, ready to shake things up!'

That’s the attitude that will make you stand out in the crowd. Sure, taking risks can be scary, and it’s always tempting to stay in your comfort zone—and that’s perfectly fine if that’s what you choose. But hear me out: staying comfortable is not what will make you stand out. No pain, no glory.

To grow professionally, you need to step up and do grown-up things. Tasks that kids can’t handle or are not willing to take on.

I strongly recommend setting a deadline to come up with a plan, a realistic deadline, but not too far in the future. In my case, I committed to returning in a week with a clear course of action.

Also, assess your environment. What kind of ground are you stepping on? Is it solid, or is it unstable and squishy? Can you breathe the air safely, or do you need to control your breath because it’s too unpleasant? Do you remember the vaquita? 😅

After the initial warnings I received and just one day in the field, it became glaringly clear: the terrain was sticky, and the air felt suffocating to breathe. The consulting company that had hired us to assist with the system design and implementation (though, truthfully, to do their job) was clearly at odds with a competitor who was also on-site, managing the data collection and entry for the client. They suspected that the ultimate, unspoken goal of the competitor was to outmaneuver them—the very company that brought us in—and claim the entire enchilada for themselves.

The third external company, the official consultants for the product, was simply there to bill hours, and counting down the hours until they could get out of there!

Meanwhile, the client had their own internal team, a mix of developers and data quality control staff who were brought on just nine months ago, supposedly brimming with expertise in the field.

And then there was my company. In other words, me.

After that, I did the only thing I could do if I truly wanted to solve the conundrum I was caught in:

'Echarle dos cojones' (as figuratively we say in my home country), and...

Dig, and ask. Dig again, and ask again. Keep digging, and keep asking relentlessly, even if you’re asking uncomfortable questions!

It's fascinating what you can uncover once you start 'excavating', especially in a place where countless people before you have been digging and then carefully covering their tracks. It is indeed like working on the infamous Money Pit on Oak Island! Back then, The Course of Oak Island TV show didn’t even exist yet, but man, it’s the first image that popped into my mind as I was writing this—so, of course, I had to include it. I just couldn’t resist (right, Todd?)! 😆

The reality was that, even though I wasn’t getting straight answers to any of my questions, the information I gathered from the different stakeholders across these various companies gave me plenty of leads. They were all disconnected, but each one seemed worth exploring.

I haven’t mentioned it yet, nor do I intend to go into detail about the nature of the work or the type of system I had to get running. After all, it’s just like the MacGuffin in a Hitchcock movie—the backdrop to the story I’m sharing with you. What I will share is that it involved a distributed system operating across the county, where all database replicas needed to stay synchronized, ensuring no precious data was lost. And I think that’s plenty of detail for you to know. 😄

The interesting thing was that, after a week, the apprehension I might have felt initially was gradually fading away, inversely proportional to my growing knowledge of the system.

Well… it makes sense, doesn’t it? Duh!

But only once you have truly immersed yourself in the mess, instead of taking the easy road and keeping a low profile and letting the days and weeks quietly slip by.

After a week in their offices, I approached the client as promised (the head of the department, who was a not insignificant big shot in that telecom) and presented my blueprint outlining how I thought we could fix the broken pipes with minimal monetary expense. We just needed to tighten a few screws and replace a couple of leaking tubes. However, it was essential to bring together what remained of the 'team' (remember, the official product consultants were already gone).

So, the next step in the plan was to build consensus toward a common objective. And for that, nothing works better than recognizing what each person was doing well and then, with carefully nuanced guidance (so they still believed it was their own idea), asking them how they could improve their part in the process.

I know, this might seem like a little bit of manipulation, but as they say, all’s fair in love and war. Just kidding! 😉

Truth be told, when you candidly talk to people and genuinely listen to what they have to say, you realize that they aren’t the mischievous personalities you initially thought—or were led to believe—they were.

They need to see that you genuinely care. Once they do, they might surprise you by showing they care as well. It is the same apprehension you felt when stepping into unfamiliar territory that made them defensive. It’s not about assigning blame for someone else’s stagnation, but rather fostering understanding and cultivating a shared sense of growth, all directed toward a common goal.

And now comes the hard part, getting things done! You can't expect or ask others to do something you are not willing to do yourself. You've likely heard the well-worn phrase: "Lead by example!" Beautiful sentiment, right? Very motivational! We drop it into conversations every chance we get...

Cut the BS (AKA 'caca de vaca 🐄💩)! It's not enough to simply say "lead by example" or to just make it seem like you're doing it. You have to genuinely mean it, and do it for real! That’s how you learn, how you inspire others to follow you, and how you truly stand out from the crowd, whether it’s a QA crowd, a Dev crowd, or any other kind of crowd.

ACT 3: Sebastian, You Are Amazing! Truly Inspirational! 🤣

Thank you, I really appreciate your sentiment! 😍

But believe me, I wouldn’t say so lightly. Like any declaration of intentions and goodwill, we are still human, and sometimes our actions simply can’t keep up with our intentions.

But that’s OK, nobody is really expecting you to operate at 110% all the time. That level of effort is unsustainable. The true key lies in giving it your all when it truly matters. And that’s something not everyone is willing to do. That is what will set you apart and put that extra mile between you and the rest of the crowd.

To wrap up the story, the funny part of all this—which still makes me smile to this day—is that, after barely three weeks of working there, a stakeholder approached looking for some crucial information. To my surprise, the client's senior programmer-analyst genuinely told them: "You need to talk to Sebastian. He’s the expert and knows our system better than anyone". 😆

By the way, within the next six months, the client replaced all the external companies and entrusted my company to take charge of the entire operation—and cook the whole enchilada. 🌮 (Yes, this is a taco, but sadly, there’s no emoji for an enchilada!)

I know... this ended up being a long story, maybe a little too quirky, maybe even a bit too graphic for your taste. But that’s just me, the real me: I like to share, some times too much, because I truly care; I might be a little unorthodox, because I just do me; And yes, I might be a little too graphic because, as we say in my home country, 'Me gustan las cosas claras, y el chocolate espeso!' (I like things to be clear, and my chocolate thick!)

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 Async Nature of Cypress: Don't Mess with the Timelines in Your Cypress Tests 'Dual-Verse'

Sebastian Clavijo Suero — Wed, 30 Apr 2025 05:46:32 +0000

ACT 1: EXPOSITION
ACT 2: CONFRONTATION
- The Asynchronous Nature of Cypress
- The Two Timelines in Cypress Tests (AKA 'Dual-Verse')
  - Example Test 1
  - Example Test 2
  - Example Test 3
  - Example Test 4
  - Example Test 5
  - Example Test 6
  - And What About Cypress Hooks?
ACT3: RESOLUTION

ACT 1: EXPOSITION

A lot has been said about the asynchronous nature of the Cypress test framework. This asynchrony is often blamed as the primary cause of flakiness in Cypress tests. And, I would say… yeah, I agree. Asynchrony is the main reason of flakiness, but that’s because it’s not used correctly, which stems from it not being properly understood.

Why is that? I can’t pinpoint the exact reason, but this is my suspicious, and I’m really not trying to be judgmental:

The proper documentation on Cypress’s async behavior is often skipped or not fully read before people jump into creating more complex tests.
It’s very common for people to mix synchronous JavaScript code with asynchronous Cypress commands and queries in their tests, and treat them the same way.
And, well… asynchronous behavior doesn’t come naturally to our brains. We think synchronously by default, and grasping asynchronous concepts requires extensive hands-on usage, often coupled with making a lot (and I mean a lot) of mistakes.

The goal of this blog is not to lecture you on general theories of asynchrony and race conditions, but to offer a clearer yet detailed explanation of how asynchrony works specifically in Cypress when running tests in a browser.

I decided to tackle the subject with a different approach than how it is usually discussed and explained. This approach will be more visually oriented, as the human brain processes images and diagrams more effectively than large amounts of text, especially when dealing with complex concepts.

To lay it all out, I’ve coined a term: “The Two Timelines in Your Cypress Tests” or, to add a little fun, “The Cypress Dual-Verse”! 😄

ACT 2: CONFRONTATION

The Asynchronous Nature of Cypress

But before we explore the details (and the fun graphical part) of how the two timelines behave and coexist when running your Cypress tests, I want to take a moment to touch on and discuss some core aspects of how Cypress works in this context. If you’re looking for more specifics, I highly recommend reading the official Cypress.io documentation on Understanding the Asynchronous nature of Cypress.

Here are a few essential points to note:

Cypress commands operate asynchronously and are executed later in a queued sequence (grasping this is essential!).
Cypress commands do not return their subjects directly; instead, they yield their subjects. As a result, you cannot assign their output to a variable.

Cypress commands do not return JavaScript Promises; rather, they return what are commonly referred to as Chainables. Although the behavior of Chainables is somewhat similar to Promises, you cannot use async/await in your Cypress tests.
Cypress commands are inherently asynchronous and yield chainable objects, which enables the next command in the chain to execute after the previous one completes.

Example of chained commands in Cypress:
```
// Visit the '/home' web page
cy.visit('/home');

// Wait until the <button> element is present in the DOM,
// verify it contains the text "Click me!", and then click it
cy.get('button')
  .should('contain', 'Click me!')
  .click();
```
In this example, the <button> element retrieved by the .get() command is yielded to the .should() command, which makes an assertion over it, and in turn is yielded to the .click() command.

There are two Cypress commands that help streamline the handling of asynchronous behavior:

wrap(): Used to wrap a JavaScript object or value so that it can be used within Cypress's chainable command structure. This is particularly useful when you want to work with non-Cypress objects, such as data variables or elements returned by a JavaScript function, within a Cypress test.
```
const myObject = { name: 'Test Object' };

// Wrap the object to use it in Cypress's command chain
cy.wrap(myObject)
  .its('name')
  .should('equal', 'Test Object');
```

then(): Used to execute a callback function once the previous Cypress command is resolved. It allows you to work directly with the resolved value of an asynchronous Cypress chainable command. This is especially useful for performing custom actions or additional assertions that cannot be directly achieved through Cypress commands.
```
cy.get('button').then(($button) => {
  // $button is the resolved jQuery element from cy.get('button')

  console.log($button.text()); // Log the button's text
  $button.click(); // Perform a click directly with raw jQuery commands
});
```
If you're accustomed to working with native Promises, the Cypress .then() behaves in a similar way. However, they are not promises; instead, they are sequential commands added to a central Cypress queue, where they are executed asynchronously at a later time.

You can nest additional Cypress commands within the .then() block. Each nested command can utilize the results or actions performed by the preceding commands. Commands outside of the .then() block will not execute until all the nested commands inside have completed. This is crucial for gaining a proper understanding of how the Cypress queue works.

📑 Note: In Cypress, you cannot implement a catch(error) handler for a failed command since Cypress does not provide built-in error recovery for failed commands. If a command fails, it halts the execution of all subsequent commands, leading to the failure of the entire test.

The Two Timelines in Cypress Tests (AKA 'Dual-Verse')

We have finally reached the fun part! 😄
What do I mean by "The Two Timelines"?

Here’s the answer:

The first is the JavaScript timeline, executed by the browser, which runs the JavaScript code synchronously, one statement after another.
The second time line is the Cypress queue, which follows its own pace, operating "in parallel" with the JavaScript timeline.

🚨🚨 Spoiler alert: the JavaScript timeline does not wait for the Cypress queue until both timelines reach the end of the block in which they are defined (this could be an it() test, a .then() block, a before()/beforeEach()/after()/afterEach() hook, or any other block definition supported in Cypress).

The official recommendation from Cypress is not to mix async code with sync code (see here). However, in reality, there will be cases and situations where you encounter this practice—whether you’re debugging flaky tests implemented by someone else or addressing logical problems that cannot be resolved with only Cypress commands.

This is why it is crucial for you to understand how Cypress's async behavior works and how these two timelines operate and interact with each other.

And we are going to learn this through a series of six examples and some "pretty" timeline graphs.

⚠️ DISCLAIMER: The examples we will explore are not meant to showcase the recommended best practices for these cases but are instead tailored to help me clearly illustrate how these timelines work.

Example Test 1

Here is the test:

// Cypress Commands and JS Sync Code
it('Test 1', () => {
    cy.request('https://jsonplaceholder.typicode.com/posts/1')
        .then((response) => {
            let id = response.body.userId  // userId value is 1
            cy.wrap(id).should('equal', 1)  // Pass! (because id == 1)
            id = id + 1  // id set to 2
            expect(id).to.equal(2)  // Pass! (because id == 2)
        })
});

In the first example, we will perform a network request and then process the response body by extracting the userId field (which contains the value 1). Next, we will assert the obtained value, modify it, and then assert again.

However, note that we have mixed Cypress should assertions with Chai expect assertions while also storing the extracted values in a local variable within the scope of the block.

But in what order do the browser execute these JavaScript statements (which are sync) along with the Cypress commands (that are async)?

When running a test, Cypress adds all the commands it finds to its queue in the same order they are encountered. However, the QA Engineer does not truly know or cannot assume when a command will be taken by the Cypress runner from the queue and executed.

And that is because JavaScript statements are executed lightning-fast by the browser and don’t wait around for the Cypress commands. It is like they are each living in their own parallel universe with separate timelines. 😄

The only certainty is that nested JavaScript statements and Cypress commands within another Cypress command block, are executed before any remaining Cypress command outside that block.

The two timelines come together either at the conclusion of a test or when a Cypress block finishes (like a .then() block).

If we carefully analyze the order in which each statement and command is executed for the Test 1, it will look like a temporal flow diagram like this:

Interesting right? 🤔

Notice in the temporal diagram, that the JavaScript statements are executed as soon as the .then() block begins and do not wait for the Cypress commands, even if those commands are defined earlier in the test code. The time?? (time with question marks )in the graph represents the uncertainty around how much time will elapse between when a command is queued by Cypress and when it is actually executed. However, it is almost guaranteed that the JavaScript statements will run before the Cypress commands are executed within the block.

Also, keep in mind that the value of the JavaScript variable id, which is used in .wrap(), is taken from its actual value at the moment .wrap() is encountered during the test execution. The wrap command is then queued with that specific value (in this case, 1).

And what happens in the Cypress Log in the test runner when we execute this test?

The Cypress Log clearly shows that the expect() Chai assertion (which is JavaScript code) runs before the .wrap() and .should() Cypress commands. And the test pass!

Yeah, I wasn’t lying before—pure JavaScript code runs much faster than Cypress commands. It’s like they exist in a Dual-Verse, with time running much faster in one than the other, and they only converge in the future when the Cypress test or block ends!

Example Test 2

What if we create a second test similar to the first one, performing the same assertions, but using only Cypress commands?

// Only Cypress Commands
it('Test 2', () => {
    cy.request('https://jsonplaceholder.typicode.com/posts/1')
        .its('body.userId')
        .should('eq', 1) // Pass! (because userId == 1)
        .then((id) => id + 1) // Increment id and yield value to next command
        .should('eq', 2); // Pass! (because id == 2)
});

And this is what the temporal execution diagram will look like in this case:

Hmmm, it's quite different from Test 1, even though it performs the same type of assertions. However, this time, it only uses Cypress commands instead of mixing with Chai assertions.

This difference is also noticeable when we look at the test results in the Cypress Log:

This time, the assertions were executed in order (first asserting 1, and then asserting 2), because Cypress executes commands in the same order they are added to the command queue. And the test also pass!

Example Test 3

Is the third test... a charm?

// Cypress Commands (with 2 .then()) and JS Sync Code
it('Test 3 ', () => {
    let id = null;  // id set to null

    cy.request('https://jsonplaceholder.typicode.com/posts/1')
      .then((response) => {
            id = response.body.userId  // userId value is 1
    }).then(() => {
        cy.wrap(id).should('equal', 1)  // Pass! (because id == 1)
        id = id + 1  // id set to 2
        expect(id).to.equal(2)  // Pass! (because id == 2)
    })
});

This third test is a bit more complex. We are defining a local variable id at the beginning of the test, which is accessible anywhere within the test, and also mixing JavaScript statements with Cypress commands.

The temporal diagram will look like:

Notice that the variable id is initialized at the very beginning of the test to null and then modified twice within both .then() blocks. Similar to Test 1, the expect Chai assertion (that is Javascript sync code) is executed before the .should() Cypress assertion (that is async). However, the test still pass.

This is confirmed by the Cypress log when we run it in the Cypress runner:

Example Test 4

Let’s spice things up a bit! What would happen if we threw an expect Chai assertion at the very end of the test, outside both .then() blocks?

// Cypress Commands (with 2 .then()), JS Sync Code and expect() outside the last .then()
it('Test 4', () => {
    let id = null;  // id set to null

    cy.request('https://jsonplaceholder.typicode.com/posts/1')
      .then((response) => {
            id = response.body.userId  // userId value is 1
    }).then(() => {
        cy.wrap(id).should('equal', 1)  // Pass! (because id == 1)
        id = id + 1  // id set to 2
        expect(id).to.equal(2)  // Pass! (because id == 2)
    })

    expect(id).to.equal(2) // Fail!!! (because id == null)
});

And who wins the Amazing Race?

The test fail!!!

Indeed, even though the expect is placed at the end of the code, it is executed immediately after we initialize the variable id to null, long before it is updated within the Cypress commands, so the Cypress commands are not even executed at all!

This is confirmed by the Cypress log when the test is executed:

Example Test 5

Let me think...

What if, instead of putting an expect at the end of the test, I use Cypress commands to perform the assertion (using .wrap() and .should())?

// Cypress Commands (with 2 .then()), JS Sync Code and should() outside the last .then()
it('Test 5', () => {
    let id = null;  // id set to null

    cy.request('https://jsonplaceholder.typicode.com/posts/1')
      .then((response) => {
            id = response.body.userId  // userId value is 1
    }).then(() => {
        cy.wrap(id).should('equal', 1)  // Pass! (because id == 1)
        id = id + 1  // id set to 2
        expect(id).to.equal(2)  // Pass! (because id == 2)
    })

    cy.wrap(id).should('equal', 2) // Will Fail!!! (because id == null)
});

Well... since Cypress commands are added to the queue in the order they are defined in the test, that final assertion should be executed at the end of the test, right?

Let's see the diagram:

And that is exactly what happens! The Cypress assertion at the very end of the test is executed last, BUT when the command .wrap() is added to the Cypress queue, the variable id still holds the value null.

Remember? JavaScript statements are executed before Cypress commands, so the JavaScript timeline reaches the end of the test (with the id variable still set to null) before any of the earlier Cypress commands are executed. So the test fails!

And here’s the proof (the Cypress Log never lies!):"

Pesky variable! 😜

Example Test 6

And finally, the last test example.

Why don’t we enclose the final Cypress assertion within a cy.then() command?

In this case, the .then() command is not chained to the yielded value of another Cypress command, but is applied directly to the global object cy (from the Cypress test framework).

it('Test 6', () => {
    let id = null;  // id set to null

    cy.request('https://jsonplaceholder.typicode.com/posts/1')
      .then((response) => {
            id = response.body.userId  // userId value is 1
    }).then(() => {
        cy.wrap(id).should('equal', 1)  // Pass! (because id == 1)
        id = id + 1  // id set to 2
        expect(id).to.equal(2)  // Pass! (because id == 2)
    })

    cy.then(() => {
        expect(id).to.equal(2) // Pass! (because id == 2)
        cy.wrap(id).should('equal', 2) //Pass! (because id == 2)
    })
});

This approach will encapsulate those assertions within a Cypress block, allowing time for the id variable to be set by the previous commands. Such a technique is a common and recommended practice in Cypress when you want to 'sync' commands with one another.

We also added, as a bonus, an expect in that final cy.then() block, and as expected, it is executed before the final Cypress assertion.

Again Javascript synchronous timeline is faster!

And What About Cypress Hooks?

Actually, Cypress hooks are also blocks that wrap JavaScript and Cypress commands, so the same rules apply to them.

ACT3: RESOLUTION

So we’ve reached the end of the exercise!

Now you understand how Cypress's asynchronous nature really works—don’t be afraid of it. When used wisely, it can be a truly powerful tool. And also, the chained commands are quite elegant.

Once again, the official Cypress recommendation is to avoid mixing JavaScript synchronous code with Cypress asynchronous commands. However, you now have the knowledge and tools to handle the The Two Timelines in your Cypress tests—for instance, when debugging a faulty or flaky test written by someone you’ve never met who knows how long ago! 😄

One tool that might help you debug flaky tests caused by incorrect usage of Cypress's asynchronous nature is the cypress-command-chain plugin, developed by Gleb Bahmutov.

It is very easy to install and use. The plugin displays the Cypress queued commands in the Cypress log in the exact order they are inserted, along with the values of the arguments at that moment.

If we run Example Test 5 (from our earlier discussion) with the cypress-command-chain plugin enabled, this is what you would see in your Cypress log:

At the top of the log, the Cypress Command Queue is displayed, showing each command inserted in order along with its arguments. Below that is the regular Cypress log, which includes the results of the assertions as they are executed.

You can find all the examples from this article in the GitHub repo: sclavijosuero/cypress-async-behavior-examples.

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!

Forem: Sebastian Clavijo Suero

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

Presenting cypress-flaky-test-audit!

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

🧠 Per-command execution details

⏱ Timing and latency observations

🔁 Retry tracking

🚦 Clear pass/fail status per command

🔍 Comparing retries within the same test run

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

🖥 Browser console output

🧾 Terminal output (CI-friendly)

📊 HTML test audit report (where everything clicks)

Who this is for (and who it is not)

ACT3: RESOLUTION

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

ACT 1: EXPOSITION

ACT 2: CONFRONTATION

Support of WCAG 2.2 AAA

Mega Revamp of the HTML Report

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

✔️ What About the existing `.validateSchema()` Command In My Code?