summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorCarlo Zancanaro <carlo@zancanaro.id.au>2015-06-01 15:04:45 +1000
committerCarlo Zancanaro <carlo@zancanaro.id.au>2015-06-01 15:04:45 +1000
commitdaeae9a1d184d733d278857079c09af19add80c6 (patch)
treed2aa65cd4f0b31dca6ad8bd0ae3b74a7f8d19bff
parent8d9210e4cbf9c3d47917f53b1e4e5732acaf6688 (diff)
Apparently bitbucket doesn't like org mode at all
-rw-r--r--readme.md82
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);
+ }
+ }