{"id":13500633,"url":"https://github.com/kiranz/just-api","last_synced_at":"2025-05-14T11:09:03.105Z","repository":{"id":46562079,"uuid":"136474968","full_name":"kiranz/just-api","owner":"kiranz","description":":boom: Test REST, GraphQL APIs","archived":false,"fork":false,"pushed_at":"2025-01-03T14:04:22.000Z","size":2010,"stargazers_count":819,"open_issues_count":14,"forks_count":36,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-04-29T17:22:31.872Z","etag":null,"topics":["api","api-testing","automation","graphql","graphql-testing","http","http-api-testing","javascript","microservice","rest","testing","webservice","webservice-test","yaml"],"latest_commit_sha":null,"homepage":"https://kiranz.github.io/just-api/","language":"JavaScript","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/kiranz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["kiranz"]}},"created_at":"2018-06-07T12:35:18.000Z","updated_at":"2025-04-23T17:40:28.000Z","dependencies_parsed_at":"2025-01-25T15:00:29.818Z","dependency_job_id":"2380d936-accf-404b-a945-d970ad1b193e","html_url":"https://github.com/kiranz/just-api","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiranz%2Fjust-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiranz%2Fjust-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiranz%2Fjust-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiranz%2Fjust-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kiranz","download_url":"https://codeload.github.com/kiranz/just-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253066892,"owners_count":21848516,"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":["api","api-testing","automation","graphql","graphql-testing","http","http-api-testing","javascript","microservice","rest","testing","webservice","webservice-test","yaml"],"created_at":"2024-07-31T22:01:07.863Z","updated_at":"2025-05-14T11:09:03.067Z","avatar_url":"https://github.com/kiranz.png","language":"JavaScript","readme":"# Just-API\n\n[![npm package](https://nodei.co/npm/just-api.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://www.npmjs.com/package/just-api)\n\n[![Join the chat at https://gitter.im/just-api/Lobby](https://badges.gitter.im/just-api/Lobby.svg)](https://gitter.im/just-api/Lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n[![Twitter](https://img.shields.io/twitter/follow/just_api_.svg?style=social\u0026label=Follow)](https://twitter.com/intent/follow?screen_name=just_api_)\n\n\nJust-API is a declarative, specification based test framework for `REST`, `GraphQL` APIs. Users can test APIs without writing code, but they can also tap into code when they want to. It reads API test specification from YAML files and runs them in serial/parallel mode. Test reports can be generated in several formats including HTML and JSON.\n\u003cbr\u003e\n\nIn simple terms, users build a test suite by providing a set of request and response validation specification in a YAML file. Each suite can have one or more specs. Just-API builds the request, sends it to server and validates response as per the specification.\nOne can choose to validate any or all of following\n\n- Status code\n- Headers\n- Cookies\n- Response JSON body\n- Response JSON schema\n\n_or Provide a custom Javascript function to validate the response_\n\nFind more [here](http://kiranz.github.io/just-api/)\n\u003cbr\u003e\n\n## Codebase visualization diagram\n![Codebase as a diagram](./justapi_diagram.png)\n\n\n## Links\n\n- [Documentation](http://kiranz.github.io/just-api/)\n- [Gitter Chatroom](https://gitter.im/just-api/Lobby)\n- [Google Group](https://groups.google.com/forum/#!forum/just-api)\n- [Issue Tracker](https://github.com/kiranz/just-api/issues)\n\n## Features\n\n- Runs test suites in parallel/serial mode\n- Supports all widely used HTTP methods\n- Supports x-www-form-urlencoded requests, Multipart requests, File uploads\n- Built-in Response Validation Constructs(Headers, Cookies, Status code, JSON body, JSON schema)\n- Custom Response validator functions\n- Supports running custom inline or module javascript sync/async functions\n- Supports Hooks (Before All, After All, Before Each, After Each, Before Test, After Test)\n- Custom suite configuration\n- Chained Request flows\n- Define/override Request path, query params, path params, headers, body at runtime\n- Suite and test context for reuse\n- Supports importing specs from one or more test suites\n- Intrasuite and Intersuite spec dependencies\n- Reusing test specification\n- Retry failed tests\n- Looping: Generate 'n' number of tests with a list\n- Built-in HTML, JSON reporters\n- Can generate reports in multiple formats for the same run\n- Logging HTTP request/response data for failed tests\n- Proper error reporting\n- Can run tests matching with a given pattern/string\n- Skipping tests with specification\n- Disable or Enable redirections\n- Reports test duration\n- Allows user to plug-in custom reporters\n\n[See all features](https://kiranz.github.io/just-api/features/)\n\n\n## Getting Started\n\n\u003eTo run just-api, you will need Node.js v10.x.x or newer.\n\n### Installation\n```sh\n$ npm install just-api\n```\n\nFollowing is a simple example showing usage of Just-API.\n\n```sh\n$ mkdir specs\n$ vim specs/starwars_service.yml\n```\n\nWrite following suite in your editor\n\n```yaml\nmeta:\n  name: Star Wars suite\nconfiguration:\n  scheme: https\n  host: swapi.co\n  base_path: /api\nspecs:\n  - name: get Luke Skywalker info\n    request:\n      path: /people/1/\n      method: get\n    response:\n      status_code: 200\n      headers:\n        - name: content-type\n          value: !!js/regexp application/json     \n      json_data:\n        - path: $.name\n          value: Luke Skywalker\n```\n\nBack in the terminal\n\n```sh\n$ ./node_modules/.bin/just-api\n\n   ✓ get Luke Skywalker info (1216ms)\n\n  Done: specs/starwars_service.yml (Passed)\n\n0 skipped, 0 failed, 1 passed (1 tests)\n0 skipped, 0 failed, 1 passed (1 suites)\nDuration: 1.3s\n```\n\n### Testing GraphQL APIs\n\nFollowing example tests a GraphQL API that returns Person info for a given name.\n\nCreate a YAML suite and run just-api.\n\n```yaml\nmeta:\n  name: GraphQL Starwars service\nconfiguration:\n  host: swapi.graph.cool\n  scheme: https\nspecs:\n  - name: Get Details of a character\n    request:\n      method: post\n      headers:\n        - name: content-type\n          value: application/json\n      payload:\n        body:\n          type: json\n          content:\n            query: \u003e\n                   {\n                    Person(name: \"Luke Skywalker\") {\n                      name,\n                      id,\n                      gender\n                     }\n                    }\n            variables: null\n            operationName: null\n    response:\n      status_code: 200\n      json_data:\n        - path: $.data.Person.name\n          value: \"Luke Skywalker\"\n```\n\n### A chained request flow with hook and custom validation\n\nWhen you need to test complex chained API flows, run dependencies in hooks to fetch pre-requisite data\nand pass it to actual test.\n\nFollowing example shows how to run dependencies using a hook, get data and validating response with a custom validator function.\n\n```yaml\nmeta:\n  name: Starwars suite\nconfiguration:\n  scheme: https\n  host: swapi.co\n  base_path: /api\nspecs:\n  - name: get R2-D2 info\n    request:\n      path: /people/3/\n      method: get\n    response:\n      status_code: 200\n      json_data:\n        - path: $.name\n          value: R2-D2\n\n  - name: search R2-D2 info\n    before_test:\n      run_type: inline\n      inline:\n        function: !js/asyncFunction \u003e\n          async function() {\n            var response = await this.runSpec('get R2-D2 info');\n            var jsonData = JSON.parse(response.body);\n            this.test.query_params = { name:  jsonData.name };\n          }\n    request:\n      path: /people\n      method: get\n    response:\n      status_code: 200\n      custom_validator:\n        run_type: inline\n        inline:\n          function: !!js/function \u003e\n            function() {\n              var jsonData = JSON.parse(this.response.body);\n              var r2d2 = jsonData.results.find(result =\u003e result.name === 'R2-D2');\n\n              if (!r2d2)\n                throw new Error('R2-D2 not returned in search results');\n            }\n```\n\nNote: You can also place custom JS functions in a module and specify the function name, module path in YAML to import.\n\nMore advanced stuff can be done with Just-API. Documentation says it all.\nTake a look at [Just-API Website](http://kiranz.github.io/just-api/) for detailed documentation.\n\nIf you are looking to use Docker to run Just-API, you might want to checkout\nJust-API docker boilerplate [here](https://github.com/kiranz/docker-just-api-sample)\n\n## Maintainer\n\nKiran kiran.6d.hex@gmail.com\n\n## License\n\n[MIT-licensed](https://github.com/kiranz/just-api/blob/master/LICENSE)\n\n## References\n\n - [Just-API, Testing HTTP-based APIs (REST, GraphQL)](https://medium.com/@kiranz.m/testing-http-based-apis-rest-graphql-f215fba989ca)\n\n\n ## Donation\n If this project helps you in anyway, Please consider making a donation\n\n- [Become a backer or sponsor on Patreon](https://www.patreon.com/just_api).\n- [One-time donation via PayPal](https://paypal.me/kiranzm)\n\n## Contributing\n\nNOTE: recommend Node `v10.x` since `v12.x` has gulp compatibility issue.\n\n1. Install deps `npm install`\n2. Install gulp `npm install -g gulp`\n3. Install test files `gulp`\n3. Install test API `npm run install_testapi`\n4. Run test API `npm run start_testapi`\n5. (in a new window) `npm test`\n\n### Test Structure\n\n- `test/cli/src/suites/[suite].spec.yaml` contains sample suites/specs\n- `test/cli/[suite].spec.js` contains JS chai/mocha test assertions about the sample suite/specs\n\nYou may need to create/modify both a sample suite/spec and corresponding JS assertion\n\n### Code Quality \u0026 Formatting\n\nTODO: add linter/hinter/prettier or whatever spec is used\n","funding_links":["https://github.com/sponsors/kiranz","https://www.patreon.com/just_api","https://paypal.me/kiranzm"],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiranz%2Fjust-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkiranz%2Fjust-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiranz%2Fjust-api/lists"}