{"id":23328948,"url":"https://github.com/nidi3/raml-tester","last_synced_at":"2025-08-22T22:33:32.881Z","repository":{"id":16566677,"uuid":"19320564","full_name":"nidi3/raml-tester","owner":"nidi3","description":"Test if a request/response matches a given raml definition","archived":false,"fork":false,"pushed_at":"2019-02-13T20:29:00.000Z","size":1241,"stargazers_count":71,"open_issues_count":14,"forks_count":14,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-05-03T00:16:47.711Z","etag":null,"topics":["java","raml","raml-tooling","testing"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nidi3.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-04-30T16:49:44.000Z","updated_at":"2024-03-31T14:14:47.000Z","dependencies_parsed_at":"2022-09-13T21:03:22.732Z","dependency_job_id":null,"html_url":"https://github.com/nidi3/raml-tester","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nidi3%2Framl-tester","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nidi3%2Framl-tester/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nidi3%2Framl-tester/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nidi3%2Framl-tester/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nidi3","download_url":"https://codeload.github.com/nidi3/raml-tester/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230647184,"owners_count":18258833,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","raml","raml-tooling","testing"],"created_at":"2024-12-20T21:29:45.869Z","updated_at":"2024-12-20T21:29:46.591Z","avatar_url":"https://github.com/nidi3.png","language":"Java","funding_links":[],"categories":["项目","测试","Projects"],"sub_categories":["测试","Testing"],"readme":"raml-tester\n===========\n[![Build Status](https://travis-ci.org/nidi3/raml-tester.svg?branch=master)](https://travis-ci.org/nidi3/raml-tester)\n[![codecov](https://codecov.io/gh/nidi3/raml-tester/branch/master/graph/badge.svg)](https://codecov.io/gh/nidi3/raml-tester)\n[![License](https://img.shields.io/badge/License-Apache_2.0-yellowgreen.svg)](https://opensource.org/licenses/Apache-2.0)\n\nTest if a request/response matches a given raml definition.\n\nVersioning\n--\n\nVersion | Contents\n---|---\n0.8.x | Stable version, uses [RAML parser 0.8.x](https://github.com/raml-org/raml-java-parser/tree/v1) and supports only RAML v0.8\n0.9.x | Development version, uses [RAML parser 1.x](https://github.com/raml-org/raml-java-parser) and supports RAML v0.8 and [parts of v1.0](https://github.com/nidi3/raml-tester/blob/raml-parser-2/1.0-support.md)\n1.0.x | As soon as RAML v1.0 support is stable\n\nAdd it to a project\n-------------------\nAdd these lines to the `pom.xml`:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eguru.nidi.raml\u003c/groupId\u003e\n    \u003cartifactId\u003eraml-tester\u003c/artifactId\u003e\n    \u003cversion\u003e0.8.8\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nIf you are stuck with java 1.6, use the compatible version by adding the following line:\n\n```xml\n    \u003cclassifier\u003ejdk6\u003c/classifier\u003e\n```\n\nUse in a spring MVC test\n------------------------\n[//]: # (spring)\n```java\n@RunWith(SpringJUnit4ClassRunner.class)\n@WebAppConfiguration\n@ContextConfiguration(classes = Application.class)\npublic class SpringTest {\n\n    private static RamlDefinition api = RamlLoaders.fromClasspath(SpringTest.class).load(\"api.raml\")\n            .assumingBaseUri(\"http://nidi.guru/raml/simple/v1\");\n    private static SimpleReportAggregator aggregator = new SimpleReportAggregator();\n\n    @ClassRule\n    public static ExpectedUsage expectedUsage = new ExpectedUsage(aggregator);\n\n    @Autowired\n    private WebApplicationContext wac;\n\n    private MockMvc mockMvc;\n\n    @Before\n    public void setup() {\n        mockMvc = MockMvcBuilders.webAppContextSetup(wac).build();\n    }\n\n    @Test\n    public void greeting() throws Exception {\n        Assert.assertThat(api.validate(), validates());\n\n        mockMvc.perform(get(\"/greeting\").accept(MediaType.parseMediaType(\"application/json\")))\n                .andExpect(api.matches().aggregating(aggregator));\n    }\n}\n```\n[//]: # (end)\n\nThe `ExpectedUsage` rule checks if all resources, query parameters, form parameters, headers and response codes\ndefined in the RAML are at least used once.\n\nThe `RamlMatchers.validates()` matcher validates the RAML itself.\n \n`api.matches()` checks that the request/response match the RAML definition.\n\nSee also the [raml-tester-uc-spring](https://github.com/nidi3/raml-tester-uc-spring) project.\n\nUse in a Java EE / JAX-RS environment\n-------------------------------------\n[//]: # (jaxrs)\n```java\n@RunWith(Arquillian.class)\npublic class JaxrsTest {\n\n    private static RamlDefinition api = RamlLoaders.fromClasspath(JaxrsTest.class).load(\"api.raml\")\n            .assumingBaseUri(\"http://nidi.guru/raml/simple/v1\");\n    private static SimpleReportAggregator aggregator = new SimpleReportAggregator();\n    private static WebTarget target;\n\n    @ClassRule\n    public static ExpectedUsage expectedUsage = new ExpectedUsage(aggregator);\n\n    @Deployment(testable = false)\n    public static WebArchive createDeployment() {\n        return ShrinkWrap.create(WebArchive.class).addClass(Application.class);\n    }\n\n    @ArquillianResource\n    private URL base;\n\n    @Before\n    public void setup() throws MalformedURLException {\n        Client client = ClientBuilder.newClient();\n        target = client.target(URI.create(new URL(base, \"app/path\").toExternalForm()));\n    }\n\n    @Test\n    public void greeting() throws Exception {\n        assertThat(api.validate(), validates());\n\n        final CheckingWebTarget webTarget = api.createWebTarget(target).aggregating(aggregator);\n        webTarget.request().post(Entity.text(\"apple\"));\n\n        assertThat(webTarget.getLastReport(), checks());\n    }\n}\n```\n[//]: # (end)\n\nThe `RamlMatchers.checks()` matcher validates that the request and response conform to the RAML.\n\n\nUse in a pure servlet environment\n---------------------------------\n[//]: # (servlet)\n```java\npublic class RamlFilter implements Filter {\n    private final Logger log = LoggerFactory.getLogger(getClass());\n    private RamlDefinition api;\n\n    @Override\n    public void init(FilterConfig filterConfig) throws ServletException {\n        api = RamlLoaders.fromClasspath(getClass()).load(\"api.yaml\");\n        log.info(api.validate().toString());\n    }\n\n    @Override\n    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)\n            throws IOException, ServletException {\n        final RamlReport report = api.testAgainst(request, response, chain);\n        log.info(\"Raml report: \" + report);\n    }\n\n    @Override\n    public void destroy() {\n    }\n}\n```\n[//]: # (end)\n\nOr see the [raml-tester-uc-sevlet](https://github.com/nidi3/raml-tester-uc-servlet) project.\n\nUse together with Apache HttpComponents\n---------------------------------------\n\n[//]: # (httpComponents)\n```java\npublic class HttpComponentsTest {\n    @Test\n    public void testRequest() throws IOException {\n        RamlDefinition api = RamlLoaders.fromClasspath(getClass()).load(\"api.yaml\");\n        Assert.assertThat(api.validate(), validates());\n\n        RamlHttpClient client = api.createHttpClient();\n        HttpGet get = new HttpGet(\"http://test.server/path\");\n        HttpResponse response = client.execute(get);\n\n        Assert.assertThat(client.getLastReport(), checks());\n    }\n}\n```\n[//]: # (end)\n\nOr see the [raml-tester-uc-servlet](https://github.com/nidi3/raml-tester-uc-servlet) project.\n\nUse together with RestAssured\n---------------------------------------\n[//]: # (restAssured)\n```java\npublic class RestAssuredTest {\n    @Test\n    public void testWithRestAssured() {\n        RestAssured.baseURI = \"http://test.server/path\";\n        RamlDefinition api = RamlLoaders.fromClasspath(getClass()).load(\"api.yaml\");\n        Assert.assertThat(api.validate(), validates());\n\n        RestAssuredClient restAssured = api.createRestAssured();\n        restAssured.given().get(\"/base/data\").andReturn();\n        Assert.assertTrue(restAssured.getLastReport().isEmpty());\n    }\n}\n```\n[//]: # (end)\nIf you are using RestAssured 3.0, call `api.createRestAssured3()`.\n\nUse as a standalone proxy\n-------------------------\nWhen used as a proxy, any service can be tested, regardless of the technology used to implement it.\nSee the [raml-proxy](https://github.com/nidi3/raml-tester-proxy) project.\n\nUse with Javascript\n-------------------\nThere is special support for javascript.\n\nSee [raml-tester-js](https://github.com/nidi3/raml-tester-js) for details and\n[raml-tester-uc-js](https://github.com/nidi3/raml-tester-uc-js) for examples.\n\n\n\nFailFast\n---------------------------------------\nYou can configure the RamlDefinition to throw an exception in case a violation is found.\n\n[//]: # (failFast)\n```java\n@Test(expected = RamlViolationException.class)\npublic void testInvalidResource() {\n    RestAssured.baseURI = \"http://test.server/path\";\n    RamlDefinition api = RamlLoaders.fromClasspath(getClass()).load(\"api.yaml\");\n    Assert.assertThat(api.validate(), validates());\n\n    RestAssuredClient restAssured = api.failFast().createRestAssured();\n    restAssured.given().get(\"/wrong/path\").andReturn();\n    fail(\"Should throw RamlViolationException\");\n}\n```\n[//]: # (end)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnidi3%2Framl-tester","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnidi3%2Framl-tester","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnidi3%2Framl-tester/lists"}