14 May 2021
This contribution is a new feature.
In this contribution we will talk about a specific part of Backstage: TechDocs.
TechDocs is a docs-like-code plugin that lets you write technical documentation next to your code.
The concept is pretty simple, you write your docs in Markdown files and TechDocs creates a reader-friendly experience for you.
TechDocs consists of a backend plugin (generate, prepare and publish the documentation) and a frontend plugin (renders the documentation to the final user).
We will focus here on the frontend part as this the most relevant to us in this context. We'll just admit that the backend plugin returns our documentation as HTML/CSS files.
The component of the frontend TechDocs plugin that we will be in charge of testing is called the TechDocs Reader.
The TechDocs Reader will be in charge of getting the HTML file, running transformers on it and then renders it into a shadow DOM root. We will make sure that it does its job properly.
Here is some screenshots of what the frontend plugin looks like inside Backstage.
Some functionality of TechDocs relies on interactions between the BackStage app and the shadow root that contains the TechDocs site.
These interactions should be tested to ensure that the TechDocs features are working properly and avoid regressions.
Here is an example of some e2e tests that we will implement:
- Navigating to a TechDocs site from a given URL
- Navigating to a TechDocs site via the primary navigation bar
- Navigating to a TechDocs site fragment via the table of contents, and so on...
This PR being still Open, some parts are likely to change.
I will keep the article updated if any changes are made.
But first... What is Cypress?
Here is a screenshot of the Cypress user interface running Backstage:
In the screenshot above you can see:
- the test status menu used to see how many tests passed or failed
- the app preview used to see what happens in your app while the tests are running
- the command log which shows the different steps of your tests (also called "time travel")
Cypress comes with its own API for creating custom commands that we can use in our tests.
We will define two commands:
loginAsGuestto log the User as a guest by setting the custom cookie
getTechDocsShadowRootto get the shadow DOM root of the TechDocs site more easily
In order to make certain elements visible (like the table of contents), we have to set a custom viewport size.
We will take the
macbook-15 preset dimensions and define those values inside the
cypress.json configuration file.
This will tell Cypress to set a custom screen size for our application.
Our first test will be to check that the User can correctly access the TechDocs home page.
We can access it by visiting the
Or we can access it through the Backstage context via the primary navigation bar to the left.
Writing the corresponding Cypress tests gives us the following code.
Note that we use the
data-testid selector as by default Cypress will favor .
By retrieving the elements with a
data-testid attribute, we make sure that our tests are not coupled to the behavior or styling of the element.
It also allows us to show that this element is used within our tests so that everyone is aware.
Once we have selected a specific TechDocs entity, we can check that the User can correctly navigate within the TechDocs pages via the navigation bar to the left.
We will visit the corresponding TechDocs entity page and simulate the clicks on the navigation bar items:
Overview > Roadmap.
The User can also navigate within the current page via the table of contents to the right.
By clicking on an anchor link, the page will scroll to the selected item in the page.
To test that we have scrolled to the correct element we will check that the
offsetTop value of our element equals the
scrollY of the
Here is the Cypress test that covers this case.
The last test that we want to cover is the
Previous/Next links at the bottom of each page.
We'll check that the
Previous link takes us to the previous page.
Once again we will visit a TechDocs page, click on the previous link defined by its class
md-footer-nav__link.md-footer-nav__link--next and make sure that it takes us to the correct page.
Here is the final test-suite that covers the different interactions between the Backstage context and the TechDocs site embedded. As we can see all the tests are completed in 32s.
As the TechDocs frontend is strongly linked to the API response and we don't know how all this stuff will change in the future, we will certainly not mock the API response as we used to do but let the backend do its job.
It means that I will certainly need to remove the API mocks in the tests and add data-testid attributes dynamically inside the generated html files.
This contribution has allowed me to define some user workflows and use Cypress to test them.