Comment on page
Writing Test Cases
With apic you not only can you run APIs and view response but also test them by adding test cases for the APIs. You can add test cases to your requests under the Scripts tab in the Request panel. You can add 2 types of scripts; pre-run script which is executed before the request is made and post-run script which is executes after the response is received.
JavaScript is used to write test cases for apic. You can use the popular javascript assertion library chaiJs to write your tests. Apic provides a wide range of API functions to prepare your test cases. See the entire list of functions available in the sections below.
Use apic.test() to write a test which takes 2 arguments, the first one being the name of the test and the second one a function that contains your assertion logic. If the code inside the test function thorws an error/exception then the test is considered to have failed. Otherwise apic considers the test to be passed. Thats how the assertion in chaiJs works.
For example let's say you want to test if the response has a field
id with the value of say 123456. Here is what your test would look like:apic.test('Response should have a field id with value 123456', function(){
expect($response.data).to.have.property("id").and.to.be.equal('123456')
})
Since all the test scripts are evaluated as Javascript, any error in script will stop further tests from getting executed. To avoid such scenarios use
apic.try whenever possible as specified below in this documentApic provides a set of APIs and functions to automate the process of API testing. For example checking the status code, checking if a header is present in the response or not etc.
To test the response and its properties, apic creates a response object named
$response that has below properties.$response {object}- This is the main response object which is created when the run is complete.body {string}- The raw string response data received in the response.data {object}- If the response can be converted to JSON then apic converts it to a JSON object and stores it under the data property of$response. If the response cant be converted to JSON then$response.datawill beundefined. If the API response looks like{"msg":"Todo created", "id":"1oFrKEGzoSX2raFHR8xR", "name":"SEo378VnqzdVsCF"}then you can accessnameby using$response.data.namein your scripts. Same for$response.data.idand$response.data.msg.headers {object}-$response.headersobject holds the list of all headers received in the response as properties and header values as the values for the properties. For example to get the value of Content-Type use$response.headers['Content-Type'].headersStr {string}- The raw string of headers received in the response (by default headers are received as a string separated with '\n').status {number}- The http status code for the response. Ex: 200, 404.statusText {string}- The http status text for the response. Ex OK, Not foundtimeTaken {number}- Time taken for the request to complete in milliseconds.timeTakenStr {stri}- String representation of time taken for the request to complete. Eg: 600 ms.respSize {string}- String representation of response size. Eg:20KB.logs {string[]}- List of log strings added.
You can access the details of the request that was sent by using the
$request variable in your tests. For example the final request url ($request.url) or the value of a request body ($request.body.todoName)$request {object}- The object containing information about the request._id {string}- The request id of saved requests.name {string}- Name of the saved request, undefined if request is not saved.url {string}- This is the final URL to which the request was sent.method {string}- The HTTP method used to send the request.headers {object}- An object containing information about the headers that were sent in the request. For exaample if your request have anauthorizationheader the you can access the value for that in the test with$request.headers['authorization']queryParams {object}- An object containing query parameters sent in the requestbody {object/string}- If your request has a payload body then you can acces that by using$request.bodyin your scripts.- JSON body - If your request payload is a JSON object the apic will automatically convert it to a JSON object and add it to the
$request.bodyobject- String body - If your request payload can't be converted to a JSON then
$request.bodywill be a string. - form-data/x-www-form-urlencoded - If you used form-data/x-www-form-urlencoded to send your payload then they will also be converted to an object and added to body. For example if you send a form data as
name=abcdthen$request.bodywill be an object with value{name: "abcd"} - GraphQL - For graphql requests
$request.bodywill contain both thequeryandvariableswith properties of same name.
Graphql body example:$request.body = {query: "<graphql query string>", variables: {...variables json...}}prescript {string}- Pre-run script.postscript {string}- Post-run script.respCodes- Response schemas saved against each status codes.
Note that APIC converts all headers to lower case before sending it and hence should be accessed with their lower case string from $request.headers.
Eg: Even if you added a header named
Test while accessing it in the $request object you should be using **test** like $request.headers['test']You can use
validateSchema() in yout test scripts to validate if the response is adhering to the specified schema or not. Know more about apic schema validation at https://apic.app/docs/tester/response-schema-validation.htmlExamples:
apic.test("The created ToDo name should match to the one sent in request.", function(){
expect($response.data.name).to.be.eql($request.body.name);
});
apic.test("Check that Status code is 201 (Created)", function(){
expect($response.status).to.be.eql(201);
});
apic.test("Response data should match the schema for status 200", function(){
expect(validateSchema(200)).to.be.eql(true);
});
apic.test("$response.data.message should be equal to \"Todo created successfully\"", function(){
expect($response.data.message).to.be.eql("Todo created successfully");
});
apic.test("$response.data.response.id should exist in response", function(){
expect($response.data.response).to.have.property("id");
})
Sometimes you may need to send dynamic random data while making API calls. We have got you covered. Apic provides a set of functions that you can use while making requests to generate dynamic random data.
apic.randomStr(minLength/length, maxLength)- returns a random string with length betweenminLengthandmaxLength.If maxLength is not specified the the returned string is exactly of lengthminLength. If neither is specified, default 1 character string.apic.randomNum(min, max, isFloat)- generates a random integer number between the min and max value. Sending the third argument isFloat as true will return float/decimal number.apic.randomEmail()- generates valid random email id.apic.randomInList(list)- if you want some random values from a list then you can use this function. This will accept a list of anything and will return one entry from the list randomly. Ex:apic.randomInList([1, 2, 1.111, 'some text', 'etc..']).apic.time()- returns the current timestamp
Since all the test scripts are evaluated as Javascript, any error in script will stop further tests from getting executed. To avoid such scenarios use apic.try whenever possible. Consider below scenario
let name = $response.user.name
log(`User name is: ${name}`)
//If 'user' field is not in response line 1 will throw error
//'Cannot read property 'name' of undefined'
//This will stop below test from getting executed
apic.test("Response has header content-type", function(){
$response.headers.has("Content-Type")
})
Safe way to do this is
//Safe way to do above is
apic.try(()=>{
let name = $response.user.name
log(`User name is: ${name}`)
})
//or use the optional chaining operator (?.)
let name = $response.user?.name
log(`User name is: ${name}`)
//and then
apic.test("Response has header content-type", function(){
$response.headers.has("Content-Type")
})
Whenever possible use the optional chaining operator (
?.) to read the value of a property located deep within a chain of connected objects without having to check that each reference in the chain is valid.Object.has(property, strictMode)- This function can be called on any Object to check if the specified property exists in the object ot not. Returnstrueorfalse. By default the check is done by ignoring the case of the property. If you want to make the check case sensitive pass the second argumentstrictModeastrue. This can be useful to check if a specific header is present in the response or not
Ex:
var obj = {
"name":"user name",
"age":22
}
obj.has("name"); //true
obj.has("Name"); //true
obj.has("Name", true) // false, in strict mode property name are case sensitive
//check if response has specific Header
apic.test("Response has header content-type", function(){
$response.headers.has("Content-Type")
})
Object.getValue(property, strictMode)- This function can be called on any Object to get the value of a specific property. By defaulte value is retrived by ignoring the case but to force case sensitive check send the second parameter striceMode as true. This can be useful to het the value of any specific header or getting values from the response data.
Ex:
var obj = {
"name":"user name",
"age":22
}
obj.getValue('age'); //22
obj.getValue('AGe'); //22
obj.getValue('AGe', true); //undefined
//get the value of content-type header
apic.test("Response header Content-Type is application/json", function(){
expect($response.headers.getValue("content-Type")).to.be.equal("application/json");
})
Last modified 3mo ago