Skip to content
Permalink
Browse files

browser.doc.capture test and docs

  • Loading branch information...
MykolaGolubyev committed Aug 12, 2019
1 parent 449d3c2 commit 366f7fe0feeff099322f467a41ffcad47f0a1d83
@@ -16,7 +16,7 @@

package com.twosigma.webtau.browser;

import com.twosigma.webtau.browser.documentation.DocumentationDsl;
import com.twosigma.webtau.browser.documentation.BrowserDocumentation;
import com.twosigma.webtau.browser.driver.CurrentWebDriver;
import com.twosigma.webtau.browser.navigation.BrowserPageNavigation;
import com.twosigma.webtau.browser.page.PageElement;
@@ -42,7 +42,7 @@

public final Cookies cookies = new Cookies(driver);
public final LocalStorage localStorage = new LocalStorage(driver);
public final DocumentationDsl doc = new DocumentationDsl(driver);
public final BrowserDocumentation doc = new BrowserDocumentation(driver);

public final PageUrl url = new PageUrl(driver::getCurrentUrl);

@@ -30,23 +30,23 @@
import static com.twosigma.webtau.cfg.WebTauConfig.getCfg;
import static java.util.stream.Collectors.toList;

public class DocumentationDsl {
public class BrowserDocumentation {
private TakesScreenshot screenshotTaker;
private List<ImageAnnotation> annotations;
private WebDriver driver;

public DocumentationDsl(WebDriver driver) {
public BrowserDocumentation(WebDriver driver) {
this(driver, Collections.emptyList());
}

private DocumentationDsl(WebDriver driver, List<ImageAnnotation> annotations) {
private BrowserDocumentation(WebDriver driver, List<ImageAnnotation> annotations) {
this.driver = driver;
this.annotations = annotations;
this.screenshotTaker = (TakesScreenshot) driver;
}

public DocumentationDsl withAnnotations(ImageAnnotation... annotations) {
return new DocumentationDsl(driver, assignDefaultText(Arrays.asList(annotations)));
public BrowserDocumentation withAnnotations(ImageAnnotation... annotations) {
return new BrowserDocumentation(driver, assignDefaultText(Arrays.asList(annotations)));
}

public static ImageAnnotation badge(PageElement pageElement) {
@@ -30,7 +30,7 @@
private String id;
private String type;
private String text;
private String color = "red";
private String color = "a";
private PageElement pageElement;

public ImageAnnotation(PageElement pageElement, String type, String text) {
@@ -57,7 +57,7 @@
private final ConfigValue cachePath = declare("cachePath", "user driven cache file path",
() -> workingDir.getAsPath().resolve(".webtau.cache.json"));

private final ConfigValue docPath = declare("docPath", "path for screenshots and other generated " +
private final ConfigValue docPath = declare("docPath", "path for captured request/responses, screenshots and other generated " +
"artifacts for documentation", workingDir::getAsPath);
private final ConfigValue noColor = declareBoolean("noColor", "disable ANSI colors");
private final ConfigValue reportPath = declare("reportPath", "report file path", () -> getWorkingDir().resolve("webtau.report.html"));
@@ -1,13 +1,13 @@
# Scenarios

You provide `REST endpoints` so users can execute various scenarios.
You need to test those scenarios and then document them.
You document `REST endpoints` so users can use them to achieve various goals.
You also need to make sure that documented scenarios work as advertised.

To automate the process, let's capture executed scenarios and use them inside your documentation.
To automate the process, capture executed scenarios and use them inside your documentation.

# Capturing Test Artifacts

To capture artifacts use `http.doc.capture`:
To capture `REST` artifacts use `http.doc.capture`:

:include-file: scenarios/rest/simplePost.groovy {title: "test.groovy", commentsType: "inline"}

@@ -0,0 +1,24 @@
# Scenarios

To document how to use a User Interface we often take screenshots and annotate them.
At the same time we need to make sure that documented scenario works as advertised.

With UI testing we can validate scenarios and at the same time capture screenshots with automatically placed annotations.

# Capturing Screenshots With Annotations

To capture screenshots use `browser.doc[.withAnnotations].capture`:

:include-file: scenarios/ui/docCapture.groovy {title: "docCapture"}

The result of the `capture` command is two files: actual screenshot and `annotations.json`.

:include-file: doc-artifacts/ui/search.json {title: "search.json"}

[Webtau](https://github.com/twosigma/webtau) documentation site is generated using [Znai](https://github.com/twosigma/znai).
[Znai](https://github.com/twosigma/znai) has `include-image` plugin that supports annotations format generated by `capture` command.

:include-image: doc-artifacts/ui/search.png {fit: true, annotationsPath: "doc-artifacts/ui/search.json"}

:include-image: doc-artifacts/ui/search.png {annotationsPath: "doc-artifacts/ui/search.json"}

@@ -22,6 +22,7 @@ UI
page-object
forms
asynchronous-page
documentation
advanced-configuration
local-storage
navigation
@@ -6,7 +6,8 @@ class SearchPage {
def welcomeMessage = $('#welcome')
def searchMessage = $('#message')
def box = $('#search-box')
def numberOfResults = $('#results .result').count
def results = $('#results .result')
def numberOfResults = results.count

def submit(query) {
browser.open("/search")
@@ -0,0 +1,12 @@
package scenarios.ui

import static com.twosigma.webtau.WebTauGroovyDsl.*
import static pages.Pages.*

scenario('search and capture') {
search.submit("search this")

browser.doc.withAnnotations(
browser.doc.badge(search.box),
browser.doc.badge(search.results)).capture('search')
}
@@ -70,7 +70,9 @@ class WebTauEndToEndTestRunner implements StepReporter, StandaloneTestListener {
}

try {
def args = ['--workingDir=examples', '--config=' + configFileName, '--reportPath=' + reportPath]
def args = ['--workingDir=examples', '--config=' + configFileName,
'--reportPath=' + reportPath,
'--docPath=doc-artifacts/ui']
args.addAll(Arrays.asList(additionalArgs))
args.add(testPath.toString())

@@ -243,6 +243,11 @@ class WebTauUiFeaturesTest {
runCli('flickingElement.groovy', 'webtau.cfg')
}

@Test
void "documentation capture"() {
runCli('docCapture.groovy', 'webtau.cfg')
}

private static void extractHtmlSnippets(String extractedPath, String resourceName, Map<String, String> cssToOutputFile) {
def artifactsRoot = Paths.get(extractedPath)

@@ -15,6 +15,28 @@
-->

<html>
<head>
<style>
body {
margin: 24px;
}
#search-box {
margin-bottom: 16px;
}
.result {
margin: 4px;
padding: 8px;
border: 1px solid #ddd;
border-radius: 4px;
}
#message {
color: #888;
}
</style>
</head>
<body>
<input id="search-box" onchange="handleChange(this)"/>
<div id="welcome">welcome to super search</div>
@@ -0,0 +1,10 @@
{
"scenarioDetails" : [ {
"scenario" : "search and capture",
"shortContainerId" : "docCapture.groovy",
"stepsSummary" : {
"numberOfSuccessful" : 5
}
} ],
"exitCode" : 0
}

0 comments on commit 366f7fe

Please sign in to comment.
You can’t perform that action at this time.