{"id":13511255,"url":"https://github.com/cybertk/abao","last_synced_at":"2025-05-15T08:06:02.130Z","repository":{"id":21371271,"uuid":"24688601","full_name":"cybertk/abao","owner":"cybertk","description":"REST API automated testing tool based on RAML","archived":false,"fork":false,"pushed_at":"2024-11-20T12:37:27.000Z","size":463,"stargazers_count":354,"open_issues_count":38,"forks_count":59,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-04-13T12:44:15.810Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"CoffeeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cybertk.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-10-01T17:46:18.000Z","updated_at":"2025-02-24T04:21:58.000Z","dependencies_parsed_at":"2024-12-27T16:01:59.100Z","dependency_job_id":"23707299-ddf9-491d-bc1c-890fd5845e2a","html_url":"https://github.com/cybertk/abao","commit_stats":{"total_commits":404,"total_committers":22,"mean_commits":"18.363636363636363","dds":"0.44059405940594054","last_synced_commit":"ed1db210433647ed232b50baeeac57bbf8aa459d"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cybertk%2Fabao","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cybertk%2Fabao/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cybertk%2Fabao/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cybertk%2Fabao/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cybertk","download_url":"https://codeload.github.com/cybertk/abao/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248870168,"owners_count":21174991,"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":[],"created_at":"2024-08-01T03:00:42.012Z","updated_at":"2025-04-14T11:25:18.913Z","avatar_url":"https://github.com/cybertk.png","language":"CoffeeScript","funding_links":[],"categories":["CoffeeScript","Automated API Testing \u0026 Load Testing Tools","Automated Testing"],"sub_categories":["50. [abao](https://github.com/cybertk/abao)"],"readme":"# Abao\n\nRAML-based automated testing tool\n\n[![Build Status][Travis-Abao-badge]][Travis-Abao]\n[![Dependency Status][DavidDM-AbaoDep-badge]][DavidDM-AbaoDep]\n[![devDependency Status][DavidDM-AbaoDevDep-badge]][DavidDM-AbaoDevDep]\n[![Coverage Status][Coveralls-Abao-badge]][Coveralls-Abao]\n[![Gitter][Gitter-Abao-badge]][Gitter-Abao]\n[![CII Best Practices][BestPractices-Abao-badge]][BestPractices-Abao]\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fcybertk%2Fabao.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fcybertk%2Fabao?ref=badge_shield)\n\n**Abao** is a command-line tool for testing API documentation written in\n[RAML][] format against its back-end implementation. With **Abao**, you can\neasily plug your API documentation into a Continuous Integration (CI) system\n(e.g., [Travis][], [Jenkins][]) and have API documentation up-to-date, all\nthe time. **Abao** uses [Mocha][] for judging if a particular API response\nis valid or not.\n\n[![NPM][NPM-Abao-badge]][NPM-Abao]\n\n## Features\n\n* Verify that each endpoint defined in RAML exists in service\n* Verify that URL params for each endpoint defined in RAML are supported in service\n* Verify that the required query parameters defined in RAML are supported in service\n* Verify that HTTP request headers for each endpoint defined in RAML are supported in service\n* Verify that HTTP request body for each endpoint defined in RAML is supported in service, via [JSONSchema][] validation\n* Verify that HTTP response headers for each endpoint defined in RAML are supported in service\n* Verify that HTTP response body for each endpoint defined in RAML is supported in service, via [JSONSchema][] validation\n\n## RAML Support\n\nThis version of the software **only** supports the [RAML-0.8][] specification.\n\n## Installation\n\nInstall stable version of full package globally.\n\n```bash\n$ npm install -g abao\n```\n\nA trimmed down version (without developer dependencies) can be installed for\nproduction usage.\n\n```bash\n$ npm install --only=prod -g abao\n```\n\nInstall latest development version in GitHub branch\n\n```bash\n$ npm install -g github:cybertk/abao\n```\n\nIf you get an `EACCES` error, see\n[this](https://docs.npmjs.com/getting-started/fixing-npm-permissions)\nNPM documentation.\n\n## Get Started Testing Your API\n\nFor general usage, an API endpoint (i.e., web service to be tested) **must**\nbe specified; this can be done implicitly or explicitly, with the latter\nhaving priority. If the RAML file to be tested provides a [baseUri][] property,\nthe API endpoint is implicitly set to that value.\n\n```bash\n$ abao api.raml\n```\n\nTo explicitly specify the API endpoint, use the `--server` argument.\n\n```bash\n$ abao api.raml --server http://localhost:8080\n```\n\n## Writing testable RAML\n\n**Abao** validates the HTTP response body against `schema` defined in [RAML][].\n**No response body will be returned if the corresponding [RAML][] `schema` is missing.**\nHowever, the response status code can **always** be verified, regardless.\n\n## Hooks\n\n**Abao** can be configured to use hookfiles to do basic setup/teardown between\neach validation (specified with the `--hookfiles` flag). Hookfiles can be\nwritten in either JavaScript or CoffeeScript, and must import the hook methods.\n\n**NOTE**: CoffeeScript files **must** use file extension `.coffee`.\n\nRequests are identified by their name, which is derived from the structure of\nthe RAML. You can print a list of the generated names with the `--names` flag.\n\n### Example\n\nThe RAML file used in the examples below can be found [here](../master/test/fixtures/machines-single_get.raml).\n\nGet Names:\n\n```bash\n$ abao machines-single_get.raml --names\nGET /machines -\u003e 200\n```\n\n**Abao** can generate a hookfile to help validate more than just the\nresponse code for each path.\n\n```bash\n$ ABAO_HOME=\"/path/to/node_modules/abao\"\n$ TEMPLATE=\"${ABAO_HOME}/templates/hookfile.js\"\n$ abao machines-single_get.raml --generate-hooks --template=\"${TEMPLATE}\" \u003e test_machines_hooks.js\n\n```\n\nThen edit the *JavaScript* hookfile `test_machines_hooks.js` created in the\nprevious step to add request parameters and response validation logic.\n\n```javascript\nvar\n  hooks = require('hooks'),\n  assert = require('chai').assert;\n\nhooks.before('GET /machines -\u003e 200', function (test, done) {\n  test.request.query = {\n    color: 'red'\n  };\n  done();\n});\n\nhooks.after('GET /machines -\u003e 200', function (test, done) {\n  machine = test.response.body[0];\n  console.log(machine.name);\n  done();\n});\n```\n\nAlternately, write the same hookfile in *CoffeeScript* named\n`test_machines_hooks.coffee`:\n\n```coffeescript\n{before, after} = require 'hooks'\n{assert} = require 'chai'\n\nbefore 'GET /machines -\u003e 200', (test, done) -\u003e\n  test.request.query =\n    color: 'red'\n  done()\n\nafter 'GET /machines -\u003e 200', (test, done) -\u003e\n  machine = test.response.body[0]\n  console.log machine.name\n  done()\n```\n\nRun validation with *JavaScript* hookfile (from above):\n\n```bash\n$ abao machines-single_get.raml --hookfiles=test_machines_hooks.js\n```\n\nYou can also specify what tests **Abao** should skip:\n\n```javascript\nvar\n  hooks = require('hooks');\n\nhooks.skip('DELETE /machines/{machineId} -\u003e 204');\n```\n\n**Abao** supports callbacks for intro and outro (coda) of all tests,\nas well as before/after each test:\n\n```coffeescript\n{beforeAll, beforeEach, afterEach, afterAll} = require 'hooks'\n\nbeforeAll (done) -\u003e\n  # runs one-time setup before all tests (intro)\n  done()\n\nbeforeEach (done) -\u003e\n  # runs generic setup before any test-specific 'before()`\n  done()\n\nafterEach (done) -\u003e\n  # runs generic teardown after any test-specific 'after()'\n  done()\n\nafterAll (done) -\u003e\n  # do one-time teardown after all tests (coda)\n  done()\n```\n\nIf `beforeEach`, `afterEach`, `before` and `after` are called multiple times,\nthe callbacks are executed serially in the order they were called.\n\n**Abao** provides hook to allow the content of the response to be checked\nwithin the test:\n\n```coffeescript\n{test} = require 'hooks'\n{assert} = require 'chai'\n\ntest 'GET /machines -\u003e 200', (response, body, done) -\u003e\n  assert.deepEqual JSON.parse(body), ['machine1', 'machine2']\n  assert.equal headers['content-type'], 'application/json; charset=utf-8'\n  return done()\n```\n\n### test.request\n\n* `server` - Server address, provided by command line option or parsed from\n  RAML `baseUri`.\n* `path` - API endpoint path, parsed from RAML.\n* `method` - HTTP method, parsed from RAML request method (e.g., `get`).\n* `params` - URI parameters, parsed from RAML request `uriParameters` [default: `{}`].\n* `query` - Object containing querystring values to be appended to the `path`.\n  Parsed from RAML `queryParameters` section [default: `{}`].\n* `headers` - HTTP headers, parsed from RAML `headers` [default: `{}`].\n* `body` - Entity body for POST, PUT, and PATCH requests. Must be a\n  JSON-serializable object. Parsed from RAML `example` [default: `{}`].\n\n### test.response\n\n* `status` - Expected HTTP response code, parsed from RAML response status.\n* `schema` - Expected schema of HTTP response body, parsed from RAML response `schema`.\n* `headers` - Object containing HTTP response headers from server [default: `{}`].\n* `body` - HTTP response body (JSON-format) from server [default: `null`].\n\n## Command Line Options\n\n```console\nUsage:\n  abao \u003c/path/to/raml\u003e [OPTIONS]\n\nExample:\n  abao api.raml --server http://api.example.com\n\nOptions passed to Mocha:\n  --grep, -g      Only run tests matching \u003cpattern\u003e                     [string]\n  --invert, -i    Invert --grep matches                                [boolean]\n  --reporter, -R  Specify reporter to use             [string] [default: \"spec\"]\n  --timeout, -t   Set test case timeout in milliseconds [number] [default: 2000]\n\nOptions:\n  --generate-hooks  Output hooks generated from template file and exit [boolean]\n  --header, -h      Add header to include in each request. Header must be in\n                    KEY:VALUE format (e.g., \"-h Accept:application/json\").\n                    Reuse option to add multiple headers                [string]\n  --hookfiles, -f   Specify pattern to match files with before/after hooks for\n                    running tests                                       [string]\n  --hooks-only, -H  Run test only if defined either before or after hooks\n                                                                       [boolean]\n  --names, -n       List names of requests and exit                    [boolean]\n  --reporters       Display available reporters and exit               [boolean]\n  --schemas         Specify pattern to match schema files to be loaded for use\n                    as JSON refs                                        [string]\n  --server          Specify API endpoint to use. The RAML-specified baseUri\n                    value will be used if not provided                  [string]\n  --sorted          Sorts requests in a sensible way so that objects are not\n                    modified before they are created.\n                    Order: CONNECT, OPTIONS, POST, GET, HEAD, PUT, PATCH,\n                    DELETE, TRACE.                                     [boolean]\n  --template        Specify template file to use for generating hooks   [string]\n  --help            Show usage information and exit                    [boolean]\n  --version         Show version number and exit                       [boolean]\n```\n\n## Run Tests\n\n```bash\n$ npm test\n```\n\n## Contribution\n\n**Abao** is always looking for new ideas to make the codebase useful.\nIf you think of something that would make life easier, please submit an issue.\n\n```bash\n$ npm issues abao\n```\n\n\n[//]: # (Cross reference section)\n\n[RAML]: https://raml.org/\n[Mocha]: https://mochajs.org/\n[JSONSchema]: http://json-schema.org/\n[Travis]: https://travis-ci.org/\n[Jenkins]: https://jenkins-ci.org/\n[RAML-0.8]: https://github.com/raml-org/raml-spec/blob/master/versions/raml-08/raml-08.md\n[baseUri]: https://github.com/raml-org/raml-spec/blob/master/versions/raml-08/raml-08.md#base-uri-and-baseuriparameters\n\n[Travis-Abao]: https://travis-ci.org/cybertk/abao/\n[Travis-Abao-badge]: https://img.shields.io/travis/cybertk/abao.svg?style=flat\n[DavidDM-AbaoDep]: https://david-dm.org/cybertk/abao/\n[DavidDM-AbaoDep-badge]: https://david-dm.org/cybertk/abao/status.svg\n[DavidDM-AbaoDevDep]: https://david-dm.org/cybertk/abao?type=dev\n[DavidDM-AbaoDevDep-badge]: https://david-dm.org/cybertk/abao/dev-status.svg\n[Coveralls-Abao]: https://coveralls.io/r/cybertk/abao/\n[Coveralls-Abao-badge]: https://img.shields.io/coveralls/cybertk/abao.svg\n[Gitter-Abao]: https://gitter.im/cybertk/abao/\n[Gitter-Abao-badge]: https://badges.gitter.im/cybertk/abao.svg\n[BestPractices-Abao]: https://bestpractices.coreinfrastructure.org/projects/388\n[BestPractices-Abao-badge]: https://bestpractices.coreinfrastructure.org/projects/388/badge\n[NPM-Abao]: https://npmjs.org/package/abao/\n[NPM-Abao-badge]: https://nodei.co/npm/abao.png?downloads=true\u0026downloadRank=true\u0026stars=true\n\n\n## License\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fcybertk%2Fabao.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fcybertk%2Fabao?ref=badge_large)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcybertk%2Fabao","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcybertk%2Fabao","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcybertk%2Fabao/lists"}