bahmutov/cypress-examples

Static site with Cypress examples tested right from the Markdown sources

@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
• 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

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.config.js 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

cypress-examples's Issues

Proof of concept for Cypress test runner to use this package

Before we switch over, let's see if we can have it as a dependency, replacing Kitchensink

Assert that text is not visible, whether present in DOM or not

From gitter:

http://on.cypress.io/dom#is-visible

Need contents bar on the left for the root index page

The page is quite long and lacks navigation

Do not generate docs/index.js file

From docs/index.md

Because the file has not tests, just

/// <reference types="cypress" />
describe('Cypress Examples', () => {
  before(() => {
    cy.visit('http://localhost:5000/cypress-examples/5.6.0/index')
  })
})

Bump bootstrap back to v4

V3 looks weird. Might need to add css class "hidden"

404 - cy-wrap page

https://glebbahmutov.com/cypress-examples/9.6.0/cypress-examples/9.7.0/commands/misc.html#cy-wrap

How to show the code under test live better?

In Kitchensink we have bootstrap markup rendered live side by side with the test code

In these examples, we can show the HTML and optionally mount it too and then do the test

I really like seeing the HTML markup, since I can understand how the test works better, but I miss having a live element.

Maybe we can style the live element better?
Maybe we can avoid duplication and use the live element as HTML or render one into the other automatically? Maybe it could be a special Vue widget for showing source and live element?

Scraped links are incorrect

Build breaks on Node v18

Decide what to do about the root pages

Should they be a copy of the latest deploy or should they redirect to the latest deploy?

Do not add text inputs to the wrong element

https://glebbahmutov.com/cypress-examples/6.2.0/recipes/form-input-by-label.html

funny

CI fails

Problem description

CI fails. See https://github.com/bahmutov/cypress-examples/actions/workflows/ci.yml, for example run 3976367744

The job test-js fails. See also record in Cypress Cloud https://cloud.cypress.io/projects/dis6wg/runs/1191/specs

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• Update dependency @vuepress/plugin-docsearch to v2.0.0-rc.0
• Update dependency cypress to v13.13.2
• Update dependency cypress-markdown-preprocessor to v1.10.11
• Update dependency start-server-and-test to v2.0.5
• Update dependency vuepress to v2.0.0-rc.14
• Click on this checkbox to rebase all open PRs at once

Detected dependencies

github-actions

.github/workflows/ci.yml

• cypress-io/github-action v6
• cypress-io/github-action v6
• cypress-io/github-action v6
• cypress-io/github-action v6
• cypress-io/github-action v6

.github/workflows/collect-fiddles.yml

.github/workflows/deployed.yml

• cypress-io/github-action v6
• cypress-io/github-action v6

.github/workflows/deployment.yml

.github/workflows/prettier.yml

.github/workflows/scrape.yml

• cypress-io/github-action v6

npm

package.json

• @vuepress/plugin-docsearch ^2.0.0-beta.61
• cypress 13.13.1
• cypress-book 1.5.0
• cypress-map ^1.40.0
• cypress-markdown-preprocessor 1.10.10
• cypress-recurse ^1.31.2
• start-server-and-test 2.0.4
• vuepress 2.0.0-beta.61
• vuepress-plugin-clean-urls 1.1.2

nvm

.nvmrc

---

• Check this box to trigger a request for Renovate to run again on this repository

Add redirects for recipes

So we can give URLs without a version. Right now only the commands and other stuff has redirect HTML pages

ignore some changed regions when comparing the screenshots

I think because of the difference in test timings, the screenshot sizes change too much. Maybe ignore the test durations somehow.

The place holder image site does not work

Causes the actions.js to break

Make sure every page has all existing tests

Look at the Kitchensink repo to make sure our markdown has all tests. Kitchensink online might be behind the tests in the repo

• Quering
• Traversal
• Actions @CypressCecelia
• Window
• Viewport
• Location
• Navigation
• Assertions
• Misc
• Connectors @CypressCecelia
• Aliasing
• Waiting
• Network Requests
• Files
• Cookies
• Spies, Stubs & Clocks
• Utilities
• Cypress API

Add dark theme

to make it easier on the eyes

