<commit_before><!--
GENERATED FILE - DO NOT EDIT
This file was generated by [MarkdownSnippets](https://github.com/SimonCropp/MarkdownSnippets).
Source File: /README.source.md
To change this file edit the source file and then run MarkdownSnippets.
-->

[![Build Status](https://github.com/approvals/ApprovalTests.java/workflows/build/badge.svg?branch=master)](https://github.com/approvals/ApprovalTests.java/actions?query=build%3Amaster)

<!-- toc -->
## Contents

  * [What can it be used for?](#what-can-it-be-used-for)
  * [Documentation](#documentation)
  * [Getting started](#getting-started)
  * [How to get it](#how-to-get-it)
  * [Podcasts](#podcasts)
  * [Examples](#examples)
  * [Approved File Artifacts](#approved-file-artifacts)
  * [More Info](#more-info)
  * [LICENSE](#license)
  * [Developer notes](#developer-notes)<!-- endtoc -->

# ApprovalTests.Java

Capturing Human Intelligence - ApprovalTests is an open source assertion/verification library to aid unit testing.

It is compatible with JUnit 3, 4 & 5 and TestNG.

The jars can be used from JDK 1.7 on up until JDK 14.

## What can it be used for?

Approval Tests can be used for verifying objects that require more than a simple assert. They also come prepackaged with utilities for some common java scenarios including


- HashMaps & Collections
- Long Strings
- Log Files
- JPanels
- Xml
- Html
- Json
- Getting *Legacy Code* under tests

## Documentation
- [ApprovalTests](/approvaltests/docs/README.md)  
- [ApprovalTests-util](/approvaltests-util/docs/README.md)

## Getting started

The best way to get started is download and open the [Starter Project](https://github.com/approvals/approvaltests.java.starterproject).  
It is a maven project and can be imported into any editor.


## How to get it
It's on Maven Central, search for 'approvaltests'. If you're using Maven,
add this to your pom file:

``` xml
<dependency>
    <groupId>com.approvaltests</groupId>
    <artifactId>approvaltests</artifactId>
    <version>8.0.0</version>
</dependency>
```

or [download the jars from maven central repository](https://repo1.maven.org/maven2/com/approvaltests/approvaltests/)

[Video Tutorials](https://www.youtube.com/playlist?list=PLFBA98F47156EFAA9&feature=view_all)
---

You can watch a bunch of short videos on getting started and [using ApprovalTests in Java](https://www.youtube.com/playlist?list=PLFBA98F47156EFAA9&feature=view_all) at youtube.

*Note*: There are a lot of videos about ApprovalTests in .Net They are equally useful for understanding the concepts despite being in a different programming language.

## Podcasts

If you prefer auditory learning, you might enjoy the following podcast (Note: Some of these talk about the .net side)

- [Cucumber Podcast](https://cucumber.io/blog/2017/01/26/approval-testing)
- [Hanselminutes](https://www.hanselminutes.com/360/approval-tests-with-llewellyn-falco)
- [Herding Code](https://www.developerfusion.com/media/122649/herding-code-117-llewellyn-falcon-on-approval-tests/)



## Examples

ApprovalTests eats it own dogfood, so the best examples are in the source code itself.

None the less,  Here's a quick look

<!-- snippet: demo -->
<a id='snippet-demo'/></a>
```java
public class SampleArrayTest
{
  @Test
  public void testList()
  {
    String[] names = {"Llewellyn", "James", "Dan", "Jason", "Katrina"};
    Arrays.sort(names);
    Approvals.verifyAll("", names);
  }
}
```
<sup><a href='/approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.java#L8-L19' title='File snippet `demo` was extracted from'>snippet source</a> | <a href='#snippet-demo' title='Navigate to start of snippet `demo`'>anchor</a></sup>
<!-- endsnippet -->

Will Produce a File `SampleTest.TestList.received.txt`
<!-- snippet: /approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.testList.approved.txt -->
<a id='snippet-/approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.testList.approved.txt'/></a>
```txt
[0] = Dan
[1] = James
[2] = Jason
[3] = Katrina
[4] = Llewellyn
```
<sup><a href='/approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.testList.approved.txt#L1-L5' title='File snippet `/approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.testList.approved.txt` was extracted from'>snippet source</a> | <a href='#snippet-/approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.testList.approved.txt' title='Navigate to start of snippet `/approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.testList.approved.txt`'>anchor</a></sup>
<!-- endsnippet -->

Simply rename this to SampleTest.testList.approved.txt and the test will now pass.

## Approved File Artifacts


The `*.approved.*` files must be checked into source your source control.
This can be an issue with git as it will change the line endings.
The suggested fix is to add
`*.approved.* binary` to your `.gitattributes`

## More Info


- [Website](https://approvaltests.org/)
- [Blog](https://blog.approvaltests.org/)
- [Getting Started Doc](https://github.com/approvals/ApprovalTests.Java/blob/master/build/resources/approval_tests/documentation/ApprovalTests%20-%20GettingStarted.md)



## LICENSE
[Apache 2.0 License](https://github.com/SignalR/SignalR/blob/master/LICENSE.md)


Questions?
---

twitter: [@LlewellynFalco](https://twitter.com/#!/llewellynfalco) or #ApprovalTests


## Developer notes

The suggested way to contribute to ApprovalTests is to [pair with Llewellyn](mailto:<EMAIL>)  
However, if you are set on forking please [read these notes](developer_notes.md)<commit_msg>Doco changes<commit_after><!--
GENERATED FILE - DO NOT EDIT
This file was generated by [MarkdownSnippets](https://github.com/SimonCropp/MarkdownSnippets).
Source File: /README.source.md
To change this file edit the source file and then run MarkdownSnippets.
-->

[![Build Status](https://github.com/approvals/ApprovalTests.java/workflows/build/badge.svg?branch=master)](https://github.com/approvals/ApprovalTests.java/actions?query=build%3Amaster)

<!-- toc -->
## Contents

  * [What can it be used for?](#what-can-it-be-used-for)
  * [Documentation](#documentation)
  * [Getting started](#getting-started)
  * [How to get it](#how-to-get-it)
  * [Podcasts](#podcasts)
  * [Examples](#examples)
  * [Approved File Artifacts](#approved-file-artifacts)
  * [More Info](#more-info)
  * [LICENSE](#license)
  * [Developer notes](#developer-notes)<!-- endtoc -->

# ApprovalTests.Java

Capturing Human Intelligence - ApprovalTests is an open source assertion/verification library to aid unit testing.

It is compatible with JUnit 3, 4 & 5 and TestNG.

The jars can be used from JDK 1.7 on up until JDK 14.

## What can it be used for?

Approval Tests can be used for verifying objects that require more than a simple assert. They also come prepackaged with utilities for some common java scenarios including


- HashMaps & Collections
- Long Strings
- Log Files
- JPanels
- Xml
- Html
- Json
- Getting *Legacy Code* under tests

## Documentation
- [ApprovalTests](/approvaltests/docs/README.md)  
- [ApprovalTests-util](/approvaltests-util/docs/README.md)

## Getting started

The best way to get started is download and open the [Starter Project](https://github.com/approvals/approvaltests.java.starterproject).  
It is a maven project and can be imported into any editor.


## How to get it
It's on Maven Central, search for 'approvaltests'. If you're using Maven,
add this to your pom file:

``` xml
<dependency>
    <groupId>com.approvaltests</groupId>
    <artifactId>approvaltests</artifactId>
    <version>8.0.0</version>
</dependency>
```

or [download the jars from maven central repository](https://repo1.maven.org/maven2/com/approvaltests/approvaltests/)

[Video Tutorials](https://www.youtube.com/playlist?list=PLFBA98F47156EFAA9&feature=view_all)
---

You can watch a bunch of short videos on getting started and [using ApprovalTests in Java](https://www.youtube.com/playlist?list=PLFBA98F47156EFAA9&feature=view_all) at youtube.

*Note*: There are a lot of videos about ApprovalTests in .Net They are equally useful for understanding the concepts despite being in a different programming language.

## Podcasts

If you prefer auditory learning, you might enjoy the following podcast (Note: Some of these talk about the .net side)

- [Cucumber Podcast](https://cucumber.io/blog/2017/01/26/approval-testing)
- [Hanselminutes](https://www.hanselminutes.com/360/approval-tests-with-llewellyn-falco)
- [Herding Code](https://www.developerfusion.com/media/122649/herding-code-117-llewellyn-falcon-on-approval-tests/)



## Examples

ApprovalTests eats it own dogfood, so the best examples are in the source code itself.

None the less,  Here's a quick look

<!-- snippet: demo -->
<a id='snippet-demo'/></a>
```java
public class SampleArrayTest
{
  @Test
  public void testList()
  {
    String[] names = {"Llewellyn", "James", "Dan", "Jason", "Katrina"};
    Arrays.sort(names);
    Approvals.verifyAll("", names);
  }
}
```
<sup><a href='/approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.java#L8-L19' title='File snippet `demo` was extracted from'>snippet source</a> | <a href='#snippet-demo' title='Navigate to start of snippet `demo`'>anchor</a></sup>
<!-- endsnippet -->

Will Produce a File `SampleTest.TestList.received.txt`
<!-- snippet: /approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.testList.approved.txt -->
<a id='snippet-/approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.testList.approved.txt'/></a>
```txt
[0] = Dan
[1] = James
[2] = Jason
[3] = Katrina
[4] = Llewellyn
```
<sup><a href='/approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.testList.approved.txt#L1-L5' title='File snippet `/approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.testList.approved.txt` was extracted from'>snippet source</a> | <a href='#snippet-/approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.testList.approved.txt' title='Navigate to start of snippet `/approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.testList.approved.txt`'>anchor</a></sup>
<!-- endsnippet -->

Simply rename this to SampleTest.testList.approved.txt and the test will now pass.

## Approved File Artifacts


The `*.approved.*` files must be checked into source your source control.
This can be an issue with git as it will change the line endings.
The suggested fix is to add
`*.approved.* binary` to your `.gitattributes`

## More Info


- [Website](https://approvaltests.org/)
- [Blog](https://blog.approvaltests.org/)
- [Getting Started Doc](https://github.com/approvals/ApprovalTests.Java/blob/master/build/resources/approval_tests/documentation/ApprovalTests%20-%20GettingStarted.md)



## LICENSE
[Apache 2.0 License](https://github.com/SignalR/SignalR/blob/master/LICENSE.md)


Questions?
---

twitter: [@LlewellynFalco](https://twitter.com/#!/llewellynfalco) or #ApprovalTests


## Developer notes  

The suggested way to contribute to ApprovalTests is to [pair with Llewellyn](mailto:<EMAIL>)  
However, if you are set on forking please [read these notes](developer_notes.md)
{'fraction_non_alphanumeric': 0.13543055185283925, 'fraction_numerical': 0.0115524748955834, 'mean_word_length': 4.701114488348531, 'pattern_counts': {'":': 0, '<': 67, '<?xml version=': 0, '>': 67, 'https://': 30, 'lorem ipsum': 0, 'www.': 8, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '389030', 'n_tokens_mistral': 3876, 'n_tokens_neox': 3568, 'n_words': 940}