asciidoctor / asciidoctorj-screenshot

A set of AsciidoctorJ extensions for adding automated screenshots to an AsciiDoc document.

AsciidoctorJ Screenshot Extension

This AsciidoctorJ extension automates the documentation of your webapp using screenshots. No more hassles when you change simple settings like CSS or change that button that was too big. Your documentation stays up to date!

Quick reference

Basic usage is a block macro screenshot that points to a URL: The title of the block macro is used as the caption of the image.

.Google Landing page
screenshot::http://google.com[google]

Use a block geb to control the browser (e.g. for filling in a form or doing a login) The content of the block is passed to Geb. Geb is then taking control of the browser.

[geb]
....
go "http://google.com"
$("input", name: "q").value("asciidoctor")
Tread.sleep(5000)
....

Parameters

screenshot

The screenshot block macro has the syntax screenshot::<url>[<parameters>] and supports the following parameters (note: the URL is not needed when the browser was navigated to the page using a geb block or other means)

name

an optional unique file name (will be generated otherwise), the screenshot will be called <name>.png. This is the first positional parameter.

frame

Try awesomeness with iphone5, nexus5 or browser. This is the second positional parameter.

dimension

size of the screenshot in the format <width>x<height> for instance 800x600. Also the values of 'frame' are supported.

selector

the CSS-like dom selector to screenshot. Only this will be part of the image. For instance div #login_window.

width

if set the value is passed unchanged to the backend (e.g. HTML or PDF). The behavior is the same as setting this attribute on an image block.

height

if set the value is passed unchanged to the backend (e.g. HTML or PDF). The behavior is the same as setting this attribute on an image block.

Note: it is not allowed to set both 'frame' and 'dimension' or 'frame' and 'selector' for a screenshot. Note: screenshot::http://google.com[google] and screenshot::http://google.com[name=google] are equivalent.

geb

The geb block supports the following parameters:

dimension

size of the screenshot in the format <width>x<height> for instance 800x600. Also the values of 'frame' are supported. This is the first positional parameter.

The content of the geb block can be any valid groovy script. The following bindings are defined and my be used within the script:

Browser

The class geb.Browser

Dimension

The class org.openqa.selenium.Dimension

Keys

The class org.openqa.selenium.Keys

asciidoc

a map containing all attributes defined in the current asciidoc file (including the attributes of the geb block). This is useful to pass information like an URL, username, password, etc. to the script.

Examples

.The Google landing page
screenshot::http://google.com[google]

[geb]
....
$("input", name: "q").value("asciidoctor")
Tread.sleep(5000)
....

.Some propositions should appear
screenshot::[frame=BROWSER]

[geb, dimension=iphone5]
....
$("h3.r a").click()
....

.Look Ma, it's Nexus 5!
screenshot::[frame=nexus5]

asciidoctorj-screenshot's Issues

Expand attributes in extension

Asciidoctor does not expand the attributes (variables) for extensions.
This needs to be done at least for the URL in the screenshot macro.
Maybe we need to also do this for the content of the geb block

cannot build/test this on OSX

not sure if it is OSX only, but that is what I have available right now.

I tried various examples of ascidoctorj-screenshot and they all failed to do anything but start firefox and then nothing happened.

Now tried building this repo and I get the same result - firefox starts up but nothing working after that.

:compileJava UP-TO-DATE
:compileGroovy UP-TO-DATE
:processResources UP-TO-DATE
:classes UP-TO-DATE
:jar
:groovydoc UP-TO-DATE
:docJar
:sourcesJar UP-TO-DATE
:assemble
:licenseMain UP-TO-DATE
:licenseTest UP-TO-DATE
:license UP-TO-DATE
:compileTestJava UP-TO-DATE
:compileTestGroovy
Download https://jcenter.bintray.com/org/spockframework/spock-core/1.0-groovy-2.4/spock-core-1.0-groovy-2.4.pom
Download https://jcenter.bintray.com/org/spockframework/spock-core/1.0-groovy-2.4/spock-core-1.0-groovy-2.4.jar
:processTestResources
:testClasses
:test

org.asciidoctor.extension.GebBlockSubstitutionTest > test keys in geb block FAILED
    org.openqa.selenium.WebDriverException at GebBlockSubstitutionTest.groovy:70
        Caused by: org.openqa.selenium.WebDriverException at GebBlockSubstitutionTest.groovy:70
            Caused by: org.openqa.selenium.firefox.NotConnectedException at GebBlockSubstitutionTest.groovy:70

org.asciidoctor.extension.GebBlockTest > test keys in geb block FAILED
    org.openqa.selenium.WebDriverException at GebBlockTest.groovy:67
        Caused by: org.openqa.selenium.WebDriverException at GebBlockTest.groovy:67
            Caused by: org.openqa.selenium.firefox.NotConnectedException at GebBlockTest.groovy:67

