How I Answer a Cypress Question

How I answer a typical user question with a tested Cypress example

I read and answer the user Cypress questions in the Cypress chat a lot. Answering just a single specific question does not scale - every answer should be a change in our documentation so that all future users that come with the same question can find the answer themselves. This blog post describes how I do this very quickly.

The question

Here is a typical question from the chat:

The user is trying to assert that multiple elements are invisible

Hmm. I do not remember asserting if multiple elements are invisible. I remember asserting that multiple elements are visible. Maybe Cypress has something broken? Maybe the negative visibility assertion does not handle multiple elements? Negative assertions can be tricky, and checking visibility is complicated.

The Markdown test

I need to test this myself. I open the cypress-examples project in my code editor and launch Cypress. This project uses cypress-markdown-preprocessor to use Markdown files as spec. I can surrounds the example HTML markup and the Cypress test commands code blocks with "fiddle" HTML comments - and this region becomes a test.

The example application markup block

The test commands can be even split across several JS code blocks with inserted explanations.

The Cypress test commands to run against the example markup

The Cypress runs the above test by mounting the HTML block as a live mini web application and then running the commands against it.

Cypress correctly retries the assertions until the elements are hidden

So our negative visibility assertion works correctly in the situations with multiple elements.

The documentation

Our test was embedded right inside the Markdown file. This file can be converted into the static HTML page. In the cypress-examples projects, we use Vuepress to convert MD to HTML. You can find the commit b588b in the repository. The commit was tested again as Markdown and as JavaScript against the converted HTML static pages.

The GitHub Actions workflow tests all documentation examples

The entire workflow runs very quickly, thanks to running all tests in parallel. After all tests pass, the static pages are deployed.

The Markdown page converted to HTML and deployed

You can see the latest version of this page at https://glebbahmutov.com/cypress-examples/commands/assertions.html or go to the Cypress version-specific page at https://glebbahmutov.com/cypress-examples/7.1.0/commands/assertions.html.

Once the page is deployed, we can send the anchor link to the example to the user who asked the question.

Answering the user question with the link to the example

📺 I have recently delivered a presentation about using the user Markdown documentation as tests. You can watch the presentation here and browse the slides at slides.com/bahmutov/tests-are-docs.

Search

After the successful deployment, the example pages are scraped, see the workflow file .github/workflows/deployed.yml.

The scrape workflow runs after each successful deployment

From now on, any user can quickly discover an example of checking if multiple elements are invisible by searching using the Algolia search widget.

The search finds our new example

You can learn more about scraping the technical documentation from my presentations Testing Your Documentation Search and Find Me If You Can and from the blog post Scrape Static Site with Algolia.

To "quote" the "Find My If You Can" presentation, I strongly believe that the users should find the answers to their questions via the search. If the answer does not exist in documentation, then:

Answer the user question with the link

Video

You can see the entire process in this 10 minute screen recording below. In this video, I answer the question "how to get and confirm attributes from multiple elements?":

Yes, it only takes a few minutes to create another tested example that is deployed only in a few minutes after all tests still pass!