From 193a061b93d6b559a2588840a2f261510e030847 Mon Sep 17 00:00:00 2001
From: dreamhead <dreamhead.cn@gmail.com>
Date: Thu, 12 Oct 2023 22:04:45 +0800
Subject: [PATCH] documented junit 5 extension

---
 moco-doc/ReleaseNotes.md |  5 +++
 moco-doc/junit5.md       | 76 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 moco-doc/junit5.md

diff --git a/moco-doc/ReleaseNotes.md b/moco-doc/ReleaseNotes.md
index fe25ae0e0..e2f6e5a63 100644
--- a/moco-doc/ReleaseNotes.md
+++ b/moco-doc/ReleaseNotes.md
@@ -1,3 +1,8 @@
+# Release
+
+## JUnit 5
+* HTTP and HTTPS with JSON configuration from file/class path
+
 # Release 1.5.0(1-Sep-2023)
 ## APIs
 * `req.client.port` is supported in template
diff --git a/moco-doc/junit5.md b/moco-doc/junit5.md
new file mode 100644
index 000000000..6bfc9e836
--- /dev/null
+++ b/moco-doc/junit5.md
@@ -0,0 +1,76 @@
+# JUnit 5 Integration
+**@Since will be at next release**
+
+Moco makes use of Extension in JUnit 5 to simplify JUnit integration.
+
+@MocoExtension is required to use Moco in JUnit 5. Every test class use Moco should be annotated with @ExtendWith(MocoExtension.class).
+
+```java
+@ExtendWith(MocoExtension.class)
+class WithMocoTest {
+  ...
+}
+```
+
+With @MocoExtesion, Moco server will be started before test and stopped after test.
+
+## HTTP Server
+
+@MocoHttpServer could be used to start a HTTP server. Configuration file and port are required.
+
+```java
+@ExtendWith(MocoExtension.class)
+@MocoHttpServer(filepath = "foo/foo.json", port=12306)
+public class MocoHttpTest {
+  @Test
+  public void should_return_expected_message() throws IOException {
+    Content content = Request.Get("http://localhost:12306").execute().returnContent();
+    assertThat(content.asString(), is("foo"));
+  }  
+}
+```
+
+**filepath** is provided here, you can also use `classpath` to retrieve configuration file from classpath.
+
+```java
+@ExtendWith(MocoExtension.class)
+@MocoHttpServer(classpath = "foo.json", port=12306)
+public class MocoHttpTest {
+  ...
+}
+```
+
+## HTTPS Server
+
+Besides @MocoHttpServer, you should also use @MocoCertificate to start Moco as a HTTPS server.
+
+```java
+@ExtendWith(MocoExtension.class)
+@MocoHttpServer(filepath = "foo/foo.json", port=12306)
+@MocoCertificate(filepath = "certificate/cert.jks", keyStorePassword = "mocohttps", certPassword = "mocohttps")
+public class MocoHttpTest {
+  @Test
+  public void should_return_expected_message() throws IOException {
+    Content content = Request.Get("http://localhost:12306").execute().returnContent();
+    assertThat(content.asString(), is("foo"));
+  }  
+}
+```
+
+Certificate file, keyStorePassword and certPassword can be configured with @MocoCertificate.
+
+You can also configure certificate file with `classpath`.
+
+```java
+@ExtendWith(MocoExtension.class)
+@MocoHttpServer(classpath = "foo.json", port=12306)
+@MocoCertificate(classpath = "certificate/cert.jks", keyStorePassword = "mocohttps", certPassword = "mocohttps")
+public class MocoHttpTest {
+  @Test
+  public void should_return_expected_message() throws IOException {
+    ...
+  }  
+}
+```
+
+