The Assert4J library lets you easily test REST and SOAP APIs using Java, Groovy or Cucumber. Under the hood the library uses the open-source test-execution engine of SoapUI.
Add the following Maven dependency to your project:
<dependency>
<groupId>io.swagger.assert</groupId>
<artifactId>swagger-assert4j-facade</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
Create and execute a simple recipe with your favorite unit-testing framework:
@Test
public void simpleCountTest() throws Exception {
RecipeExecutionResult result = executeRecipe(
GET("https://api.swaggerhub.com/specs")
.withParameters(
query("specType", "API"),
query("query", "testserver")
)
.withAssertions(
json("$.totalCount", "4")
)
);
assertExecutionResult(result);
}
Run your test and enjoy the results (or not…);
java.lang.AssertionError: Execution failed: [[JsonPath Match] Comparison failed for path [$.totalCount], expecting [4], actual was [5]]
Expected :FINISHED
Actual :FAILED
Learn more about the Java testing vocabulary by:
Assert4J provides a Groovy DSL to create and execute API tests locally or on TestServer. Documentation of the DSL is available here.
The following steps explain how to use this DSL in a JUnit test.
Add the following Maven dependency to your project:
<dependency>
<groupId>io.swagger.assert</groupId>
<artifactId>swagger-assert4j-groovy-dsl</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
Create a JUnit test with a test recipe in Groovy:
The example below shows how to create and execute a recipe with one single step locally, using the SoapUI OS engine. This requires the additional dependency on io.swagger.assert:assert4j-local, but there is no need to install SoapUI.
import io.swagger.assert4j.execution.Execution
import org.junit.Test
import static io.swagger.assert4j.dsl.execution.RecipeExecution.executeRecipe
class DslTestDemo {
@Test
void testSwaggerHubApi() {
//Executes recipe locally - this requires the additional dependency io.swagger.assert:assert4j-local
Execution execution = executeRecipe {
get 'https://api.swaggerhub.com/specs', {
parameters {
query 'specType', 'API'
query 'query', 'testserver'
}
asserting {
jsonPath '$.totalCount' occurs 0 times
}
}
}
assert execution.errorMessages.empty
}
}
Here is sample output from this test. It shows that the assertion on the test step has failed:
Assertion failed:
assert execution.errorMessages.empty
| | |
| | false
| [[JsonPath Count] Comparison failed for path [$.totalCount], expecting [0], actual was [1]]
io.swagger.assert4j.local.execution.SoapUIRecipeExecution@f810c18
Similarly, you can execute the recipe on TestServer with the following:
import io.swagger.assert4j.execution.Execution
import org.junit.Test
import static io.swagger.assert4j.dsl.execution.RecipeExecution.executeRecipeOnServer
class DslTestDemo {
@Test
void testSwaggerHubApi() {
Execution execution = executeRecipeOnServer '<your TestServer url, e.g. http://localhost:8080>', '<your user>', '<your password>', {
get 'https://api.swaggerhub.com/specs', {
parameters {
query 'specType', 'API'
query 'query', 'testserver'
}
asserting {
jsonPath '$.totalCount' occurs 0 times
}
}
}
assert execution.errorMessages.empty
}
}
Here is sample output from this test:
Assertion failed:
assert execution.errorMessages.empty
| | |
| | false
| [TestStepName: GET request 1, messages: [JsonPath Count] Comparison failed. Path: [$.totalCount]; Expected value: [0]; Actual value: [1].]
io.swagger.assert4j.testserver.execution.TestServerExecution@dfddc9a
Tutorial in the ReadyAPI TestServer documentation: Creating Code-Based Recipes: Tutorial
The samples submodule here on GitHub contains a number of samples for Java, Groovy and Maven.
To get access to extended functionality like data-driven testing, centralized execution and reporting, etc., you need to execute your tests with ReadyAPI TestServer instead of running them locally.
TestServer is a standalone server that exposes a REST API for running API tests, it receives and runs test recipes in the same underlying JSON format that is also used in the test shown above. If you’re using the RecipeExecutionFacade (as in the example above) all you have to do is add system (or environment) variables that point the facade to a running TestServer instance. For example, if we add
testserver.endpoint=http://testserver.readyapi.io:8080
testserver.user=demoUser
testserver.password=demoPassword
as either system/env properties to our execution and then rerun the above test - those tests will be executed by the specified TestServer instance available at http://testserver.readyapi.io.
Usage of the facade as in the above examples also enables logging of both generated recipes and HTTP transaction logs of executed tests (in HAR file format). Adding the following two properties:
swagger-assert4j.log.executions.folder=target/logs/executions
swagger-assert4j.log.recipes.folder=target/logs/recipes
will automatically result in the corresponding artifacts being written to the corresponding folders.
This library is licensed under the Apache 2.0 License - copyright Smartbear Software