Introduction
Cypress Assertions are the most important part and also most effective test automation in Cypress. When implementation is done properly, they improve test reliability, improve test execution speed, and provide clear validation of as expected behavior. In contrast, due to their wrong expression, these kinds of assertions are a significant factor that causes one’s test will not run properly and to do software debugging becomes very hard. Poor automation is only the result.
In this cypress testing guide, we will give you point-by points, typical pitfalls and even several examples, so that the end result is a Cypress test that is trustworthy, maintainable and can grow with your application.
Best practices for using Cypress assertions
1. Prefer .should() Over .then() for DOM State Checks
Cypress’s .should() command is automatically retried until it passes or times out. This makes it ideal for asserting DOM state changes, particularly in asynchronous applications.
Avoid:
cy.get('.status').then(($el) => {
expect($el.text()).to.eq('Complete');
});
Better:
cy.get('.status').should('contain', 'Complete');
Why? .then() executes once when the element is found, while.should() retries until the condition passes. Using .should() reduces flakiness and eliminates the need for manual waiting.
2. Be specific in your assertions
Vague assertions like .should(‘exist’) offer little value when debugging. They confirm presence but say nothing about content, attributes, or visibility. Instead, be precise.
Instead of this:
cy.get('.submit-button').should('exist');
Do this:
cy.get('.submit-button')
.should('be.visible')
.and('contain.text', 'Submit Order')
.and('have.attr', 'disabled', 'disabled');
3. Chain assertions for clarity and efficiency
Cypress lets you group.should() and.and() together to help retain cleanliness in the most lucid testing code.
cy.get('.item')
.should('be.visible')
.and('contain', '42')
.and('have.class', 'highlighted');
Extensions are tied to a single subject, and that helps enforce good practice and readability of code. It also lets us take full advantage of Cyclone’s control message system.
4. Limit each test to one logical assertion
Lots of assertions in a single test case or script make it harder to trace the failures. So split complex verifications into separate test cases to isolate behavior.
Instead of this:
it('checks form behavior', () => {
cy.get('username').should('exist');
cy.get('password').should('exist');
cy.get('login-button').should('be.enabled');
});
Do this:
it('should show username field', () => {
cy.get('username').should('exist');
});
it('should show password field', () => {
cy.get('password').should('exist');
});
it('should enable login button', () => {
cy.get('login-button').should('be.enabled');
});
This modular approach reduces test complexity and improves test granularity.
5. Replace cy.wait() with assertion retries
Using cy.wait() with static values introduces test instability and slows down your suite. Instead of using it, use Cypress’s auto-retry.
Bad:
cy.wait(2000);
cy.get('.spinner').should('not.exist');
Good:
cy.get('.spinner').should('not.exist');
The above code allows Cypress to retry he condition until it times out, resulting in faster and more stable in-text execution.
6. Use .its() and .invoke() for non-DOM assertions
To check JavaScript object properties or invoke methods, use .its() and .invoke() effectively.
cy.window().its('navigator.language').should('eq', 'en-US');
cy.get('price').invoke('text').then(parseFloat).should('be.gt', 0);
The above code is used for accessing local Storage, browser APIs, cookies or dynamically rendered content.
7. Use custom assertions and commands
By putting common checks into reusable Cypress commands, you can avoid doing the same logic twice.
Cypress.Commands.add('shouldBeLoggedIn', () => {
cy.get('.profile-name').should('exist');
});
cy.shouldBeLoggedIn();
Custom commands enhance code reusability, improve readability, and reduce maintenance.
❌Common Cypress testing mistakes
Now, even an experienced person sometimes misuses Cypress assertions. Let’s look at the most common errors and how to avoid them.
1. Forgetting to assert after actions
Interacting with UI without validating the result makes your test pointless. Always follow actions with assertions
Mistake:
cy.get('button').click();
// no follow-up check
Fix:
cy.get('button').click();
cy.get('.confirmation').should('contain', 'Order placed');
2. Misusing .then() for Assertions
.then() is not retried. Avoid putting assertions inside it unless necessary.
Wrong:
cy.get('.count').then(($el) => {
expect($el.text()).to.eq('5');
});
Right:
cy.get('.count').should('have.text', '5');
Use .then() method only for converting values, not any asserting conditions.
3. Ignoring text whitespace issues
Assertions like .should(‘have.text’, …) fail with invisible whitespace. Consider using .should(‘contain’, …) or trimming values.
cy.get('.message')
.invoke('text')
.then((text) => expect(text.trim()).to.eq('Welcome'));
4. Overusing static waits
Reliance on fixed waits (cy.wait(5000)) results in slow, unreliable tests. Always prefer condition-based waits via .should().
5. Only writing positive assertions
Cover negative flows and edge cases, too.
Example:
cy.get('.logout-button').should('not.exist');Neglecting this results in incomplete coverage.
6. Not validating accessibility
Now here we are using assertions to verify accessibility attributes:
cy.get('button').should('have.attr', 'aria-label', 'Submit');
This is the best, or we can say great, way to catch or identify missing or misused attributes early in development.
🔁 With the below points we can write Reliable Cypress test with assertions
A. Structure tests with clear blocks
A good test structure improves readability and maintenance.
describe('Login form', () => {
beforeEach(() => {
cy.visit('/login');
});
it('should show error for invalid email', () => {
cy.get('input[type=email]').type('wrong@');
cy.get('button[type=submit]').click();
cy.get('.error')
.should('be.visible')
.and('contain', 'Invalid email');
});
});
B. Reuse custom commands for assertions
Avoid or ignore writing the same checks in every test.
Cypress.Commands.add('login', (email, password) => {
cy.get('email').type(email);
cy.get('password').type(password);
cy.get('button[type=submit]').click();
});
Cypress.Commands.add('assertLoginSuccess', () => {
cy.url().should('include', '/dashboard');
cy.get('.welcome').should('contain', 'Welcome');
});
C. Use .should(callback) for Complex Logic
Sometimes assertions need to be dynamic.
cy.get('.total').should(($el) => {
const val = parseFloat($el.text());
expect(val, 'Total price').to.be.greaterThan(0);
});
D. Combine UI and API assertions
By Cypress we can verify front-end changes with back-end responses and ensure end-to-end reliability.
cy.get('button.confirm').click();
cy.get('.toast').should('contain', 'Order submitted');
cy.request('/api/orders')
.its('body')
.should('have.length.at.least', 1);
✅Do’s and ❌ don’ts of Cypress assertions
| ✅Do’s | ❌ Don’t |
| Use .should() for automatic retries | Rely on cy.wait() unnecessarily |
| Assert specific values and attributes | Write vague checks like .should(‘exist’) |
| Create reusable custom commands | Copy-paste the same assertions |
| Assert both positive and negative flows | Only test “happy paths” |
| Chain multiple assertions fluently | Overload one test with too many checks |
Debugging assertion failures
1. Use cy.log() to print values within .should() or .then() blocks.
2. Leverage the Cypress Test automation Runner UI to hover over DOM snapshots on failure.
3. Filter out noise using Cypress.config(‘hideXHR’, true).
4. Use.only and.skip to isolate failing tests for faster debugging.
Final thoughts on Cypress assertions
Cypress assertions are not used only for verifying outcomes—we can build fast, it’s maintainable, and trustworthy test suites. Below are the points that we can follow for best practices:
- Prevent flaky tests
- Make debugging easier
- Ensure higher confidence in deployments
Review your assertions first whenever your test suite becomes erratic or sluggish. You can ship with confidence and steer clear of regressions if you have a strong assertion strategy.
