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.

To capture screenshots use browser.doc[.withAnnotations].capture : search.submit("search this") browser.doc.withAnnotations( browser.doc.badge(search.box), browser.doc.badge(search.results)).capture('search') The result of the capture command is two files: actual screenshot and annotations.json . { "shapes" : [ { "id" : "circle9", "type" : "circle", "text" : "1", "color" : "a", "x" : 128, "y" : 41, "align" : "Center", "r" : 15 }, { "id" : "circle10", "type" : "circle", "text" : "2", "color" : "a", "x" : 494, "y" : 134, "align" : "Center", "r" : 15 } ], "pixelRatio" : 1 } https://testingisdocumenting.org/webtau Webtau documentation site is generated using https://github.com/testingisdocumenting/znai Znai. It has include-image plugin that supports annotations format generated by capture command. :include-image: doc-artifacts/search.png {fit: true, annotationsPath: "doc-artifacts/search.json"}

search.submit("search this") browser.doc.withAnnotations( browser.doc.badge(search.box), browser.doc.badge(search.results)).capture('search') browser.doc.withAnnotations( browser.doc.highlight(search.box), browser.doc.cover(search.results, "covering text")).capture('search-highlight-cover')

Use above , below , toTheLeft and toTheRight to put an annotation outside of element center. search.submit("search this") browser.doc.withAnnotations( browser.doc.badge(search.box).toTheRight(), browser.doc.badge(search.results).above()).capture('search-diff-placement') data.json.map('doc-artifacts/search-diff-placement.json'.toString()) .shapes.align.should == ['ToTheRight', 'Above']