raml-tester
Test if a request/response matches a given raml definition.
Versioning
| Version | Contents |
|---|---|
| 0.8.x | Stable version, uses RAML parser 0.8.x and supports only RAML v0.8 |
| 0.9.x | Development version, uses RAML parser 1.x and supports RAML v0.8 and parts of v1.0 |
| 1.0.x | As soon as RAML v1.0 support is stable |
Add it to a project
Add these lines to the pom.xml:
<dependency>
<groupId>guru.nidi.raml</groupId>
<artifactId>raml-tester</artifactId>
<version>0.8.8</version>
</dependency>
If you are stuck with java 1.6, use the compatible version by adding the following line:
<classifier>jdk6</classifier>
Use in a spring MVC test
@RunWith(SpringJUnit4ClassRunner.class)
@WebAppConfiguration
@ContextConfiguration(classes = Application.class)
public class SpringTest {
private static RamlDefinition api = RamlLoaders.fromClasspath(SpringTest.class).load("api.raml")
.assumingBaseUri("http://nidi.guru/raml/simple/v1");
private static SimpleReportAggregator aggregator = new SimpleReportAggregator();
@ClassRule
public static ExpectedUsage expectedUsage = new ExpectedUsage(aggregator);
@Autowired
private WebApplicationContext wac;
private MockMvc mockMvc;
@Before
public void setup() {
mockMvc = MockMvcBuilders.webAppContextSetup(wac).build();
}
@Test
public void greeting() throws Exception {
Assert.assertThat(api.validate(), validates());
mockMvc.perform(get("/greeting").accept(MediaType.parseMediaType("application/json")))
.andExpect(api.matches().aggregating(aggregator));
}
}
The ExpectedUsage rule checks if all resources, query parameters, form parameters, headers and response codes defined in the RAML are at least used once.
The RamlMatchers.validates() matcher validates the RAML itself.
api.matches() checks that the request/response match the RAML definition.
See also the raml-tester-uc-spring project.
Use in a Java EE / JAX-RS environment
@RunWith(Arquillian.class)
public class JaxrsTest {
private static RamlDefinition api = RamlLoaders.fromClasspath(JaxrsTest.class).load("api.raml")
.assumingBaseUri("http://nidi.guru/raml/simple/v1");
private static SimpleReportAggregator aggregator = new SimpleReportAggregator();
private static WebTarget target;
@ClassRule
public static ExpectedUsage expectedUsage = new ExpectedUsage(aggregator);
@Deployment(testable = false)
public static WebArchive createDeployment() {
return ShrinkWrap.create(WebArchive.class).addClass(Application.class);
}
@ArquillianResource
private URL base;
@Before
public void setup() throws MalformedURLException {
Client client = ClientBuilder.newClient();
target = client.target(URI.create(new URL(base, "app/path").toExternalForm()));
}
@Test
public void greeting() throws Exception {
assertThat(api.validate(), validates());
final CheckingWebTarget webTarget = api.createWebTarget(target).aggregating(aggregator);
webTarget.request().post(Entity.text("apple"));
assertThat(webTarget.getLastReport(), checks());
}
}
The RamlMatchers.checks() matcher validates that the request and response conform to the RAML.
Use in a pure servlet environment
public class RamlFilter implements Filter {
private final Logger log = LoggerFactory.getLogger(getClass());
private RamlDefinition api;
@Override
public void init(FilterConfig filterConfig) throws ServletException {
api = RamlLoaders.fromClasspath(getClass()).load("api.yaml");
log.info(api.validate().toString());
}
@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
throws IOException, ServletException {
final RamlReport report = api.testAgainst(request, response, chain);
log.info("Raml report: " + report);
}
@Override
public void destroy() {
}
}
Or see the raml-tester-uc-sevlet project.
Use together with Apache HttpComponents
public class HttpComponentsTest {
@Test
public void testRequest() throws IOException {
RamlDefinition api = RamlLoaders.fromClasspath(getClass()).load("api.yaml");
Assert.assertThat(api.validate(), validates());
RamlHttpClient client = api.createHttpClient();
HttpGet get = new HttpGet("http://test.server/path");
HttpResponse response = client.execute(get);
Assert.assertThat(client.getLastReport(), checks());
}
}
Or see the raml-tester-uc-servlet project.
Use together with RestAssured
public class RestAssuredTest {
@Test
public void testWithRestAssured() {
RestAssured.baseURI = "http://test.server/path";
RamlDefinition api = RamlLoaders.fromClasspath(getClass()).load("api.yaml");
Assert.assertThat(api.validate(), validates());
RestAssuredClient restAssured = api.createRestAssured();
restAssured.given().get("/base/data").andReturn();
Assert.assertTrue(restAssured.getLastReport().isEmpty());
}
}
If you are using RestAssured 3.0, call api.createRestAssured3().
Use as a standalone proxy
When used as a proxy, any service can be tested, regardless of the technology used to implement it. See the raml-proxy project.
Use with Javascript
There is special support for javascript.
See raml-tester-js for details and raml-tester-uc-js for examples.
FailFast
You can configure the RamlDefinition to throw an exception in case a violation is found.
@Test(expected = RamlViolationException.class)
public void testInvalidResource() {
RestAssured.baseURI = "http://test.server/path";
RamlDefinition api = RamlLoaders.fromClasspath(getClass()).load("api.yaml");
Assert.assertThat(api.validate(), validates());
RestAssuredClient restAssured = api.failFast().createRestAssured();
restAssured.given().get("/wrong/path").andReturn();
fail("Should throw RamlViolationException");
}
11 Jul 11, 2022
4 Mar 23, 2022
6.5k Dec 28, 2022
654 Dec 28, 2022
113 Nov 7, 2022
2.5k Jan 2, 2023
3.9k Dec 28, 2022
1.3k Jan 7, 2023
1.9k Jan 3, 2023
268 Dec 11, 2022
260 Jan 2, 2023
20 Jul 26, 2022
247 Jan 9, 2023
133 Nov 17, 2022
143 Nov 22, 2022
5.8k Dec 27, 2022
6.5k Dec 31, 2022