Documentation Automated Screencapture
From Koha Wiki
A brain dump and notes on ideas for automating the creation of screenshots for the Koha manual.
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.
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
- 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.
- 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.
- 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
- Selenium: https://selenium-python.readthedocs.io/index.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
- 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
- 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)
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
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:
- 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