From 8342aedff4da5bd6e90d476cd02c51ca6d39da16 Mon Sep 17 00:00:00 2001
From: Michael Hoennig <michael@hoennig.de>
Date: Mon, 4 Nov 2024 17:55:04 +0100
Subject: [PATCH] improve readme and cleanup

---
 .../{contact => }/PathAssertion.java          |  4 +--
 .../hsadminng/hs/office/scenarios/README.md   | 25 ++++++++++++++++++-
 .../hs/office/scenarios/UseCase.java          |  1 -
 3 files changed, 25 insertions(+), 5 deletions(-)
 rename src/test/java/net/hostsharing/hsadminng/hs/office/scenarios/{contact => }/PathAssertion.java (77%)

diff --git a/src/test/java/net/hostsharing/hsadminng/hs/office/scenarios/contact/PathAssertion.java b/src/test/java/net/hostsharing/hsadminng/hs/office/scenarios/PathAssertion.java
similarity index 77%
rename from src/test/java/net/hostsharing/hsadminng/hs/office/scenarios/contact/PathAssertion.java
rename to src/test/java/net/hostsharing/hsadminng/hs/office/scenarios/PathAssertion.java
index a6925fde..ffd9df8e 100644
--- a/src/test/java/net/hostsharing/hsadminng/hs/office/scenarios/contact/PathAssertion.java
+++ b/src/test/java/net/hostsharing/hsadminng/hs/office/scenarios/PathAssertion.java
@@ -1,7 +1,5 @@
-package net.hostsharing.hsadminng.hs.office.scenarios.contact;
+package net.hostsharing.hsadminng.hs.office.scenarios;
 
-import net.hostsharing.hsadminng.hs.office.scenarios.ScenarioTest;
-import net.hostsharing.hsadminng.hs.office.scenarios.UseCase;
 import net.hostsharing.hsadminng.hs.office.scenarios.UseCase.HttpResponse;
 
 import java.util.function.Consumer;
diff --git a/src/test/java/net/hostsharing/hsadminng/hs/office/scenarios/README.md b/src/test/java/net/hostsharing/hsadminng/hs/office/scenarios/README.md
index 36e7c3c8..037b151a 100644
--- a/src/test/java/net/hostsharing/hsadminng/hs/office/scenarios/README.md
+++ b/src/test/java/net/hostsharing/hsadminng/hs/office/scenarios/README.md
@@ -63,4 +63,27 @@ Here, use-cases can be re-used, usually with different data.
 
 ### The Use-Case Itself
 
-The use-case
+The use-case is implemented by the `run()`-method which contains HTTP-calls.
+
+Each HTTP-call is wrapped into either `obtain(...)` to keep the result in a placeholder variable,
+the variable name is also used as a title.
+Or it's wrapped into a `withTitle(...)` to assign a title.
+
+The HTTP-call is followed by some assertions, e.g. the HTTP status and JSON-path-expression-matchers.
+
+Use `${...}` for placeholders which need to be replaced with JSON quotes
+(e.g. strings are quoted, numbers are not),
+`%{...}` for placeholders which need to be rendered raw
+and `&{...}` for placeholders which need to get URI-encoded.
+
+Properties with null-values are removed from the JSON.
+If you need to keep a null-value, e.g. to delete a property,
+use `NULL` (all caps).
+
+
+### The Use-Case Verification
+
+The verification-step is implemented by the `verify()`-method which usually contains a HTTP-HTTP-call.
+
+It can also contain a JSON-path verification to check if a certain value is in the result.
+
diff --git a/src/test/java/net/hostsharing/hsadminng/hs/office/scenarios/UseCase.java b/src/test/java/net/hostsharing/hsadminng/hs/office/scenarios/UseCase.java
index acb1d33f..2788c21c 100644
--- a/src/test/java/net/hostsharing/hsadminng/hs/office/scenarios/UseCase.java
+++ b/src/test/java/net/hostsharing/hsadminng/hs/office/scenarios/UseCase.java
@@ -6,7 +6,6 @@ import com.jayway.jsonpath.JsonPath;
 import io.restassured.http.ContentType;
 import lombok.Getter;
 import lombok.SneakyThrows;
-import net.hostsharing.hsadminng.hs.office.scenarios.contact.PathAssertion;
 import net.hostsharing.hsadminng.reflection.AnnotationFinder;
 import org.apache.commons.collections4.map.LinkedMap;
 import org.assertj.core.api.OptionalAssert;