The Async Nature of Cypress: Don't Mess with the Timelines in Your Cypress Tests 'Dual-Verse'

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”!

Apr 30, 2025 - 06:59

The Async Nature of Cypress: Don't Mess with the Timelines in Your Cypress Tests 'Dual-Verse'

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”!