Documentation Automated Screencapture

From Koha Wiki

Jump to: navigation, search

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

Contents

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:

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:

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:

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