Replace Kitchensink

Start using this repo instead of cypress-example-kitchensink

• what to do about all CIs? I say let's split CI examples from Kitchensink examples

Solve tough cases

There are several tests that are harder to solve dynamically

• location hardcodes full urls
• cy.root (export solves it)

Prevent AI bots from scraping this site

https://blog.qrator.net/en/best-practices-to-prevent-ai-from-scraping-your-we_190/

fix scraping

I think selectors should be updated

Can't push to fork in Windows

Running this repository on Windows 11 it is not possible to push to a fork.

"pre-push": "npm run stop-only" fails:

$ git push origin
husky > pre-push (node v12.22.12)

> @bahmutov/[email protected] stop-only 
> stop-only --folder docs --skip docs/.vuepress

Found .only here 👎
docs/commands/assertions.md:73:// 1 argument - the assertion name only like "be.visible"
docs/commands/assertions.md:361:If we only know a part of the expected attribute, we can first assert the attribute is present, then use an assertion to match its value.
...

The problem is reproducible running
npm run stop-only
directly.
(node 18.13.0 / npm 8.19.3)

npm run stop-only completes without error on Ubuntu 22.04

$ npm run stop-only

> @bahmutov/[email protected] stop-only
> stop-only --folder docs --skip docs/.vuepress

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Location: renovate.json
Error type: The renovate configuration file contains some invalid settings
Message: Invalid schedule: 'Invalid schedule: Failed to parse "before 2am every Thursday"'

need to record the results on Cypress dashboard

to be able to debug CI failures

add cypress-map plugin

I think these recipes would look great if we could show solutions based on cypress-map commands

Make sure to skip the recipes tests

Do not export them as specs

Collect Git created date for each file

To give accurate timestamps for collected fiddles

$ git log --diff-filter=A --follow --format=%aD -1 -- docs/recipes/own-text.md 
Sun, 22 May 2022 14:24:04 -0400

Add Cypress v6 cy.intercept test

New cy.intercept example in https://example.cypress.io/commands/network-requests

Make sure all tests have names from Kitchensink spec files

Give fiddles full names like https://github.com/cypress-io/cypress-example-kitchensink/blob/master/cypress/integration/examples/misc.spec.js

Check index page for all links

To all tests

Bump actions to Node v18+

Set up Renovate

To keep Cypress up to date

How to extract into spec files

We have just Markdown files, but to function as Kitchensink examples, we need to extract all fiddles as JavaScript spec files

Can we get a sidebar for each document?

To have quick navigation inside each file?

Parallelize the deployed workflow

Because it runs all JS specs against the deployed site, it is taking a while now

Follow the approach in https://glebbahmutov.com/blog/parallel-cypress-tests-gh-action/

Does not allow "run all specs"

Due to cypress-io/cypress-fiddle#99

(before hook in each spec file outside of describe)

switch away from set-output command

- name: Set Cypress version 🎁
  id: cypress
  run: echo "::set-output name=version::$(node ./src/print-cypress-version)"

- name: Print Cypress version 🖨
  run: echo "Cypress version is ${{ steps.cypress.outputs.version }}"

Can we have more examples from cypress-fiddle here?

https://github.com/cypress-io/cypress-fiddle

Post deploy is not working

https://github.com/bahmutov/cypress-examples/actions/workflows/deployed.yml

Seems the deploy action no longer triggers the right deployed event with

test-publish-scrape:
    if: github.event.context == 'github/pages' && github.event.state == 'success'

Can GitHub pages deploy under subfolder

Probably having Cypress version variable and deploying to <ULR>/version

Can 404 visit redirect to the latest version?

do not insert the form

A recipe inserts the new form into the header of the docs

Finish creating pages

Need to create all pages just like Kitchensink has

• Viewport #11
• Location #12
• Local storage

Scraped results go to the old relative link after deploying new docs versions

For example, we scraped when the link was 9.4.1

Now the docs are at 9.5.0

The search results show the correct link (and you can even open it in a new tab and it works correctly)

But if you click on the search result, it appends it to the current URL and leads nowhere

fix the click test

• missing popover plugin
• why doesn't the test fail on error?