Dedicated Hamcrest Adapter module, closes #109

Provide a separate module containing adapters between Hamcrest and
Confidence. This deprecates the `Hamcrest` `Quality` in confidence-core.

README.md

@@ -153,11 +153,23 @@ General note on matching arrays: arrays (including ones of primitive types) can
 
 *works with arrays of primitive types
 
-Confidence provides an adapter to use Hamcrest `Matcher`s in Confidence assertions.
-The adapter `Quality` is called `hamcrest` and you just pass a `Matcher` to it like in:
+## confidence-hamcrest
+
+Confidence provides adapters to use Hamcrest `Matcher`s in Confidence assertions and Confidence `Quality`s where
+Hamcrest `Matchers` are required (for instance when working with rest-assured, mockito or awaitlity).
+
+You can use Hamcrest `Matcher`s with Confidence by including the `confidence-hamcrest` artifact and adapting it with
+the `matches` adapter `Quality`.
+
+```java
+assertThat(List.of(1,2,5,10,11), matches(hasItem(2)));
+```
+
+The same module also provides a Hamcrest `Matcher` called `qualifiesAs` to use Confidence `Quality`s in a test
+that requires a `Matcher`:
 
 ```java
-assertThat(List.of(1,2,5,10,11), hamcrest(hasItem(2)));
+response.then().body("id", qualifiesAs(jsonStringOf(object(with("foo", equalTo("bar"))))))
 ```
 
 # JUnit Confidence TestEngine

confidence-core/src/main/java/org/saynotobugs/confidence/quality/compat/Hamcrest.java

@@ -27,7 +27,10 @@
 import org.saynotobugs.confidence.assessment.Pass;
 import org.saynotobugs.confidence.description.Text;
 
