Karate DSL is a tool that allows tests of REST APIs using domain-specific language. With Karate DSL, it’s possible to create tests that verify status and compare response JSON without losing the readability of the spec code. In this article, we will create and configure, step-by-step, a project to run API spec tests. No knowledge of Java is necessary.
Creating a project
We will first need to get the Eclipse IDE. For our purposes, you can download the Eclipse IDE for Java and DSL Developers. Go to File > New > Other…
In the opened window, type “Maven” to search, choose Maven Project, and click Next.
In the next window, select the option Create a simple project (skip archetype selection) and then click Next. We will add the Karate DSL dependencies on Maven after creating the project.
To finish this project’s creation, fill in the Group ID and Artifact ID fields and then click Finish. These are the most basic steps to create a project for the use presented here, but you can do more as needed for additional projects.
Adding Karate DSL
To add the Karate DSL dependencies, right-click on the pom.xml file and choose Open with > Generic Text Editor. We then need to add the dependencies tag and add two dependencies: karate-apache and karate-junit4.
My complete pom.xml looks like this:
4.0.0 com.monteirobrena.karate spec 0.0.1-SNAPSHOT com.intuit.karate karate-apache 0.7.0 test com.intuit.karate karate-junit4 0.7.0 test
Add additional configurations
To add additional configurations in our project, we need to create a file named karate-config.js in the root of src/test/java. To do this, right-click on the src/test/java folder and choose New > File.
On the next screen, fill in File name with karate-config.js and click Finish.
Open the karate-config.js file, and define the URL that you will use to test. I defined a var named apiURL and set a local URL to test. My complete karate-config.js is shown below:
function() {
var config = {
apiURL: 'http://127.0.0.1:3000/pages'
};
karate.configure('connectTimeout', 5000);
karate.configure('readTimeout', 5000);
return config;
}
Creating a class test
Karate DSL recommends creating a folder/package to separate the context of tests. For this example, I created a package named pages, and inside it, I added a new class called PagesRunner.java.
With the right mouse button, click on the package and choose New > Class.
On the next screen, fill in Name with the name of your class. Remember to add the Runner in the final step to associate it with Karate DSL. Then, click on Finish.
The only things we need to put in this class are the imports and the Karate annotation. Your class will look like this:
package api.pages;
import com.intuit.karate.junit4.Karate;
import org.junit.runner.RunWith;
@RunWith(Karate.class)
public class PagesRunner {
}
Creating the specs
Again, with the right mouse button, click on the package and choose New > File to create a feature file of Karate DSL.
On the next screen, fill in the File name with a name of your file as pages-get.feature and then click on Finish.
And now for the most important step of this article, which is the definition of our tests. We will call an API request in the URL that we set in the karate-config.js and compare the result with the expected JSON.
Feature: API test with Karate DSL
Scenario: Verify return of pages
Given url apiURL
When method get
Then status 200
And match response == read(‘page.json’)
To run our test, right-click on PagesRunner.java and choose Run As > JUnit Test. But before the run, verify if your service set in the karate-config.js is running and accepting GET requests.
The spec fails because we have not created a JSON file yet!
To fix it, right-click on the pages package and choose New > File. In the next window, type page.json in the File name field, and then click on Finish. You need to paste the expected JSON inside your page.json and try to run the test again. Now, the test will be successful.
Karate DSL will generate an HTML file with a view of the test results, which can be accessed in: ~/eclipse-workspace/spec/target/surefire-reports/TEST-api.pages.pages-get.html
Conclusion
Perhaps you know of other solutions to test your APIs, but try Karate DSL as an option to quickly start and run your tests. A test team without deep programming knowledge can maintain specs created with Karate DSL because of the facility of the domain language. It is very useful for documentation of APIs as well (even before development) which is a great thing.
