Jvadocs and cycle fix

Author: cardil

README.md

@@ -6,11 +6,41 @@ Gasper is a very simple integration testing JUnit harness for `java -jar` server
 
 [![WildFly Swarm](https://avatars3.githubusercontent.com/u/11523816?v=3&s=100)](http://wildfly-swarm.io/) [![Spring Boot](https://avatars2.githubusercontent.com/u/317776?v=3&s=100)](http://projects.spring.io/spring-boot/)
 
-Gasper provides a simple to use JUnit `TestRule` that can be used to build integration tests with simple apps, like micro-services. You can configure Gasper with easy to use builder interface.
+Gasper provides a simple to use JUnit `TestRule` that can be used to build integration tests with simple apps, like REST micro-services. You can configure Gasper easily with a builder interface. Gasper will start the application before test class and stop it after tests completes.
+
+Gasper supports currently only [Maven](https://maven.apache.org/). The `pom.xml` file is used to read project configuration achieving zero configuration operation.
 
 ## Usage
 
-Best to use with libraries like [Unirest](http://unirest.io/java.html) and [JSON Assert](https://github.com/marcingrzejszczak/jsonassert)
+
+Gasper utilize your packaged application. It It means it should be used in integration tests that run after application is being packaged by build tool (Maven). Add this code to your `pom.xml` file (if you didn't done that before):
+
+```xml
+<build>
+[..]
+<plugins>
+[..]
+  <plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-failsafe-plugin</artifactId>
+    <version>2.19.1</version>
+    <executions>
+      <execution>
+        <goals>
+          <goal>integration-test</goal>
+          <goal>verify</goal>
+        </goals>
+      </execution>
+    </executions>
+  </plugin>
+[..]
+</plugins>
+[..]
+</build>
+```
+
+
+Place your integration tests in classes that ends with `*IT` or `*ITest`.
 
 ### WildFly Swarm configuration
 
@@ -30,21 +60,25 @@ public static Gasper gasper = Gasper.configurations()
   .build();
 ```
 
+Before running `GasperBuilder.build()` method, you can reconfigure those default configurations to your needs.
+
 ### Example test method (Unirest + JSONAssert)
 
+Gasper is best to use with libraries like [Unirest](http://unirest.io/java.html) for fetching data and asserting HTTP/S statuses and [JSON Assert](https://github.com/marcingrzejszczak/jsonassert) to validate correctness of JSON output for REST services.
+
 ```java
 @Test
 public void testGetRoot() throws UnirestException {
   // given
-  String address = gasper.getAddress();
+  String address = gasper.getAddress(); // Address to deployed app, running live on random port
   String expectedMessage = "WildFly Swarm!";
 
   // when
   HttpResponse<String> response = Unirest.get(address).asString();
 
   // then
   assertThat(response.getStatus()).isEqualTo(200);
-  assertThat(response.getBody()).field("hello").isEqualTo(expectedMessage);
+  assertThat(response.getBody()).field("hello").isEqualTo(expectedMessage); // JSON Assert
 }
 ```
 
@@ -56,6 +90,7 @@ To configure Gasper use `GasperBuilder` interface, for ex.:
 private final int port = 11909;
 private final String webContext = "/test";
 private final String systemPropertyForPort = "swarm.http.port";
+
 @ClassRule
 public static Gasper gasper = Gasper.configure()
   .silentGasperMessages()
@@ -66,7 +101,7 @@ public static Gasper gasper = Gasper.configure()
   .withMaxStartupTime(100)
   .withMaxDeploymentTime(20)
   .withEnvironmentVariable("jdbc.password", "S3CreT!1")
-  .withServerLoggingOnConsole()
+  .withTestApplicationLoggingOnConsole()
   .usingPomFile(Paths.get("pom.xml"))
   .withArtifactPackaging("jar")
   .waitForWebContext(webContext)
@@ -89,7 +124,26 @@ public static Gasper gasper = Gasper.configure()
 </dependency>
 ```
 
+## Contributing
+
+Contributions are welcome!
+
+To contribute, follow the standard [git flow](http://danielkummer.github.io/git-flow-cheatsheet/) of:
+
+1. Fork it
+1. Create your feature branch (`git checkout -b feature/my-new-feature`)
+1. Commit your changes (`git commit -am 'Add some feature'`)
+1. Push to the branch (`git push origin feature/my-new-feature`)
+1. Create new Pull Request
+
+Even if you can't contribute code, if you have an idea for an improvement please open an [issue](https://github.com/wavesoftware/java-gasper/issues).
+
 ## Requirements
 
-Gasper requires Java 8. Tested on Travis CI.
+* Java 8
+* Maven 3
+
+## Releases
 
+* `1.0.0` - codename: *SkyMango*
+	* First publicly available release

src/main/java/pl/wavesoftware/gasper/Gasper.java

@@ -9,7 +9,6 @@
 import org.junit.runner.Description;
 import org.junit.runners.model.Statement;
 import pl.wavesoftware.eid.utils.EidPreconditions;
-import pl.wavesoftware.gasper.internal.AbstractGasperBuilder;
 import pl.wavesoftware.gasper.internal.Executor;
 import pl.wavesoftware.gasper.internal.Logger;
 import pl.wavesoftware.gasper.internal.Settings;
@@ -28,6 +27,119 @@
 import static pl.wavesoftware.eid.utils.EidPreconditions.tryToExecute;
 
 /**
+ * <h2>About</h2>
+ * Gasper is a very simple integration testing JUnit harness for <code>java -jar</code> servers like <a href="http://wildfly-swarm.io/">WildFly Swarm</a> and <a href="http://projects.spring.io/spring-boot/">Spring Boot</a>.
+ * <p>
+ * Gasper provides a simple to use JUnit {@link TestRule} that can be used to build integration tests with simple apps, like REST micro-services. You can configure Gasper easily with a builder interface. Gasper will start the application before test class and stop it after tests completes.
+ * <p>
+ * Gasper supports currently only <a href="https://maven.apache.org/">Maven</a>. The <code>pom.xml</code> file is used to read project configuration achieving zero configuration operation.
+ *
+ * <h3>Usage</h3>
+ *
+ * Gasper utilize your packaged application. It  It means it should be used in integration tests that run after application is being packaged by build tool (Maven). Add this code to your <code>pom.xml</code> file (if you didn't done that before):
+ *
+ * <pre>
+ * &lt;build&gt;
+ * [..]
+ * &lt;plugins&gt;
+ * [..]
+ * &lt;plugin&gt;
+ *   &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
+ *   &lt;artifactId&gt;maven-failsafe-plugin&lt;/artifactId&gt;
+ *   &lt;version&gt;2.19.1&lt;/version&gt;
+ *   &lt;executions&gt;
+ *     &lt;execution&gt;
+ *       &lt;goals&gt;
+ *         &lt;goal&gt;integration-test&lt;/goal&gt;
+ *         &lt;goal&gt;verify&lt;/goal&gt;
+ *       &lt;/goals&gt;
+ *     &lt;/execution&gt;
+ *   &lt;/executions&gt;
+ * &lt;/plugin&gt;
+ * [..]
+ * &lt;/plugins&gt;
+ * [..]
+ * &lt;/build&gt;
+ * </pre>
+ *
+ * Place your integration tests in classes that ends with <code>*IT</code> or <code>*ITest</code>.
+ *
+ * <h4>WildFly Swarm default configuration</h4>
+ *
+ * <pre>
+ * &#064;ClassRule
+ * public static Gasper gasper = Gasper.configurations()
+ *   .wildflySwarm()
+ *   .build();
+ * </pre>
+ *
+ * <h4>Spring Boot default configuration</h4>
+ *
+ * <pre>
+ * &#064;ClassRule
+ * public static Gasper gasper = Gasper.configurations()
+ *   .springBoot()
+ *   .build();
+ * </pre>
+ * <p>
+ * Before running {@link GasperBuilder#build()} method, you can reconfigure those default configurations to your needs.
+ *
+ * <h4>Example test method (Unirest + JSONAssert)</h4>
+ *
+ * Gasper is best to use with libraries like <a href="http://unirest.io/java.html">Unirest</a> for fetching
+ * data and asserting HTTP/S statuses and <a href="https://github.com/marcingrzejszczak/jsonassert">JSON
+ * Assert</a> to validate correctness of JSON output for REST services.
+ *
+ * <pre>
+ * &#064;Test
+ * public void testGetRoot() throws UnirestException {
+ *   // given
+ *   String address = gasper.getAddress(); // Address to deployed app, running live on random port
+ *   String expectedMessage = "WildFly Swarm!";
+ *   // when
+ *   HttpResponse<String> response = Unirest.get(address).asString();
+ *   // then
+ *   assertThat(response.getStatus()).isEqualTo(200);
+ *   assertThat(response.getBody()).field("hello").isEqualTo(expectedMessage); // JSON Assert
+ * }
+ * </pre>
+ *
+ * <h4>Additional configuration</h4>
+ *
+ * To configure Gasper use {@link GasperBuilder} interface, for ex.:
+ *
+ * <pre>
+ * private final int port = 11909;
+ * private final String webContext = "/test";
+ * private final String systemPropertyForPort = "swarm.http.port";
+ *
+ * &#064;ClassRule
+ * public static Gasper gasper = Gasper.configure()
+ *   .silentGasperMessages()
+ *   .usingSystemPropertyForPort(systemPropertyForPort)
+ *   .withSystemProperty("swarm.context.path", webContext)
+ *   .withSystemProperty(systemPropertyForPort, String.valueOf(port))
+ *   .withJVMOptions("-server", "-Xms1G", "-Xmx1G", "-XX:+UseConcMarkSweepGC")
+ *   .withMaxStartupTime(100)
+ *   .withMaxDeploymentTime(20)
+ *   .withEnvironmentVariable("jdbc.password", "S3CreT!1")
+ *   .withTestApplicationLoggingOnConsole()
+ *   .usingPomFile(Paths.get("pom.xml"))
+ *   .withArtifactPackaging("jar")
+ *   .waitForWebContext(webContext)
+ *   .withArtifactClassifier("swarm")
+ *   .usingWebContextChecker(GasperBuilderTest::checkContext)
+ *   .withPort(port)
+ *   .build();
+ * </pre>
+ *
+ * <h4>Requirements</h4>
+ *
+ * <ul>
+ *     <li>Java 8</li>
+ *     <li>Maven 3</li>
+ * </ul>
+ *
  * @author Krzysztof Suszyński <krzysztof.suszynski@wavesoftware.pl>
  * @since 2016-03-04
  */
@@ -54,31 +166,40 @@ public final class Gasper implements TestRule {
     /**
      * Creates a builder interface {@link GasperBuilder} that can be used to configure Gasper.
      * <p>
-     * You can also use already created configurations by using method {@link #configurations()} for convenience.
+     * You can also use, already created, configurations by using method {@link #configurations()} for
+     * convenience.
      * @return a configure interface for configuration purposes
      */
     public static GasperBuilder configure() {
-        return new GasperBuilderImpl();
+        return new GasperBuilder();
     }
 
+    /**
+     * Retrieves {@link GasperConfigurations} which hold some pre configured {@link GasperBuilder} instances
+     * and can be used for convenience.
+     * @return a pre configured configurations
+     */
     public static GasperConfigurations configurations() {
         return new GasperConfigurations();
     }
 
+    /**
+     * Use this method to get port on which Gasper runs your test application.
+     * @return a usually random port on which Gasper runs your application
+     */
     public Integer getPort() {
         return settings.getPort();
     }
 
+    /**
+     * Use this method to get full address to your test application that Gasper runs. It usually
+     * contains a random port.
+     * @return a full address to running application
+     */
     public String getAddress() {
         return settings.getEndpoint().fullAddress();
     }
 
-    protected interface RunnerCreator {
-        default Gasper create(Settings settings) {
-            return new Gasper(settings);
-        }
-    }
-
     @Override
     public Statement apply(Statement base, Description description) {
         return tryToExecute((EidPreconditions.UnsafeSupplier<Statement>) () -> {
@@ -88,6 +209,12 @@ public Statement apply(Statement base, Description description) {
         }, "20160305:004035");
     }
 
+    protected interface RunnerCreator {
+        default Gasper create(Settings settings) {
+            return new Gasper(settings);
+        }
+    }
+
     private void setup() {
         log(FIGLET);
         MavenResolver resolver = new MavenResolver(settings.getPomfile());
@@ -155,8 +282,4 @@ private void ensureLogger() {
             logger = new Logger(log, settings);
         }
     }
-
-    private static class GasperBuilderImpl extends AbstractGasperBuilder {
-
-    }
 }