Package: rest-api-tester
Python REST API TesterInstallationpip install rest-api-testerThis is available for Python3.7+Aboutrest-api-testermakes it easy to create REST API tests for your APIs.
Though this tool is written in Python, your APIs need not be. This library provides a consistent way to write API tests
and perform the necessary validation. It is primarily built to handle traditional, JSON-based APIs, although it has
the ability to handle other API formats. Also...rest-api-testercan auto-update your scenario files for you when
tests fail!TutorialCreate a test cases file named__scenarios__/test_something.json{"create_something":{"url":"/something","method":"POST","status":200,"request":{"name":"something"},"response":{"id":1,"name":"something"}}}Create a unit test classfromrest_api_tester.testimportTestCaseclassTestSomething(TestCase):...Create a test client implementation (seeherefor an example)Set up your test case runnerimportosfromrest_api_testerimportTestCase,TestCaseRunner<importyourTestClientclasshere>classTestSomething(TestCase):defsetUp(self)->None:test_client=TestClient(base_url='https://myapp.com:5000')path_to_scenarios_dir=os.path.join(os.path.dirname(__file__),'__scenarios__')self.runner=TestCaseRunner(client=test_client,path_to_scenarios_dir=path_to_scenarios_dir,default_content_type='application/json')Create your first API testclassTestSomething(TestCase):...deftest_create_something(self)->None:result=self.runner.run(path_to_test_cases='test_something.json',test_name='create_something')self.verify_test_result(result=result)Add a more complicated test{"update_something":{"description":"Make sure PUT /something/{id} returns a 200","url":"/something/{id}","method":"PUT","status":200,"request":{"name":"something","alias":"$$$"},"response":{"id":"$$$","name":"something","alias":"$$$","created_date":"$$$"}}}importdatetimeclassTestSomething(TestCase):...deftest_update_something(self)->None:new_alias='something_else'something_id=create_something()# assume this function already existsresult=self.runner.run(path_to_test_cases='test_something.json',test_name='update_something',# Fill in URL variables at runtimeurl_params={'id':something_id},# Modify request data at runtimerequest_json_modifiers={'alias':new_alias},# Modify expected response data at runtimeresponse_json_modifiers={'id':something_id,'alias':new_alias,'created_date':str(datetime.datetime.now().date())})self.verify_test_result(result=result,# Exclude some response fields from validationexcluded_response_paths=['some_response_field_i_can_ignore'])Summaryrest-api-testermakes API testing easier for APIs based on JSON and plain-text formats.Scenario FilesTest scenarios are written in external files.
A scenario specifies the request to be made and expected response details (i.e. content, headers, and status).API ClientYou must implement your own client as a subclass ofrest_api_tester.client.base_client.BaseClientto make the API requests.
Seeherefor an example.Test Case RunnerTo run your test cases, you must userest_api_tester.runner.TestCaseRunner.
This class parses your test scenario files and uses your client implementation to make the necessary API requests.
A JSON parser is provided as a default to parse your test scenario files.
A scenario files can contain one or more test scenarios, each with a specific key that can be referenced in code.
Custom parsers can be created and passed toTestCaseRunner.Test CaseAll test cases are built upon python'sunittest. Your test case classes should inherit fromrest_api_tester.test.TestCase.
This base class provides the functionality to verify test results fromrest_api_tester.runner.TestCaseRunner.
To do this, you will pass the test results fromTestCaseRunnertoTestCase.verify_test_result.
The default response content verifier should work for most cases, but a custom verifier function can be used via theverifierparam.Modifying Scenarios at RuntimeIn many instances, URLs, request data, and expected response data need to be modified at runtime.
For example, you may create an entity, but its ID or creation date are not known until runtime.
Another use case is authentication. For example, you may generate a login cookie at runtime, which can be used to augment your request.
Thus, your test scenarios need to be augmented.rest-api-testeroffers various ways to handle such cases.You can modify scenario URLs at runtime by usingurl_paramsfromTestCaseRunner.run.If your URL is/something/{id}, you can useurl_params={'id': 123}to substitute123in for{id}.You can modify your scenario request JSON data at runtime by usingrequest_json_modifiersfromTestCaseRunner.run.You can provide a dict of JSON paths and, for each, a value.The JSON path format supported is a simple one that can be easily understood via the test caseshere.Note that this is similar but not quite the same as JsonPath expressions (e.g.https://github.com/json-path/JsonPath)For example,{'a.[1].b.*c': 3}will modify setitem['c'] = 3for all items ofrequest_json['a'][1]['b'].Similarly, you can modify your scenario expected response JSON data at runtime by usingresponse_json_modifiersfromTestCaseRunner.run.You can also modify request headers and expected response headers at runtime by usingrequest_header_modifiersandresponse_header_modifiersfromTestCaseRunner.run.If you want to exclude some response fields from verification, you can useexcluded_response_pathsfromTestCase.verify_test_resultThis will be a list of the same kind of JSON paths fromrequest_json_modifiersandresponse_json_modifiers.This can be useful if certain fields from the response can't be easily known at runtime.If you'd like more fine-grained, programmatic control over test scenario data before a test is actually run, you can usetest_data_modifierfromTestCaseRunner.run.This requires passing a function (or list of functions) which accepts aTestDataparameter and returns the modifiedTestData.TheTestDataobject contains all the parsed test scenario data before the test has been executed (i.e. the client has made an API call).This can be used to add authentication headers/cookies that may not be known until runtime.Auto-updating Scenario Files on Failrest-api-testercan also auto-update your scenario files for you when tests fail.
For example, if you run your tests, but your response data does not match,rest-api-testercan automatically update the scenario's expected response details based on what the actual API response was.
This can be done in one of the following ways:Settingself.update_scenarios_on_fail = TrueinTestCase.setup.Passingupdate_scenarios_on_fail = TruetoTestCase.verify_test_resultYou can modify the default behavior ofupdate_scenarios_on_failby settingself.update_scenarios_on_fail_optionsinTestCase.setUpor by passingupdate_scenarios_on_fail_optionstoTestCase.verify_test_result.Please note that scenario files can become corrupted if tests run in parallel and update the same file.
Corruption can also happen if the tests are force-killed in the middle of writing to scenario files.Not SupportedAPIs based on data formats other than JSON and plain textIt's possible other formats could be used, but it would likely require more workaround and effortFile uploadsSOAPWebsocketsRPCExamplesYou can find more advanced API test exampleshere.Note: The examples provided are run against a FastAPI server, and thus need Python3.7+ to run.