Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.Problem/Motivation
Currently, the process for creating screenshots for the User Guide is a bit convoluted, involving running a test via the Simpletest UI, and then using a browser plugin to make screenshots. There are several problems:
a) A couple of the screenshots we currently require to be done manually, it's because they require JavaScript and in a regular test, that is difficult to simulate.
b) Convoluted process.
c) The Simpletest UI is probably headed for end of life in Drupal Core. If it goes away, our process will die with it (although maybe it will live on as a Contrib module, but that is unclear, since no one wants to maintain it).
d) The test classes for the screenshots use \Drupal\simpletest\WebTestBase as their base class, and this class is deprecated.
So... I learned recently (thanks mixologic!) that the JavascriptTestBase class ( https://api.drupal.org/api/drupal/core!tests!Drupal!FunctionalJavascript... ) has a createScreenshot() method. We may be able to convert our tests to use this base class, and that method, and improve all of the above problems.
Proposed resolution
Figure out if this will work, and do it if so.
Remaining tasks
See Proposed Resolution.
User interface changes
Better process for making screenshots.
API changes
Not relying on deprecated base class for tests.
Data model changes
None.
| Comment | File | Size | Author |
|---|---|---|---|
| #6 | 2856747-first-chapter-6.patch | 52.64 KB | jhodgdon |
Comments
Comment #2
jhodgdonAs another note, if you run a JavascriptTestBase test using automated test running on Drupal CI, and it has screenshots, you can see them by navigating to:
> View results on dispatcher
> Build artifacts
Comment #3
jhodgdonJust a note: I am going to give this a try over the next few days...
Comment #4
jhodgdonThere's a nice tutorial here:
https://www.drupal.org/docs/8/phpunit/phpunit-javascript-testing-tutorial
Comment #5
jhodgdonI have a proof of concept of this working! There are a few differences between the new Drupal Core JavascriptTestCase base class for the tests and the old one we were using before, and the parameters for the screenshot method on the UserGuideDemoTestBase class had to be a bit different, so I'll need to go through chapter by chapter and tweak things a bit. Plus, I have so far only tested English, and only the first section of screenshots from the doPrefaceInstall() method.
Anyway, so far it seems good -- after running the tests from the command line, you end up with jpg image files in a temp directory. They'll still need to be trimmed with ImageMagick and converted to PNG files, but they look good, and on the whole I think it's simpler to set up and run than the old way. So, I'll proceed.
In the meantime, I thought I would post a patch here so in case my computer crashes or something -- it took me a bit of work to get this far and I'd hate to lose it! I'll be busy the next few days and will continue working on this next week.
Comment #6
jhodgdonPhew! A lot of work to get non-English languages working -- mostly trouble with importing the translations from localize.drupal.org. But, after several work-arounds, I have this working, at least on the first chapter (Preface screenshots), for Catalan and French, and I'm running the other languages (including Farsi, which is being added due to #2904523: Create Persian/Farsi Screenshots, which may be an adventure since it's right-to-left).
I think the work will most likely be worth it though, because with the new process, it's actually possible that someone besides me would be able to create screenshots -- it's a way simpler process, and less finicky.
Anyway, I thought I'd attach a new patch. Still to do:
a) Finish running the first chapter for the other languages besides French, English, and Catalan, and make sure they're working.
b) Rework the rest of the chapters and run them.
Comment #8
jhodgdonOK! I just made the first commit for this -- I made new screenshots for all 7 languages that we currently are making screenshots for (including now Farsi/Persian), just for the first section (Preface and Installation chapters). I also created new database/files backups, which contain more complete translation imports (hopefully that will take care of #2887495: Automated screenshots have English in them, but since only a few strings were used in the first few screenshots, I cannot be entirely sure yet).
Over the next few days, I will be fixing up and running the rest of the chapters' screenshots, and most likely I will make one commit per chapter or so with all the languages in it.
Comment #10
jhodgdonWell. I had major problems with the next chapter, mostly due to, apparently, known fatal bugs in the PhantomJS browser that JavascriptTestBase uses. After numerous web searches for work-arounds, I could get most of the languages to run, but not all.
After spending several days on the effort, I am giving up. I decided it is not worth the trouble to do this. So, I'm closing this as a Won't Fix. It will be a problem when drupal 9.x comes out, because the test classes we are using are going away, but we'll deal with it then... maybe some of the bugs will be fixed by then (although I kind of doubt it, having looked at the issues and seeing no progress on them).
Very discouraging really... Oh well! In the process I did figure out a solution to #2887495: Automated screenshots have English in them, which I will implement. Meanwhile, I have reverted the earlier commit.