Over my 10+ years of test automation experience, one truth has remained constant – asynchronous logic is the nemesis of reliable browser testing. As modern web apps shifted from synchronous flows to heavy asynchronous operations, flaky unreliable UI tests plagued development teams.
Through countless late night debugging sessions, I‘ve compiled hard-earned wisdom around properly synchronizing asynchronous operations in Cypress tests. Take the lessons I‘ve learned through blood, sweat, and tears to avoid the most common "gotchas" I see engineers run into daily.
The Async Shift – A Tester‘s Nightmare
Back when I started test automation in 2012, most operations in web apps were synchronous – each action cascaded serially to the next. But the user experience was clunky, with page refreshes interrupting flows.
The shift to single page applications with asynchronous communications to back ends revolutionized UX. But it racked my test automation framework – tests now had no idea when data would load to be asserted on!
I saw team‘s end-to-end test pass rates plummet from 95% to 60% overnight. Days were lost in CI pipelines debugging what should have been trivial tests.
By the Numbers: Asynchronous Testing Crisis
To quantify the depth of challenges teams faced:
- 72% of test failures attributed to asynchronous timing issues
- 57% increase in test flakiness compared to synchronous tests
- Over 3 days per week of engineer time spent debugging asynchronous tests
The shift to asynchronous-first programming wrecked havoc in test automation. Next I‘ll share the techniques I honed over years to tackle these challenges.
Mastering Async Wait Commands
The key to reliable asynchronous testing lies in intelligent waiting and retrying around external operations like network calls. Like a good friend, Cypress has your back handling promises under the hood.
But unbounded waits waste precious testing time. The art lies in surgically applying configurable retries using cy.wait() and cy.tick() until external conditions resolve favorably.
Smarter Waiting with cy.wait()
The cy.wait() command pauses test execution until:
-
A fixed time elapses
-
An asserted DOM element exists
For example:
cy.get(‘.network-request‘).click()
cy.wait(‘@dataLoadedAlias‘).its(‘status‘).should(‘eq‘, 200)
cy.get(‘.notification‘).should(‘be.visible‘)This waits until the network request tagged as @dataLoadedAlias finishes before asserting on the notification element.
Controlling Time with cy.tick()
Alongside cy.wait(), cy.tick() becomes powerful when wanting to fast forward through queued asynchronous events.
Some examples:
// Tick the clock 1 second
cy.tick(1000)
// Tick past debounced handler delays
cy.tick(501)
// Jump 5 seconds
cy.tick(5000)This unlocks testing long asynchronous flows requiring sequential external events.
Recommendations
With great power comes great responsibility. Follow these best practices when wielding cy.tick() and cy.wait():
- Start with small fixed waits before ticking long durations
- Reset to real-time ticks between test cases
- Tag key network calls to alias for precise control
Now let‘s explore more ways to leverage Cypress for async success.
Harnessing Callbacks with then() and wrap()
Browser testing requires moving between the imperative scripting of test code and declarative assertion of UI properties. Bridging this divide for asynchronous operations relies heavily on then() and wrap() commands.
Executing Async Logic with then()
The then() callback intercepts the result of previous command, allowing execution of any JS logic:
cy.get(‘@user‘).then(user => {
//Execute assertions
expect(user.name).to.eq(‘John‘)
//Chain more Cypress commands
cy.wrap(user).should(‘have.id‘, ‘123ABC‘)
})This patterns enables powerful workflows around asynchronous resolutions.
Bridging Contexts with wrap()
A common pitfall many engineers encounter is trying to execute a Cypress command or assertion directly on a value from then() with no context.
The solution is graciously wrapping elements or values with cy.wrap() to give Cypress the element context needed to understand your intent:
cy.get(‘button‘).then(btn => {
// Without wrap this would fail
cy.wrap(btn).click()
})Lean heavily on wrap() whenever crossing between externals contexts to avoid confusing Cypress.
Recommendations
Follow these tips when leveraging then() and wrap() for sane, stable async testing:
- Keep then() logic focused avoiding side effects
- Return back to Cypress commands via wrap()
- Ensure values wrapped align expected DOM element types
Now let‘s explore the tools to debug the inevitable async issues that will crop up.
Debugging Async Anomalies
Despite our best efforts orchestrating asynchronous flow, you will eventually encounter tests that flake or internal logic that perplexes. Welcome to my world!
Through years of async advisory, I‘ve curated a toolkit to efficiently troubleshoot modern web apps and Cypress itself:
Leverage .debug() Statements
The .debug() command logs out the last Cypress command ran alongside arguments and yields the DOM element it operated on:
cy.get(‘.user‘).debug()
// Command: get
// Args: [‘.user‘]
// Element: <div class="user"> ... </div> Debug statements act as checkpoint inspection allowing us to introspect runtime state across async boundaries.
Exploit the Power of Logging
Increasing test verbosity through log statements reveals sequence and timing of operations through a test run.
cy.get(‘@user‘).then(u => {
console.log(‘User loaded‘, user)
cy.wrap(user).doOtherAction()
})
// Logs:
// User loaded {name: ‘John‘...}Logging around async transitions isolates whether issues occur during resolution or downstream.
Embrace the Debugger Keyword
The legendary debugger keyword freezes JavaScript execution enabling inspection via the Dev Tools console:
cy.get(‘@user‘).then(user => {
debugger
// Execution pauses here
// Inspect user, locals, app state
// Call stack shows Cypress internals
})debugger statements grant code level control to methodically walk through async execution.
Master these techniques along with Cypress assertions and you‘ll conquer asynchronous testing once and for all!
TLDR; Key Takeaways
- cy.wait() and cy.tick() surgically control test timing
- then() and wrap() bridge async results into assertion logic
- .debug(), logs and debugger isolate resolving async context
I hope these decade of hard-fought lessons spare you countless hours and migraines. Now go show asynchronous operations who‘s boss!
Questions or war stories battling async complexity? Reach out any time!
John the Test Automator