org.asciidoctor.extension.ScreenshotMacroBlockTest > default dir for images should be 'screenshots' below 'destination_dir' FAILED
    org.openqa.selenium.WebDriverException at ScreenshotMacroBlockTest.groovy:65
        Caused by: org.openqa.selenium.WebDriverException at ScreenshotMacroBlockTest.groovy:65
            Caused by: org.openqa.selenium.firefox.NotConnectedException at ScreenshotMacroBlockTest.groovy:65

org.asciidoctor.extension.ScreenshotMacroBlockTest > take configured dir name for images FAILED
    org.openqa.selenium.WebDriverException at ScreenshotMacroBlockTest.groovy:75
        Caused by: org.openqa.selenium.WebDriverException at ScreenshotMacroBlockTest.groovy:75
            Caused by: org.openqa.selenium.firefox.NotConnectedException at ScreenshotMacroBlockTest.groovy:75

> Building 84% > :test > 20 tests completed, 4 failed
> 
> ```
> ```

i'm running firefox 48.0.1 if that matters.

[Bug] screenshot directory problem

Hello again.

I'm still using Maven.

My image dir : <imagesdir>./images</imagesdir>

The screenshots are written in target/generated-docs/screenshots

The generated HTML says the image is there src="./images/screenshots/asciidoctorj-screenshot.png"

With the extra /images in path, it is not displaying...

Did I miss something ?

Support for other browsers than firefox

Currently only Firefox is supported. Allow to configure the browser.

Change output configuration

Change the way the output directory is configured to resemble the way it is done in the asciidoctor-diagram extension

Add SPI for capturing the screenshot

If the step of capturing the screenshot was made pluggable via an SPI (i.e., ScreenshotTaker), this extension could be used to import screenshots taken using a specialized workflow. Such an SPI would promote reuse by making this extension a foundation for describing how to capture screenshots from AsciiDoc. The custom code would only have to worry about taking the screenshot.

As an example, the documentation team may use a service that sets up an application and exposes an API that instructs that service to capture and furnish a screenshot. This extension, via the SPI implementation, would merely have to receive that image and return it. The extension would then proceed as it does today, ultimately adding that image into the AST.

Allow to scale image

as @bcouetil mentions in # 13 (#13 (comment))

It would be nice if the screenshot could be scaled by asciidoctor after it was taken.

screenshot::${url}[dimension=1024x780,width=600]

Where dimension is interpreted by the screenshot extension and width is passed to the converter to do the scaling

Tutorial needed

this plugin seems to be quite helpful, however, I don't manage to set it up.

A quick guide on how to set it up would be great.

[Bug] Screenshot taking top left corner only

Thank you for this useful extension.

Using this code under maven inspired from the pom.xml example :
screenshot::https://bcouetil.gitlab.io/academy/sample/reveal/reveal-my-asciidoc.html[asciidoctorj-screenshot,dimension=640x480]

The module opens chrome, resizes it, And I can see that everything is there :

But on the result image, I see only the top left corner :

• Is is expected ?
• If so, I do I get all what Chrome displays ?
• dimension resizes before the screenshot, how to resize after ? Like when we use width=800 in asciidoc file.

Thanks.

Browser not closed

When executing asciidoctor task for generating screenshots but with Gradle Daemon enabled, the browser is not closed after the documentation is generated.

I have executed asciidoctor task first with daemon enabled and I noticed this behaviour, then I executed the same task but with daemon disabled and it worked, so it seems that this is the cause of the problem since it has been the only difference.

[Bug] Closing problem when multiple backends including PDF

I understand that the plugin is not intended to work with PDF.

But, under Maven, I generate my documentation for Reveal.js, HTML and PDF together, and I have a critical bug when going through the PDF generation :

GRAVE: (NameError) no method 'process' for arguments (org.jruby.RubyObjectVar9,org.jruby.RubyObjectVar9) on Java::OrgAsciidoctorExtension::ShutdownGebPostProcessor
  available overloads:
    (org.asciidoctor.ast.Document,java.lang.String)
    (org.asciidoctor.ast.DocumentRuby,java.lang.String)

I tried wrapping the code with ifndef::backend-pdf[] without success, before finding that, even without using any block, simply having the Maven dependency gives the critical error. And I did not find a way to have a Maven dependency only on a specific execution.

Just searching for a way to not block the process...

Support of Geb pages

Geb supports the page object pattern. This allows to keep the element selectors in a single place and reuse it everywhere. It would be great if we can make use of this page objects in the geb block and the screenshot macro.