What if your e2e tests generated your user documentation?

Bare with me for a moment while I shed some light 💡 on that.

I think it’s fair to say software developers understand the importance of writing tests; I’ve certainly seen a great uptake in that in recent years 👍.It’s also fair to say up-to-date documentation would be very helpful on many levels: Developers ramp up quicker, non-developer co-workers understand the system better and most importantly, user-facing documentation (if written well and read by users) increases user satisfaction.

Write tests

To quote Guillermo Rauch:

Quite frankly, this used to be very time consuming. Times have changed and tools such as Cypress.io (https://www.cypress.io/) don’t over-promise by saying “Fast, easy and reliable testing for anything that runs in a browser.”

In this blog post, I am going to focus on Cypress.io’s video recording and how to leverage that. To learn more, I recommend https://docs.cypress.io/guides/guides/screenshots-and-videos.html#Videos.

Write documentation

Knowing how to write integration / end-to-end tests, let’s focus on a currently still quite dark area (based on my experience): Documentation.

As developers, many of us like to build features, solve problems, deploy code, the list goes on. I have rarely seen “write documentation” listed in a pull request template’s task list, not to mention excitement on a peer’s face when they’re asked to write documentation 😜.

Again, that’s because it’s time consuming and much more so than e2e tests, quickly becomes stale and with that, useless or confusing to the reader.

(If you do want to write and publish documentation, it’s worth researching about https://docusaurus.io/).

So what if documentation could be automatically generated and kept in sync with the source code, hence the user interface in a web app would be 100% identical to what’s presented in the docs — always 😮!

Let the tests generate documentation

I recently started to spend some of my free time to contribute to https://github.com/withspectrum/spectrum in an effort to give back to a project I truly believe in and a product I recommend to friends and peers to connect with like-minded people in a number of online communities.

Spectrum uses Cypress.io for end-to-end tests. At the time of this writing, 104 tests exist and complete in roughly 15 minutes. Now, remember when I mentioned Cypress.io’s video recording feature above? That’s enabled in Spectrum’s code and after I ran the tests, I had a video file I can watch, pause, and resume to get a high-level overview of Spectrum’s features.

For the first time in my career as software developer, I felt excited to jump into an existing code base!

Next: Generate user documentation

So far, we have:

• End-to-end tests for product features (both happy paths and error cases)
• A single 15 minute video that visualizes how to use the product features

So what do we need next in order to generate user documentation?

**Shorter videos, ideally one video per product feature.**In Spectrum’s case: a video that shows how to register for an account or a video to explain how to join a community.The solution to that could be: The test code can use a naming convention for describe('', () => {})or it('', () => {})blocks to indicate which tests should run independently and hence create separate videos. Something along the lines of it('DOC: Register for an account', () => {}). A script then runs DOC: tests and copies the generated videos to a ./docs/videos folder, where they can be referenced in an inline help feature in the web app.

**Crop the video to what’s important to users**A screenshot of a video generated by Cypress.io looks like this:

Screenshot of a video generated by Cypress.io e2e tests

What we need for end user documentation is the web app itself, the part marked with a green rectangle. As a video, the steps described on the left execute in order, displaying the web app to the right.The solution to capture the green part is to either have a flag in Cypress.io or find a way to programmatically crop the video.

**Display the video as inline help**This part can be achieved by adding an inline help indicator (often a simple ?) next to product features a user hasn’t interacted with. Upon clicking that ?, the generated video on how to use that feature plays.

Conclusion

With Cypress.io’s video recording feature, a web app inline help system and a bit of glue code, I see a future where web developers focus on writing robust, well tested code and get bite-sized end user video documentation more or less for free.

I’ve been playing with that idea in my head for a few weeks. If anyone has some thoughts, please don’t hesitate to reach out.