What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Give a Chai expect assertion a short message as its second argument, inside a Cypress .should() callback. The label adds context to the assertion in Cypress’s Command Log; it does not replace the expected condition or change Cypress’s retry behavior.
Write an assertion label that explains the expected behavior
Use the label to identify what the assertion is checking and when that result should occur. For example:
As an Amazon Associate I earn from qualifying purchases.
cy.get('[data-testid="todos"]').should(($todos) => {
expect($todos, 'todo list after adding one item').to.have.length(3)
expect($todos, 'new todo is visible in the list').to.contain('Write tests')
})Cypress documents passing a string as the second argument to expect; it says the string appears in the Command Log to give the assertion more context. See the Cypress .should() API documentation. Exact presentation can vary with Cypress, Chai, and reporter versions.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Make each label specific and brief
A useful label tells you which behavior, element, or post-action condition failed. For example, “confirmation after submitting the form” is more informative than “value” or “should contain,” which merely repeats implementation details.
cy.get('[data-testid="submit"]').click()
cy.get('[data-testid="confirmation"]').should(($confirmation) => {
expect($confirmation, 'confirmation after submitting the form')
.to.contain('Your request was received')
})Use labels selectively. When the test title and assertion already make an expectation obvious, an additional label may add little. Cypress’s best-practices guidance also recommends readable assertions and discusses grouping assertions in integration tests.
Keep Cypress retries working for you
Cypress retries assertions in a .should() chain until they pass or time out. A callback passed to .should() can contain several labeled expect assertions about the same yielded subject, but Cypress may run that callback more than once. Keep it limited to repeatable assertions: do not enqueue Cypress commands or perform external side effects inside it. A label annotates the expectation; it does not alter the retry model. Details are in the API documentation.
If conditions are independent or a callback makes the test hard to follow, use separate queries and assertions instead. The goal is to make the failed expectation easy to locate, not to compress the test into one opaque block.
Assert the required result, not merely that something changed
A clear label cannot make an incorrect assertion reliable. A negative assertion such as not.have.length(2) after adding a todo can pass for several wrong reasons: the application might have deleted the list, removed an existing item, or added a blank item. Cypress explains this risk in its assertions reference.
When the required outcome is a particular list and item, assert those outcomes directly, as in the example above: the expected item count and the new todo’s text. Use a negative assertion when absence itself is the behavior being tested and other plausible incorrect states are controlled.
Choose selectors based on whether text is part of the contract
If changing visible wording should fail the test because the wording is part of the required behavior, select by text. If a copy edit should not count as a behavior change, prefer a stable data attribute. Cypress describes this distinction in its best-practices guidance. Selector choice helps keep failures focused on behavior rather than incidental copy.
Rank #4
Read the whole failure report
A custom assertion label is one clue, not a replacement for Cypress’s other diagnostics. Depending on the failure and the versions and reporter in use, output can include an error name and message, expected and actual values, a Learn more link, source file and line information, a code frame, and a stack trace. Cypress describes useful failures as readable and actionable in its code-frame article.
Free tools Windows power users keep installed
One-click scans. No signup required.
For end-to-end failures, Gleb Bahmutov’s 2017 article “Good error messages” describes the goal of explaining the expected outcome and showing relevant UI information at failure time. Treat that as historical context rather than a guarantee that every current failure displays identical UI details.
Best Value
Pick the assertion style that makes the failure clearest
| Choice | Use it when | What it contributes |
|---|---|---|
expect(subject, 'label') |
A specific expectation needs added context. | A short assertion-level label in the Command Log. |
A built-in .should() chainer, such as should('have.text', value) |
The chainer already states the expected behavior clearly. | A concise assertion with an expected/actual comparison. |
| A positive assertion of expected content or state | The test must prove a particular outcome. | A direct check of the required result. |
| A negative assertion | Absence is itself the behavior and other failure modes are controlled. | A check for absence, which can be ambiguous if many wrong states also satisfy it. |
| Text locator or data attribute | Choose text when wording is part of the contract; choose a data attribute when copy is incidental. | Controls whether a wording change should fail the test. |
Troubleshoot confusing assertion failures
- The label is missing or formatted differently: confirm the installed Cypress, Chai, and reporter versions. Cypress documents labels in the Command Log, but exact formatting can differ.
- The assertion passes even though the intended result is wrong: inspect whether a negative assertion admits other incorrect states. Assert the expected content or state directly.
- The test behaves inconsistently after adding a callback: remember that Cypress can retry the
.should()callback. Remove commands and non-repeatable side effects from it. - A copy edit causes an irrelevant failure: if wording is not part of the behavior, select the element with a stable data attribute rather than its text.
- The label does not explain the failure: name the expected behavior or the item and condition being checked, then inspect the expected/actual values and source location in the rest of the failure report.
Or skip the browser setup
For capturing a page screenshot rather than diagnosing a Cypress assertion, ScreenshotNeo offers a website screenshot API and MCP server. One GET request can return an image or PDF. For example, save a WebP screenshot of a page with cURL:
Quick Recap
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and the Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up free for 1,000 screenshots a month with no card.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
