What is Gavel?
Gavel is a tool for deciding which HTTP API call is valid and which is not.
It's useful for:
- Specification by example and BDD for HTTP (RESTful) APIs
- Diff HTTP Requests and Responses
- Testing API documentation
- DRY test assertion engine for REST API's HTTP request and response
- API client (SDK) validations
$ curl --trace - http://httpbin.org/ip | curl-trace-parser > expected $ curl --trace - http://httpbin.org/ip | curl-trace-parser > real $ cat real | gavel expected_message $ echo $? 0
How does it work?
Gavel` filters out boring noise in API communication and helps you understand important differences between real and expected HTTP messages (HTTP request and response). You can use Gavel with examples for:
- HTTP Headers
- Textual HTTP body
- JSON HTTP body
- HTTP body defined by JSON Shema
- Status code
Brief behavior description
- Headers can't miss
- Header values metters
- JSON keys in bodies can't miss
- Textual body must match exactly
See detailed expectation behavior specification
Platform independent documentation and specification
Gavel is fair to everyone!
Relish radically changed point of view on Cucumber from BDD tool to documentation-oriented acceptance testing platform for collaboration. Examples are made on raw HTTP, in order to focus on implementation independence. It means, thanks to Cucumber, each example in Gavel specification is tested against each Gavel implementation in continous integration. So Gavel's behavior documentation can never be outdated and Gavel's behavior is consistent across all languages.
Contribution to this specification
- Fork this repo
- Make change to existing features or add features
- Bump version (create tag)
- Open pull request
Use GitHub issues for discussion.
New language implementation (the BDD way)
- Fork this repo
- Assign implementation specific Cucumebr tag (e.g. @erlang) in this document
- Add forked repo as git submodule to cucumber feature directory in your project
- Setup your Cucumber-like test runner to use only this tag (-t option) to filter out other implementations
- Tag features with your language tag as you implement
- Implement Cucumber step definitions (glue code between Cucumber steps and your code)
- Run Cucumber and see it failing
- Implement scenario in your code
- Run Cucumber and see examples passing (Make cukes green)
- Do not forget to add Cucumber features for code exapmles for your implementation
- Add your repository to Travis-CI and add badge in this document
- Publish your repository
Untagged features and scenarios are considered mandatory in all imlpementations
@draft - feature sketch, aggregation thoughts @proposalt - proposal for stabilization
Implementation specific tags
@nodejs - Implemented in Node.js, tested
@nodejs-pending Planned to implement in Node.js, NOT tested