<commit_before># EgTest
Write annotations to create unit tests and documentation in Java and other JVM languages

###### Definition
e.g., _exempli gratia:_ for the sake of an example.

Not to be confused with i.e., _id et_: it is. (A definition or exhaustive list.)

##Why

Because unit tests should be the easiest way to test.

Because code, tests, and documentation belong together.

## What it's for (and not for)
EgTest annotations provide **testable documentation in the source code**.

EgTest annotations automatically show up in Javadoc, so you can have confidence that the examples work as documented.

By removing the excuses for writing tests, you may find yourself writing tests for one-off code or exploratory code. 
Rather than testing in a REPL, it is easier to write a permanent unit test. Even simple one-line functions are worth a 
unit test when it's this quick and easy!

EgTest is **not** an excuse to avoid writing complete unit tests! In some cases, especially
with functional programming, you might be able to avoid writing a test file. EgTest should encourage you to 
break your complex code into small, simple, easily tested functions. With EgTest, you don't need to write several lines
of unit test boilerplate for a one-line test-- but you still need that boilerplate for more complicated tests.

Because EgTest encourages you to think small, **private methods and regular expressions are fair game.** If you break a 
big method into several small private pieces, you can test each private piece individually.

EgTest provides the annotations, not the code generators for the unit tests. The annotations are independent of any
particular test or build tool.

### Examples

See [The example source code](https://github.com/dleppik/EgTest/tree/master/annotation-examples/src/main/java/com/vocalabs/egtest/example).

```Java
import java.util.regex.Pattern;
import com.vocalabs.egtest.annotation.*;

public class ExampleForReadme {

    /**
     * Regular expression to match address portions of typical real-world email addresses.
     * It does NOT attempt to match all valid RFC 2822 addresses.
     */
    @EgMatches("<EMAIL>")
    @EgMatches("<EMAIL>")

    @EgNoMatch("dleppik")
    @EgNoMatch("<EMAIL>")
    @EgNoMatch("<NAME> <<EMAIL>>")
    public static final Pattern
            SIMPLE_EMAIL_RE = Pattern.compile("^[\\w+.\\-=&|/?!#$*]+@[\\w.\\-]+\\.[\\w]+$");

    @Eg(given = {"1", "2"}, returns = "3")
    @Eg(given = {"1", "Integer.MIN_VALUE"}, returns = "Integer.MAX_VALUE")
    public static int add(int a, int b) {
        return a + b;
    }

    @EgException(value = {"null"}, willThrow = NullPointerException.class)
    public static String methodWhichCannotHandleNulls(Object thing1) {
        return thing1.toString();
    }

    @Eg(given = {"\"World\""}, returns = "\"Hello, World!\"")
    public static String greet(String target) {
        return "Hello, "+target+"!";
    }

    @EgException({"null", "\"hello\""})
    @EgException({"\"hello\"", "null"})
    public static String anotherMethodWhichCannotHandleNulls(Object thing1, Object thing2) {
        return thing1.toString() + thing2.toString();
    }
}
```

##Generating Unit Tests

**A JUnit 4 test generator is in progress, with Gradle integration as the initial target.**

A properly formed EgTest unit test is in the same package as the class being tested, but it should have a name which
does not conflict with typical unit test class names. That way the same test suite can simultaneously run EgTests and 
hand-written tests. For example, a class `org.example.MyExample.class` might yield a test class named 
`org.example.MyExample$EgTest.class`.

Method parameters and return types should be constants, but they can be of any type import from anywhere, so long as 
it is visible to the test. Thus `java.time.Instant.EPOCH`, with the full package name, may be used.

While there's no reason we can't support any JVM language, the assertions are written in Java.
<commit_msg>Fixed README URL to source code.<commit_after># EgTest
Write annotations to create unit tests and documentation in Java and other JVM languages

###### Definition
e.g., _exempli gratia:_ for the sake of an example.

Not to be confused with i.e., _id et_: it is. (A definition or exhaustive list.)

##Why

Because unit tests should be the easiest way to test.

Because code, tests, and documentation belong together.

## What it's for (and not for)
EgTest annotations provide **testable documentation in the source code**.

EgTest annotations automatically show up in Javadoc, so you can have confidence that the examples work as documented.

By removing the excuses for writing tests, you may find yourself writing tests for one-off code or exploratory code. 
Rather than testing in a REPL, it is easier to write a permanent unit test. Even simple one-line functions are worth a 
unit test when it's this quick and easy!

EgTest is **not** an excuse to avoid writing complete unit tests! In some cases, especially
with functional programming, you might be able to avoid writing a test file. EgTest should encourage you to 
break your complex code into small, simple, easily tested functions. With EgTest, you don't need to write several lines
of unit test boilerplate for a one-line test-- but you still need that boilerplate for more complicated tests.

Because EgTest encourages you to think small, **private methods and regular expressions are fair game.** If you break a 
big method into several small private pieces, you can test each private piece individually.

EgTest provides the annotations, not the code generators for the unit tests. The annotations are independent of any
particular test or build tool.

### Examples

See [The example source code](https://github.com/dleppik/EgTest/tree/master/annotation-example/src/main/java/com/vocalabs/egtest/example).

```Java
import java.util.regex.Pattern;
import com.vocalabs.egtest.annotation.*;

public class ExampleForReadme {

    /**
     * Regular expression to match address portions of typical real-world email addresses.
     * It does NOT attempt to match all valid RFC 2822 addresses.
     */
    @EgMatches("<EMAIL>")
    @EgMatches("<EMAIL>")

    @EgNoMatch("dleppik")
    @EgNoMatch("<EMAIL>")
    @EgNoMatch("<NAME> <<EMAIL>>")
    public static final Pattern
            SIMPLE_EMAIL_RE = Pattern.compile("^[\\w+.\\-=&|/?!#$*]+@[\\w.\\-]+\\.[\\w]+$");

    @Eg(given = {"1", "2"}, returns = "3")
    @Eg(given = {"1", "Integer.MIN_VALUE"}, returns = "Integer.MAX_VALUE")
    public static int add(int a, int b) {
        return a + b;
    }

    @EgException(value = {"null"}, willThrow = NullPointerException.class)
    public static String methodWhichCannotHandleNulls(Object thing1) {
        return thing1.toString();
    }

    @Eg(given = {"\"World\""}, returns = "\"Hello, World!\"")
    public static String greet(String target) {
        return "Hello, "+target+"!";
    }

    @EgException({"null", "\"hello\""})
    @EgException({"\"hello\"", "null"})
    public static String anotherMethodWhichCannotHandleNulls(Object thing1, Object thing2) {
        return thing1.toString() + thing2.toString();
    }
}
```

##Generating Unit Tests

**A JUnit 4 test generator is in progress, with Gradle integration as the initial target.**

A properly formed EgTest unit test is in the same package as the class being tested, but it should have a name which
does not conflict with typical unit test class names. That way the same test suite can simultaneously run EgTests and 
hand-written tests. For example, a class `org.example.MyExample.class` might yield a test class named 
`org.example.MyExample$EgTest.class`.

Method parameters and return types should be constants, but they can be of any type import from anywhere, so long as 
it is visible to the test. Thus `java.time.Instant.EPOCH`, with the full package name, may be used.

While there's no reason we can't support any JVM language, the assertions are written in Java.

{'fraction_non_alphanumeric': 0.09697197197197197, 'fraction_numerical': 0.0037537537537537537, 'mean_word_length': 3.912722802704364, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5841876', 'n_tokens_mistral': 2260, 'n_tokens_neox': 2162, 'n_words': 1007}