https://github.com/asciidoctor/asciidoctorj-screenshot
A set of AsciidoctorJ extensions for adding automated screenshots to an AsciiDoc document.
https://github.com/asciidoctor/asciidoctorj-screenshot
asciidoctor asciidoctor-extension screenshot
Last synced: 3 months ago
JSON representation
A set of AsciidoctorJ extensions for adding automated screenshots to an AsciiDoc document.
- Host: GitHub
- URL: https://github.com/asciidoctor/asciidoctorj-screenshot
- Owner: asciidoctor
- License: mit
- Created: 2016-02-24T23:25:44.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2019-01-21T23:46:40.000Z (over 6 years ago)
- Last Synced: 2025-07-06T18:47:25.112Z (3 months ago)
- Topics: asciidoctor, asciidoctor-extension, screenshot
- Language: Groovy
- Homepage:
- Size: 19.7 MB
- Stars: 36
- Watchers: 3
- Forks: 7
- Open Issues: 4
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project
README
= AsciidoctorJ Screenshot Extension
Stephan Classen ; François-Xavier Thoorens
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 http://www.gebish.org/[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::[]` 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 `.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 `x` 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 `x` 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]
```