Document support for interface default methods in the User Guide

Fixes #192.

documentation/src/docs/asciidoc/writing-tests.adoc

@@ -226,3 +226,35 @@ class MyMockitoTest {
 
 }
 ----
+
+=== Interface Default Methods
+
+JUnit 5 allows tests to be declared in interface default methods. One possible application of this feature is to write tests for interface contracts. For example, you can write tests for how implementations of `Object.equals` or `Comparable.compareTo` should behave as follows:
+
+[source,java]
+[subs="verbatim"]
+----
+include::{testDir}/example/defaultmethods/Testable.java[tags=user_guide]
+----
+
+[source,java]
+[subs="verbatim"]
+----
+include::{testDir}/example/defaultmethods/EqualsContract.java[tags=user_guide]
+----
+
+[source,java]
+[subs="verbatim"]
+----
+include::{testDir}/example/defaultmethods/ComparableContract.java[tags=user_guide]
+----
+
+In your test class you can then implement both contract interfaces thereby inheriting the corresponding tests. Of course you'll have to implement the abstract methods:
+
+[source,java]
+[subs="verbatim"]
+----
+include::{testDir}/example/defaultmethods/StringTests.java[tags=user_guide]
+----
+
+The above tests are merely meant as examples and therefore not complete.

documentation/src/test/java/example/defaultmethods/ComparableContract.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2015-2016 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v1.0 which
+ * accompanies this distribution and is available at
+ *
+ * http://www.eclipse.org/legal/epl-v10.html
+ */
+
+package example.defaultmethods;
+
+import static org.junit.gen5.api.Assertions.assertEquals;
+import static org.junit.gen5.api.Assertions.assertTrue;
+
+import org.junit.gen5.api.Test;
+
+// tag::user_guide[]
+public interface ComparableContract<T extends Comparable<T>> extends Testable<T> {
+
+	T createSmallerValue();
+
+	@Test
+	default void returnsZeroWhenComparedToItself() {
+		T value = createValue();
+		assertEquals(0, value.compareTo(value));
+	}
+
+	@Test
+	default void returnsPositiveNumberComparedToSmallerValue() {
+		T value = createValue();
+		T smallerValue = createSmallerValue();
+		assertTrue(value.compareTo(smallerValue) > 0);
+	}
+
+	@Test
+	default void returnsNegativeNumberComparedToSmallerValue() {
+		T value = createValue();
+		T smallerValue = createSmallerValue();
+		assertTrue(smallerValue.compareTo(value) < 0);
+	}
+
+}
+// end::user_guide[]

documentation/src/test/java/example/defaultmethods/EqualsContract.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2015-2016 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v1.0 which
+ * accompanies this distribution and is available at
+ *
+ * http://www.eclipse.org/legal/epl-v10.html
+ */
+
+package example.defaultmethods;
+
+import static org.junit.gen5.api.Assertions.assertEquals;
+import static org.junit.gen5.api.Assertions.assertFalse;
+import static org.junit.gen5.api.Assertions.assertNotEquals;
+
+import org.junit.gen5.api.Test;
+
+// tag::user_guide[]
+public interface EqualsContract<T> extends Testable<T> {
+
+	T createNotEqualValue();
+
+	@Test
+	default void valueEqualsItself() {
+		T value = createValue();
+		assertEquals(value, value);
+	}
+
+	@Test
+	default void valueDoesNotEqualNull() {
+		T value = createValue();
+		assertFalse(value.equals(null));
+	}
+
+	@Test
+	default void valueDoesNotEqualDifferentValue() {
+		T value = createValue();
+		T differentValue = createNotEqualValue();
+		assertNotEquals(value, differentValue);
+		assertNotEquals(differentValue, value);
+	}
+
+}
+// end::user_guide[]

documentation/src/test/java/example/defaultmethods/StringTests.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2015-2016 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v1.0 which
+ * accompanies this distribution and is available at
+ *
+ * http://www.eclipse.org/legal/epl-v10.html
+ */
+
+package example.defaultmethods;
+
+// tag::user_guide[]
+class StringTests implements ComparableContract<String>, EqualsContract<String> {
+
+	@Override
+	public String createValue() {
+		return "foo";
+	}
+
+	@Override
+	public String createSmallerValue() {
+		return "bar"; // 'b' < 'f' in "foo"
+	}
+
+	@Override
+	public String createNotEqualValue() {
+		return "baz";
+	}
+
+}
+// end::user_guide[]

documentation/src/test/java/example/defaultmethods/Testable.java

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2015-2016 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v1.0 which
+ * accompanies this distribution and is available at
+ *
+ * http://www.eclipse.org/legal/epl-v10.html
+ */
+
+package example.defaultmethods;
+
+// tag::user_guide[]
+public interface Testable<T> {
+
+	T createValue();
+
+}
+// end::user_guide[]