giantmonkey / 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 (i.e. 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")
waitFor(5){true}
....

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.

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")
waitFor(5){true}
....

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

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

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