Skip to content

Commit

Permalink
Jvadocs and cycle fix
Browse files Browse the repository at this point in the history
  • Loading branch information
@cardil
cardil committed Mar 6, 2016
1 parent 19e9703 commit 87c4816
Show file tree
Hide file tree
Showing 7 changed files with 475 additions and 193 deletions.
66 changes: 60 additions & 6 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
}
```

Expand All @@ -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()
Expand All @@ -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)
Expand All @@ -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
149 changes: 136 additions & 13 deletions src/main/java/pl/wavesoftware/gasper/Gasper.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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
*/
Expand All @@ -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>) () -> {
Expand All @@ -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());
Expand Down Expand Up @@ -155,8 +282,4 @@ private void ensureLogger() {
logger = new Logger(log, settings);
}
}

private static class GasperBuilderImpl extends AbstractGasperBuilder {

}
}

0 comments on commit 87c4816

Please sign in to comment.