-
+/**
+ * @deprecated in favour of the Matches Quality in the confidence-hamcrest module
+ */
+@Deprecated
 @StaticFactories(value = "Core", packageName = "org.saynotobugs.confidence.quality")
 public final class Hamcrest<T> implements Quality<T>
 {

confidence-hamcrest/build.gradle

@@ -0,0 +1,27 @@
+plugins {
+    id 'java-library'
+}
+apply from: '../jacoco.gradle'
+apply from: '../publish.gradle'
+
+sourceCompatibility = JavaVersion.VERSION_1_8
+targetCompatibility = JavaVersion.VERSION_1_8
+
+dependencies {
+    compileOnly libs.eclipse.jdt.anntation
+    compileOnly libs.srcless.annotations
+    annotationProcessor libs.bundles.srcless.processors
+
+    api libs.hamcrest
+    api project(':confidence-core')
+    implementation libs.jems2
+
+    testImplementation project(':confidence-test')
+    testImplementation libs.jems2.testing
+    testImplementation libs.junit.jupiter.api
+    testRuntimeOnly libs.junit.jupiter.engine
+}
+
+test {
+    useJUnitPlatform()
+}

confidence-hamcrest/src/main/java/org/saynotobugs/confidence/hamcrest/matcher/QualifiesAs.java

@@ -0,0 +1,59 @@
+/*
+ * Copyright 2024 dmfs GmbH
+ *
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package org.saynotobugs.confidence.hamcrest.matcher;
+
+import org.dmfs.srcless.annotations.staticfactory.StaticFactories;
+import org.hamcrest.Description;
+import org.hamcrest.TypeSafeDiagnosingMatcher;
+import org.saynotobugs.confidence.Assessment;
+import org.saynotobugs.confidence.Quality;
+import org.saynotobugs.confidence.Scribe;
+import org.saynotobugs.confidence.scribe.StringBuilderScribe;
+
+/**
+ * A Hamcrest {@link org.hamcrest.Matcher} of {@code T} that delegates to a {@link Quality}.
+ */
+@StaticFactories(value = "Hamcrest", packageName = "org.saynotobugs.confidence.hamcrest")
+public final class QualifiesAs<T> extends TypeSafeDiagnosingMatcher<T>
+{
+    private final Quality<? super T> mQuality;
+
+    public QualifiesAs(Quality<? super T> quality)
+    {
+        mQuality = quality;
+    }
+
+    @Override
+    protected boolean matchesSafely(T item, Description mismatchDescription)
+    {
+        Scribe scribe = new StringBuilderScribe("");
+        Assessment assessment = mQuality.assessmentOf(item);
+        assessment.description().describeTo(scribe);
+        mismatchDescription.appendText(scribe.toString());
+        return assessment.isSuccess();
+    }
+
+    @Override
+    public void describeTo(Description description)
+    {
+        Scribe scribe = new StringBuilderScribe("");
+        mQuality.description().describeTo(scribe);
+        description.appendText(scribe.toString());
+    }
+}

confidence-hamcrest/src/main/java/org/saynotobugs/confidence/hamcrest/quality/Matches.java

@@ -0,0 +1,67 @@
+/*
+ * Copyright 2024 dmfs GmbH
+ *
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package org.saynotobugs.confidence.hamcrest.quality;
+
+import org.dmfs.srcless.annotations.staticfactory.StaticFactories;
+import org.hamcrest.StringDescription;
+import org.saynotobugs.confidence.Assessment;
+import org.saynotobugs.confidence.Description;
+import org.saynotobugs.confidence.Quality;
+import org.saynotobugs.confidence.assessment.Fail;
+import org.saynotobugs.confidence.assessment.Pass;
+import org.saynotobugs.confidence.description.Text;
+
+
+/**
+ * A {@link Quality} of {@code T} that delegates to a Hamcrest {@link org.hamcrest.Matcher}.
+ */
+@StaticFactories(value = "Hamcrest", packageName = "org.saynotobugs.confidence.hamcrest")
+public final class Matches<T> implements Quality<T>
+{
+    private final org.hamcrest.Matcher<? super T> mDelegate;
+
+
+    public Matches(org.hamcrest.Matcher<? super T> delegate)
+    {
+        mDelegate = delegate;
+    }
+
+
+    @Override
+    public Assessment assessmentOf(T candidate)
+    {
+        if (mDelegate.matches(candidate))
+        {
+            return new Pass();
+        }
+        org.hamcrest.Description mismatch = new StringDescription();
+        mDelegate.describeMismatch(candidate, mismatch);
+        return new Fail(new Text(mismatch.toString()));
+    }
+
+
+    @Override
+    public Description description()
+    {
+        org.hamcrest.Description expected = new StringDescription();
+        mDelegate.describeTo(expected);
+        return new Text(expected.toString());
+    }
+
+}

confidence-hamcrest/src/test/java/org/saynotobugs/confidence/hamcrest/matcher/QualifiesAsTest.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2024 dmfs GmbH
+ *
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package org.saynotobugs.confidence.hamcrest.matcher;
+
+import org.junit.jupiter.api.Test;
+import org.saynotobugs.confidence.quality.object.EqualTo;
+
+import static org.dmfs.jems2.hamcrest.matchers.matcher.MatcherMatcher.*;
+import static org.hamcrest.CoreMatchers.allOf;
+import static org.hamcrest.MatcherAssert.assertThat;
+
+class QualifiesAsTest
+{
+    @Test
+    void test()
+    {
+        assertThat(new QualifiesAs<>(new EqualTo<>("123")),
+            allOf(
+                matches("123"),
+                mismatches("12", "\"12\""),
+                describesAs("\"123\"")
+            ));
+    }
+
+}

confidence-hamcrest/src/test/java/org/saynotobugs/confidence/hamcrest/quality/MatchesTest.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2024 dmfs GmbH
+ *
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package org.saynotobugs.confidence.hamcrest.quality;
+
+import org.hamcrest.Matchers;
+import org.junit.jupiter.api.Test;
+import org.saynotobugs.confidence.quality.composite.AllOf;
+import org.saynotobugs.confidence.test.quality.Fails;
+import org.saynotobugs.confidence.test.quality.HasDescription;
+import org.saynotobugs.confidence.test.quality.Passes;
+
+import static org.saynotobugs.confidence.Assertion.assertThat;
+
+class MatchesTest
+{
+    @Test
+    void test()
+    {
+        assertThat(new Matches<>(Matchers.equalTo(123)),
+            new AllOf<>(
+                new Passes<>(123),
+                new Fails<>(12, "was <12>"),
+                new HasDescription("<123>")
+            ));
+    }
+}

settings.gradle

@@ -1,5 +1,6 @@
 rootProject.name = 'confidence'
 include 'confidence-core'
+include 'confidence-hamcrest'
 include 'confidence-asm'
 include 'confidence-json'
 include 'confidence-mockito4'