Documentation Automated Screencapture

A brain dump and notes on ideas for automating the creation of screenshots for the Koha manual.

Aim

The current situation:

• There are about 1473 images in the manual images folder [as at 2018-10-03].
• Many screenshots are probably outdated and don't reflect the current version of Koha.
• Recreating all the screenshots manually is time consuming.
• There is different sample data depending on who and when the screenshots were taken.
• Adding annotations is time consuming.
• Only covers US English interface.
• There are inconsistencies in screen size used when capturing screenshots.

The desired result:

• Updated screenshots are automatically generated for each new Koha release.
• The same sample data is used each time.
• Ability to generate screenshots for multiple languages, with example data in the appropriate language as well.

Options

Option 1 - Selenium + Robot Framework + Screenshot library

This option lets you:

• Automatically generate screenshots, including specific areas based on css classes.
• Add sample data, for example: show the fields with the data to be added before submit is pressed.
• Incorporate annotations, such as numbers or text boxes.

How it works:

• You have a 'resource' file (resources.robot) that includes variables and common 'keywords'. This can include the URL for the Koha site, usernames and passwords, common tasks such as logging in.
• You have test scripts that create the required screenshots (filename.robot). For example: log in to the staff client, go to a page, click this button, enter this data, capture screenshot of area required.
• You run the tests.
• Screenshots are generated.
• Report generated to show if tests passed or failed.

Repository with example scripts: TO ADD

Advantages:

• Automates screenshot capture.
• Meets most of the aims.
• Can version control of test scripts.
• Repeatable process once your computer is setup with the required components.

Disadvantages:

• There may be some screenshots that require manual creation.
• Initial work required to setup script for screenshot capture.
• May need to have a process for casual contributors, for example: have a temp image folder where screenshots are added, documentation team create or update scripts to generate automatically.

The components:

• Python: programming language
• Selenium: a web testing tool that lets you write a script with things you want to test, and then indicates whether it passed or failed.
• Robot Framework: works with Selenium and is more 'user friendly' to setup test scripts, rather than needing to create a Python script.
• Screenshot library: a library that works with the Robot Framework to enable screen captures.

Setup for Ubuntu Linux 18.04:

• Install Python 3 (generally already installed: test to see with python3 --version)
• Install pip3 (way to install python libraries): sudo apt-get install pip3
• Install Selenium: pip3 install selenium
• Install Robot Framework: pip3 install robotframework
• Install XXX (can't remember what this is): pip3 install robotframework-selenium2library
• Install library for screen capture: pip3 install XXX
• Install selenium browser driver for Firefox: TO UPDATE
• Add to $PATH (Linux): TO DO

Links:

• Selenium: https://selenium-python.readthedocs.io/index.html
• http://robotframework.org
• https://github.com/robotframework/robotframework/blob/master/INSTALL.rst#python-2-vs-python-3
• http://robotframework.org/robotframework/latest/libraries/Screenshot.html
• https://robotframework-selenium2screenshots.readthedocs.io/en/latest/_downloads/keywords.html - arguments for Selenium2Screenshots
• Other links and tutorials:
  • Automating Screenshots in Documentation: https://blog.codeship.com/automating-screenshots-in-documentation/
  • Selenim with Python tutorial: https://selenium-python.readthedocs.io/index.html
  • Selenium online training (not yet tested): https://www.tutorialspoint.com/selenium_online_training/index.asp
  • Sphinx + Robot Framework = documentation as result of functional testing https://sphinxcontrib-robotframework.readthedocs.io/en/latest/index.html
  • https://www.slideshare.net/plewicki/sphinx-robot-framework-documentation-as-result-of-functional-testing
  • Presentation to robocon18: https://datakurre.github.io/robocon2018/

Writing tests (see repository for examples):

• resource.robots - common variables and keywords that test scripts can reuse
• filename.robot - scripts to complete fields and capture screenshots, can be grouped in separate files

Where used:

• Used for Python documentation - TO DO add link

Integration with Sphinx:

• https://sphinxcontrib-robotframework.readthedocs.io/en/latest/index.html - Basically, you can incorporate the tests into the actual manual files when using restructured test.

Option 2 - Wraith (yet to test)

Wraith - compares two images and sees if there are any differences: https://github.com/BBC-News/wraith http://bbc-news.github.io/wraith/

TO DO - add more detail

Option 3 - Cucumber

Joubu investigate automating screenshots some time ago - see mailing list thread https://lists.katipo.co.nz/public/koha/2018-January/049807.html and https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=13849

This was also related to improving testing in Koha.

Cucumber: A behaviour-driven development (BDD) tool - see https://docs.cucumber.io/ and https://cucumber.io/blog/2017/05/15/intro-to-bdd-and-tdd

TO DO - add more detail

Other things

Optimising image sizes

Optimise images using pngcrush (reduced image folder size from 82.3 MB to 54.6 MB - about a 33% reduction in size).

Script to go through folder and minimise images using pngcrush: https://gist.github.com/tony-landis/3909387

TO DO: identify a suitable jpeg optimsation tool:

• mozjpeg? https://github.com/mozilla/mozjpeg https://images.guide/ Guide about image optimisation

TO DO

• Add numbers and annotations (see slide 19 in presentation above + docs)
• Generate images locally as part of building documentation - investigate further
• Images that can't be automatically captured - how to identify and make sure updated images created
• Image optimisation - decide on a jpeg optimisation tool
• Setup - complete this and test!
• Find link again for how used in Python documentation
• Add more detail to Cucumber and Wraith options
• Identify other options