# Introducing Exemplar for Automated Samples Testing

DevFeed: [Introducing Exemplar for Automated Samples Testing](<https://devfeed.tech/articles/introducing-exemplar-for-automated-samples-testing-24614.md>)

Original publisher: [Read original article](<https://blog.gradle.org/documentation-samples-testing-exemplar>)

Author: Eric Wendelin

Published: 2018-10-09T04:00:00Z

Content type: article

Language: en

Sources: [The Gradle Blog](<https://devfeed.tech/sources/the-gradle-blog.md>)

Topics: [Testing](<https://devfeed.tech/topics/testing.md>), [Documentation](<https://devfeed.tech/topics/documentation.md>), [Integration testing](<https://devfeed.tech/topics/integration-testing.md>), [Gradle](<https://devfeed.tech/topics/gradle.md>), [Command-line interface](<https://devfeed.tech/topics/cli.md>), [Logging](<https://devfeed.tech/topics/logging.md>), [cURL](<https://devfeed.tech/topics/curl.md>)

Tags: [command-line](<https://devfeed.tech/tags/command-line.md>), [curl](<https://devfeed.tech/tags/curl.md>), [docs](<https://devfeed.tech/tags/docs.md>), [documentation](<https://devfeed.tech/tags/documentation.md>), [github](<https://devfeed.tech/tags/github.md>), [gradle](<https://devfeed.tech/tags/gradle.md>), [integration-testing](<https://devfeed.tech/tags/integration-testing.md>), [logging](<https://devfeed.tech/tags/logging.md>), [testing](<https://devfeed.tech/tags/testing.md>)

## AI overview

This article introduces Exemplar, a library for automated testing of documentation samples and integration-test examples. It supports sample discovery, output normalization, flexible verification, command-line execution, embedded samples in structured documents, and configuration through a JUnit test runner or APIs. Gradle uses it to verify examples in documentation and guides while reducing integration-test boilerplate.

## Source excerpt

This post introduces a new library called Exemplar. The goal of Exemplar is to ensure that users get outputs that you expect them to see. It handles sample discovery, normalization (semantically equivalent results, perhaps from different environments), and flexible output verification. It invokes any command-line tool in the environment to be invoked. You can also invoke curl, for example, to verify service API responses. Gradle uses this library to verify examples in docs and guides, and remove boilerplate from integration tests. Exemplar can be configured using a JUnit test runner (recommended) or using its APIs. See examples below and in the Exemplar GitHub repo. Use cases for Exemplar It's important that documentation samples are accurate. Imagine the frustration, trying to learn something new and having the examples fail to work. We think Exemplar works best as a documentation checking mechanism. It is not meant to substitute other forms of integration testing however. Exemplar is unique because it allows discovery of samples embedded in structured documents, as well as OutputNormalizers (bundled and custom ones), conveniences for using sample projects in "more traditional" integration tests (via @UsesSample("path/to/sample")), and allows samples to be programmatically modified (for extra environment setup, perhaps) before execution (SampleModifier). Exemplar is focused on logging and exit code outputs, and verifying other side effects is cumbersome (checking created files may require extra commands). Furthermore, although Exemplar can be used for any tool, it only has APIs for JVM projects. Sample project testing primer The sample-discovery library in Exemplar will consider any directory containing a *.sample.conf file under the samples root as a sample project. A sample config file is written in HOCON and tells sample-check how to run the sample project. It can be simple: executable: echo args: "Hello World" ... or more complex, with multiple steps: commands: [