From f7d9f40d535987a11766fdc57df3d6463b6bbe65 Mon Sep 17 00:00:00 2001 From: Marc Philipp Date: Sat, 19 Mar 2016 18:03:31 +0100 Subject: [PATCH] Document support for interface default methods in the User Guide Fixes #192. --- .../src/docs/asciidoc/writing-tests.adoc | 32 +++++++++++++ .../defaultmethods/ComparableContract.java | 44 ++++++++++++++++++ .../defaultmethods/EqualsContract.java | 45 +++++++++++++++++++ .../example/defaultmethods/StringTests.java | 32 +++++++++++++ .../java/example/defaultmethods/Testable.java | 19 ++++++++ 5 files changed, 172 insertions(+) create mode 100644 documentation/src/test/java/example/defaultmethods/ComparableContract.java create mode 100644 documentation/src/test/java/example/defaultmethods/EqualsContract.java create mode 100644 documentation/src/test/java/example/defaultmethods/StringTests.java create mode 100644 documentation/src/test/java/example/defaultmethods/Testable.java diff --git a/documentation/src/docs/asciidoc/writing-tests.adoc b/documentation/src/docs/asciidoc/writing-tests.adoc index b5c09bbfad4b..12cdb9b27b13 100644 --- a/documentation/src/docs/asciidoc/writing-tests.adoc +++ b/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. diff --git a/documentation/src/test/java/example/defaultmethods/ComparableContract.java b/documentation/src/test/java/example/defaultmethods/ComparableContract.java new file mode 100644 index 000000000000..9bbc5eb266d3 --- /dev/null +++ b/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> extends Testable { + + 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[] diff --git a/documentation/src/test/java/example/defaultmethods/EqualsContract.java b/documentation/src/test/java/example/defaultmethods/EqualsContract.java new file mode 100644 index 000000000000..83741fd86090 --- /dev/null +++ b/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 extends Testable { + + 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[] diff --git a/documentation/src/test/java/example/defaultmethods/StringTests.java b/documentation/src/test/java/example/defaultmethods/StringTests.java new file mode 100644 index 000000000000..7aeb23c2e4c9 --- /dev/null +++ b/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, EqualsContract { + + @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[] diff --git a/documentation/src/test/java/example/defaultmethods/Testable.java b/documentation/src/test/java/example/defaultmethods/Testable.java new file mode 100644 index 000000000000..f051fe46bd24 --- /dev/null +++ b/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 createValue(); + +} +// end::user_guide[]