Visual testing on Asciidoctor User Manual

[ggrossetie]

Install and testing procedure:

 $ npm install
 $ casperjs test spec/testsuite.js

Generate reference screenshots:

 $ rm -f spec/screenshots/*
 $ asciidoctor spec/fixtures/docs/user-manual-intro.adoc

Generate user manual with the latest stylesheet:

 $ asciidoctor -a stylesheet=../../../asciidoctor.min.css spec/fixtures/docs/user-manual-intro.adoc

NOTE: Do not forget to unable Google Fonts (ie. uncomment the @import)

Run test again:

 $ casperjs test spec/testsuite.js

Currently PhantomCSS hangs if I run the visual testing against the complete user-manual.html (ie. with the content div). Maybe PhantomCSS doesn't like id duplications (see https://github.com/asciidoctor/asciidoctor.org/issues/565) or maybe the document is too big to be analyzed within reasonable time.

TODO

• [x] Add install and testing procedure to the README
• [x] Update user-manual.html with the latest stylesheet
• [x] Fix footer date to avoid regression

[ggrossetie]

@mojavelinux In the intro section of the User Manual, the only visual "regression" are:

• Padding on admonition block is slightly different (space between the icon and text)
• Responsive breakpoints are not exactly the same (with a 1024px*768px viewport)

Differences in pink:

I changed viewport to 1920px*1080px

[ggrossetie]

@mojavelinux Could you please enable Travis build ? I want to know if the build is working on Travis :relaxed:

[mojavelinux]

Yep! I can take care of that.

[mojavelinux]

Enabled. I think you need to force push to trigger the build.

[mojavelinux]

This will be very important for me to get back to the work to upgrade us to Foundation 5/6. That requires changing from ems to rems in a lot of places and that introduces to room for a lot of subtle, hard to detect changes.

[ggrossetie]

cssshrink is incompatible with the latest version of color:

https://github.com/stoyan/cssshrink/pull/33 https://github.com/stoyan/csscolormin/pull/6

EDIT: Another way to fix this issue is to find out which of the color* librairies is compatible with cssshrink. I tried but I think it's better to upgrade :wink:

[mojavelinux]

I'd rather lock the version. I really don't want to spend a lot of time on upgrading tools since we might change the way we build the stylesheet anyway. That's where the visual testing comes in.

[ggrossetie]

I'd rather lock the version. I really don't want to spend a lot of time on upgrading tools since we might change the way we build the stylesheet anyway. That's where the visual testing comes in.

@mojavelinux That was my initial plan but I couldn't figure out what version of color and color-string is compatible with csscolormin. I will try again to find a compatible version. If cssshrink is working on your machine, could you please give me the output of npm list--depth=0 ?

I think we should use yarn "lockfile"... so that, even if an author of a Node module does not use specific version we should have a reliable build ! 🚀

[mojavelinux]

Here's the output you requested:

└─┬ cssshrink@0.0.5
  ├─┬ csscolormin@0.0.5
  │ ├─┬ color@0.11.3
  │ │ ├── clone@1.0.2
  │ │ ├── color-convert@1.5.0
  │ │ └── color-string@0.3.0
  │ └─┬ color-string@0.4.0
  │   └── color-name@1.1.1
  ├─┬ gonzales-ast@0.0.6
  │ └── gonzales@1.0.7
  └── prettyugly@0.0.5

I think we should use yarn "lockfile".

100%

[ggrossetie]

@mojavelinux Thanks, the build is now running fine, but the screenshots are slightly different. I think we need to upload the generated screenshots somewhere... maybe we could use GitHub pages ?

[mojavelinux]

We're going to use backstopjs to regression test the default stylesheet instead. See https://github.com/asciidoctor/asciidoctor/issues/4070