Gleb Bahmutov PRO
JavaScript ninja, image processing expert, software quality fanatic
https://lizkeogh.com/2019/07/02/off-the-charts/
+3 degrees Celsius will be the end.
C / C++ / C# / Java / CoffeeScript / JavaScript / Node / Angular / Vue / Cycle.js / functional
(these slides)
Markdown README.md
Is this still accurate?
README.md
describe('Mailto', () => {
it('screenshot', () => {
cy.visit('/'); // localhost:3000
cy.get('#to').type('me');
cy.get('#subject').type('Date night');
cy.get('#body').type('Have plans?');
cy.get('#output').should(
'have.text',
'mailto:me?subject=Date%20night&body=Have%20plans%3F',
);
cy.get('#mailto').screenshot('mailto');
});
});
describe('Mailto', () => {
it('screenshot', () => {
cy.visit('/'); // localhost:3000
cy.get('#to').type('me');
cy.get('#subject').type('Date night');
cy.get('#body').type('Have plans?');
cy.get('#output').should(
'have.text',
'mailto:me?subject=Date%20night&body=Have%20plans%3F',
);
cy.get('#mailto').screenshot('mailto');
});
});
README.md
our test
manual update never works long-term
Test screenshot
README image
$ npm i -D cypress-book
+ cypress-book@1.5.0
name: ci
on: push
jobs:
test:
runs-on: ubuntu-latest
env:
DEBUG: cypress-book
steps:
- name: Checkout 🛎
uses: actions/checkout@v2
# use https://github.com/cypress-io/github-action
- name: Run tests 🧪
uses: cypress-io/github-action@v2
with:
start: npm run dev
- name: Copy social image
run: |
npx copy-image \
-s cypress/screenshots/spec.js/mailto.png \
-o media/demo.png
# now let's see any changed files
- name: See changed files 👀
run: git status
- name: Commit any changed files 💾
uses: stefanzweifel/git-auto-commit-action@v4
with:
commit_message: Updated screenshots
file_pattern: '*.png'
.github/workflows/ci.yml
changed image is committed to the repository
changed image is committed to the repository
Version badge
name: badges
on:
push:
# update README badge only if the README file changes
# or if the package.json file changes, or this file changes
branches:
- master
paths:
- README.md
- package.json
- .github/workflows/badges.yml
schedule:
# update badges every night
# because we have a few badges that are linked
# to the external repositories
- cron: '0 3 * * *'
jobs:
badges:
name: Badges
runs-on: ubuntu-20.04
steps:
- name: Checkout 🛎
uses: actions/checkout@v2
# using https://github.com/bahmutov/dependency-version-badge
- name: Update version badges 🏷
run: npx -p dependency-version-badge update-badge cypress
- name: Commit any changed files 💾
uses: stefanzweifel/git-auto-commit-action@v4
with:
commit_message: Updated badges
branch: master
file_pattern: README.md
.github/workflows/badges.yml
vs
added image
The image is used here
The test code
making the image
is here
Can we keep these two related things close?
# mailto ![cypress version](https://img.shields.io/badge/cypress-6.8.0-brightgreen)
![Demo image](./media/demo.png)
<!-- fiddle Mailto screenshot -->
```js
cy.visit('/'); // localhost:3000
cy.get('#to').type('me');
cy.get('#subject').type('Date night');
cy.get('#body').type('Have plans?');
cy.get('#output').should(
'have.text',
'mailto:me?subject=Date%20night&body=Have%20plans%3F',
);
cy.get('#mailto').screenshot('mailto');
```
<!-- fiddle-end -->
README.md
const mdPreprocessor = require('cypress-markdown-preprocessor');
module.exports = (on) => {
on('file:preprocessor', mdPreprocessor);
};
cypress/plugins/index.js
{
"testFiles": "README.md",
"integrationFolder": "."
}
cypress.json
README tests ⏩ screenshots ⏩ static project site
Cypress
VuePress
@bahmutov on Twitter
gleb.bahmutov@gmail.com
If you have ideas how to include them better in the documentation, let me know
If I see a question on a forum, GitHub, Twitter, etc
How do I toggle a checkbox?
App HTML
Test code
Markdown file
Markdown file
Markdown file
HTML code block
is mounted as live app
Markdown file
JS code block
runs as a test
Markdown spec also becomes a static docs page
Every example is scraped into the docs index
Documentation makes or breaks projects
Remember: Are you selling the drills and not the holes
Video of the entire spec file test run
A picture is worth a 1000 words
A 30fps 10 second video is worth 300,000 words
By Gleb Bahmutov
Keeping the documentation up-to-date with the web application is hard. The screenshots and the videos showing the user how to perform some task quickly fall out of sync with the latest design and logic changes. In this presentation, I will show how to use end-to-end tests to generate the documentation. By keeping the tests in sync with the application, and by running them on every commit, we will update the documentation, ensuring our users never get confused by the obsolete docs. Presented at TestingStage 2021, video at https://youtu.be/H9VqsTZ9NME
JavaScript ninja, image processing expert, software quality fanatic