Automatic Screenshots in Documentation

• Michael Hamann
• Vincent Massol

350 hours (Large size project)

Medium

At the moment, screenshots in XWiki's documentation are manually created and thus rarely updated even when the actual design or layout of the application changes. The goal of this project is to change this by automating the production of screenshots for the documentation. This consists of several parts:

• Actually take the screenshots, this should be done as part of our existing docker-based UI tests that automatically test the UI using Selenium. New UI tests should be added for at least some parts of the documentation, the idea being to cover some representative cases such that important issues can be discovered and fixed during the project.
• Store the screenshots. We need to decide if the screenshots should be stored in XWiki (the instance on xwiki.org) or in some separate place. Further, this requires to decide screenshots for which versions should be stored (e.g., current LTS and stable version and release candidate when it is more recent than the stable version, maybe the most recent build on each branch). We probably also need to ensure that we have CI jobs executed on the release itself. We will also need some way to clean up old screenshots such that we don't collect screenshots forever.
• Display the screenshots. Depending on how the screenshots are stored, we probably need some macro to display the automatically taken screenshots. For this, we also need to decide for which version the screenshot should be displayed by default and how the user can see screenshots for other versions (e.g., some kind of version selector).

Please develop more detailed ideas for these parts as part of your proposal.

We're currently considering implementing screenshot-based regression testing (aka visual testing). While this doesn't need to bother you too much, there are some areas of intersection you should be aware of and work together with us if necessary:

• For regression testing, we will have some way to determine if two screenshots match. This could also be used in this project to determine if a new screenshot should be stored.
• Regression testing also needs a way to store known-good screenshots for different branches. Maybe this could be integrated with the screenshot storage of this project.
• The screenshots that are created by this project should be used for regression testing.
• This could be used to improve XWiki release notes so that when some improvement or new feature change an existing UI of XWiki, the release notes can show the difference before/after by showing the image diff.

To get a rough idea of this project please complete the following tasks:

• Adapt an existing integration test to take a meaningful screenshot of some UI element. Interesting tests could, e.g., be the tests for AppWithinMinutes.
• Let the test automatically upload the screenshot to an existing XWiki instance using the REST API for attachments (as attachment for an existing document). You may put both the URL, the name of the attachment and the credentials for this instance in the code for this prototype (extra credits for getting both URL and credentials from an environment variable). In the end, the attachment name could be something like {name}-{version} but for the prototype, you can just use a fixed name (or use two made-up versions to get more input for the next task).
• Write a wiki macro that lists all attachments with a certain name-prefix, displays the most recent version and displays a select for the versions.

This is not necessarily how the final project will be developed, but these tasks should help you to familiarize yourself with the tools that you'll use for the project itself and demonstrate us that you know the technologies required for this project. Further, you might already identify potential issues that you can then address in the project itself. Feel free to ask for clarification and help regarding these tasks.

You should know some Java and have some knowledge about web development (HTML, CSS, JavaScript). A plus is experience with Selenium, testing in general, and Jenkins (our CI system).

2023

Proposed