[Koha] Screenshots internationalization for the manual (and acceptance tests?)

[Jonathan Druart]

Hello everybody,

I have spent (too much) time trying to automatically generate the
screenshots of the manual.
The idea behind that was multiple: keep the screenshots up-to-date from one
version of Koha to the others, and generate screenshots in each language of
the manual.
I was really excited after the first half hour when I successfully took my
first screenshot with only few lines of code.
But after a couple of days I realize that the task is very huge: we have
more than 1300 images in the manual, and I have generated only 68 so far.

First I need to know how important is that for you. Will it really change
our lives to have screenshots translated in other languages (and kept in
sync with the interface)? How important is the value added?
One thing is sure: if someone wants to translate screenshots, they should
do it in a generic way so all languages can take advantage of it.

The hidden added value of such mechanism is to add a huge test coverage: we
are going to make sure the screenshots can be generated in several
languages, catching issues we do not cover in our test suites, etc.
A bit of technique: the screenshots are taken using Selenium tests (which
we already use a bit in the test suites): it simulates a user's interaction
with the interface.

The big problem is that, for now, only developers could help me.
But do not stop reading now please :)

The code looks like that:
C4::Context->set_preference('SpecifyReturnDate', 1);
$driver->get($base_url.'circ/returns.pl');
screenshot("SpecifyReturnDate", { class => "yui-u first" });
For the "SpecifyReturnDate" screenshot, we set the syspref to 1, hit
returns.pl and create a screenshot from the element with a class "yui-u
first" (yes the element should have an id).
As you can imagine this one is part of the easiest ones.

Now imagine "FineNotifyAtCheckin", we want to capture the alert box when
the patron has fines and returns an item.
The code is:
C4::Context->set_preference('FineNotifyAtCheckin', 1);
my $b = Koha::Items->find(74)->barcode;
issue( $patron, $b );
Koha::Account::Line->new({ borrowernumber => $patron->borrowernumber,
accountno => 1, amountoutstanding => 5 })->store;
checkin( $b );
screenshot("FineNotifyAtCheckin", { class => "dialog alert" } );
Koha::Account::Lines->search({ borrowernumber => $patron->borrowernumber
})->delete;
First I assume I have an item with itemnumber=74 that can be issued by a
given patron. I check it out and create a fine of 5. I check the item in
and tadaaa I can take the screenshot for the alert dialog. Then I clean up.

And trust me, this is not the hardest.

So what I suggest is that, if (and only if) people are very interested in
contributing to translate the screenshots and in the concept of having the
whole interface tested, we could offer an easy way to contribute to this
project.

We could do that using Cucumber (see also bug 13849), and let people write
something much more readable (by anybody), like:
Scenario: Take a screenshot for SpecifyReturnDate
Given I have set the syspref SpecifyReturnDate to 1
And I hit the circ/returns.pl
Then I take a screenshot of the element with the class "yui-u first"

Or:
Scenario: Take a screenshot for FineNotifyAtCheckin
Given I have set the syspref FineNotifyAtCheckin to 1
And I checked an item out to a patron
And I added a fine of 5 to the patron
And I checked the item in
Then I take a screenshot of the element with the class "dialog alert"

Does it seem more readable?

Let me know what do you think of that and if you are willing to help.
Then I will see if I can dedicate more time to this project.

Cheers,
Jonathan

Additional information:
- For now only sample data from "en" are used. Part of the interface is not
translated yet (item types, authorised values, framework, etc.)
- The process does not finish for "fr" because of bug 20043
- I have already found several bugs (not reported yet) writing these tests.
- The screenshots I generated are from the installer (all of them) and the
administration part (~50%)
- Currently I cannot regenerate only 1 screenshot (if something went wrong
for instance). They should be independent (unless for the installer part)
and the script should take an image name in parameter (like perl
generate_screenshot.pl --name FineNotifyAtCheckin --lang es).
- Could be done later:
* Generate screenshots for "fr" with UNIMARC data
* Use sample data from the language we want
* Have separate data set depending on the language (like having the biblio
titles or patron names depending on the region: John Doe for 'en', Jean
Dupont for 'fr', Juan Pérez for 'es', etc.)
* And certainly much more...
The links to what have been done so far: (manual with only the installer
and administration sections, these links are temporary)
ar - http://download.koha-community.org/manual/wip_screenshots/ar/html/
en - http://download.koha-community.org/manual/wip_screenshots/en/html/
es - http://download.koha-community.org/manual/wip_screenshots/es/html/
it - http://download.koha-community.org/manual/wip_screenshots/it/html/
pt_BR -
http://download.koha-community.org/manual/wip_screenshots/pt_BR/html/
zh_TW -
http://download.koha-community.org/manual/wip_screenshots/zh_TW/html/

Here is the list of the images that have been generated:
https://pastebin.com/RQV35cu2