@bahmutov/cypress-examples

Static site with Cypress examples tested right from the Markdown sources

Live site glebbahmutov.com/cypress-examples/

Benefits

• single source of truth for tests and HTML pages. No more copy / pasting
  • Cypress runs tests using Markdown source files via cypress-markdown-preprocessor and cypress-fiddle
• great development experience with live reload and optimized static build thanks to Vuepress and Prettier formatting
• JavaScript specs are extracted and published as NPM package @bahmutov/cypress-examples after testing against the deployed site and then published to NPM under @bahmutov/cypress-examples
• excellent text and code comment search thanks to Algolia
  • Scrape Static Site with Algolia blog post
  • scrape happens after deploying the docs to GitHub Pages in .github/workflows/deployed.yml workflow
• recipes that are not included in the NPM package but deployed to the static pages
• top level pages redirect to the deployed version pages. For example if the user visits /cypress-examples/ they are redirected to /cypress-examples/x.y.z/ page.

Blog posts

The following blog posts explain how I write Cypress demo tests using Markdown in this repository

• Run End-to-end Tests from Markdown Files
• Write Cypress Markdown Preprocessor

You can see the cypress.json and plugins.js to learn how cypress-markdown-preprocessor is set tup.

Notes

• use "function" syntax in <script> tags that need to be live, otherwise Markdown escapes => arrows?!
• if the HTML block includes the <style> section, put it at the start of the block, otherwise it might get lost

Try published specs

You can run the exported spec files.

• Start a new project or use an existing project, and add this module as a dev dependency

$ npm i -D @bahmutov/cypress-examples

• Open or run Cypress and point at the folder inside node_modules

$ npx cypress open --project node_modules/\@bahmutov/cypress-examples/

Development

There is a difference between running Markdown files and testing fully exported specs against the built site. To do this all in a single command locally run

npm run dev:export

This command builds the static site, exports the Markdown specs into JavaScript specs, starts local server, and when it responds, starts Cypress.

You can also export all Markdown files into JavaScript, run them locally, and run all E2E tests using the JS specs with:

npm run run:exported