1 files changed, 82 insertions, 0 deletions
diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..2ae6bb7
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,82 @@
+Property-based testing within the [JUnit](http://junit.org/) test framework.
+
+Using `java-check` you can write `@Property` tests. These tests will
+have any parameters randomly generated (using generators marked with
+`@DataSource`). This allows you to write tests which assert general
+properties rather than specific cases.
+
+As an example, let's test the `Collections.reverse` function. One
+simple property of `Collections.reverse` is that reversing a list
+twice results in the original list (ie. `reverse(reverse(x)) = x)`).
+
+Let's write a property for this:
+
+    @RunWith(Properties.class)
+    public class ExampleTest {
+        @DataSource
+        public static Generator<List<Integer>> integerList = listOf(integer());
+    
+        @Property
+        public void reverseIsInvolution(List<Integer> list) {
+            List<Integer> reversed = new ArrayList<>(list);
+            Collections.reverse(reversed);
+    //        reverse(reversed);
+    
+            assertEquals(list, reversed);
+        }
+    }
+
+Oh no! The test above is incorrect! I've accidentally commented out
+the second `reverse(reversed)` line, which means I'm trying to test
+whether `reverse(x) = x`. That means this test should fail:
+
+    au.id.zancanaro.javacheck.junit.PropertyError: reverseIsInvolution([0, -1])
+            Seed: 1433134487916
+    
+    Expected :[0, -1]
+    Actual   :[-1, 0]
+      <Click to see difference>
+    
+            at au.id.zancanaro.javacheck.junit.Properties$GenerativeTester.evaluate(Properties.java:217)
+            ...  (extra stack trace entries have been removed for clarity)
+    Caused by: java.lang.AssertionError: expected:<[0, -1]> but was:<[-1, 0]>
+            at org.junit.Assert.fail(Assert.java:88)
+            ...  (extra stack trace entries have been removed for clarity)
+
+The test has failed, and it's managed to reduce the failing case to
+the smallest possible failing case: a two-element list with both
+elements being different.
+
+It's easy for us to fix the test, and here is the complete file for
+`ExampleTest.java`:
+
+    package com.example;
+    
+    import au.id.zancanaro.javacheck.Generator;
+    import au.id.zancanaro.javacheck.annotations.DataSource;
+    import au.id.zancanaro.javacheck.annotations.Property;
+    import au.id.zancanaro.javacheck.junit.Properties;
+    import org.junit.runner.RunWith;
+    
+    import java.util.ArrayList;
+    import java.util.List;
+    
+    import static au.id.zancanaro.javacheck.Generators.integer;
+    import static au.id.zancanaro.javacheck.Generators.listOf;
+    import static java.util.Collections.reverse;
+    import static org.junit.Assert.assertEquals;
+    
+    @RunWith(Properties.class)
+    public class ExampleTest {
+        @DataSource
+        public static Generator<List<Integer>> integerList = listOf(integer());
+    
+        @Property
+        public void reverseIsInvolution(List<Integer> list) {
+            List<Integer> reversed = new ArrayList<>(list);
+            reverse(reversed);
+            reverse(reversed);
+    
+            assertEquals(list, reversed);
+        }
+    }