Keploy is a no-code testing platform that generates tests from API calls.
This is the client SDK for Keploy API testing platform. There are 2 modes:
- Record mode
- Record requests, response and all external calls and sends to Keploy server.
- It runs the request on the API again to identify noisy fields.
- Sends the noisy fields to the keploy server to be saved along with the testcase.
- Test mode
- Fetches testcases for the app from keploy server.
- Calls the API with same request payload in testcase.
- Validates the respones and uploads results to the keploy server
The Keploy Java SDK helps you to integrate keploy with java applications. (For other languages, see KEPLOY SDKs)
- Java 1.8+
Find the latest release of the Keploy Java SDK at maven central.
Add keploy-sdk as a dependency to your pom.xml:
<dependency>
<groupId>io.keploy</groupId>
<artifactId>keploy-sdk</artifactId>
<version>N.N.N</version> (eg: 1.2.9)
</dependency>
or to build.gradle:
implementation 'io.keploy:keploy-sdk:N.N.N' (eg: 1.2.9)
There are 3 modes:
- Record: Sets to record mode.
- Test: Sets to test mode.
- Off: Turns off all the functionality provided by the API
Note: KEPLOY_MODE
value is case sensitive.
-
Start keploy server refer
-
For Spring based application
- Add
@Import(KeployMiddleware.class)
below@SpringBootApplication
in your main class.
- Add
-
For Java EE application
- Specify the below filter above all other filters and servlets in the web.xml file.
<filter> <filter-name>middleware</filter-name> <filter-class>io.keploy.servlet.KeployMiddleware</filter-class> </filter> <filter-mapping> <filter-name>middleware</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>
- Specify the below filter above all other filters and servlets in the web.xml file.
-
Run along with agent to mock external calls of your API π€©π₯
-
Download the latest - Download the latest agent jar from here (eg: 1.2.9)
-
Prefix
-javaagent:
with absolute classpath of agent jar ( eg:-javaagent:<your full path to agent jar>/agent-1.2.9.jar
).-
Using Intellij: Go to Edit Configuration-> add VM options -> paste java agent edited above.
-
Using command line:
- First add below plugins in your pom.xml file.
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-dependency-plugin</artifactId> <version>3.1.1</version> <executions> <execution> <id>copy-dependencies</id> <phase>package</phase> <goals> <goal>copy-dependencies</goal> </goals> </execution> </executions> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jar-plugin</artifactId> <version>3.2.2</version> <configuration> <archive> <manifest> <addClasspath>true</addClasspath> <classpathPrefix>dependency/</classpathPrefix> <mainClass>{your main class}</mainClass> </manifest> </archive> </configuration> </plugin>
- And then run this
command:
java -javaagent:<your full path to agent jar>/agent-1.2.9.jar -jar <your full path to application jar>.jar
. This command will attach agent jar and also run the application. You need to set some required env variables written below in order to generate test cases. So, run this command after setting the env variables.
-
-
-
Configure Environment Variables
APP_NAME
(default APP_NAME = myApp)APP_PORT
(default APP_PORT = 8080)DELAY
(default DELAY = 5)(It is the estimate application startup time (in sec))KEPLOY_URL
(default KEPLOY_URL = https://localhost:6789/api)KEPLOY_MODE
(default KEPLOY_MODE = off)KEPLOY_TEST_PATH
(default /src/test/e2e/keploy-tests directory of your application)KEPLOY_MOCK_PATH
(default /src/test/e2e/mocks directory of your application)KEPLOY_ASSET_PATH
(default /src/test/e2e/assets directory of your application)DENOISE
(default DENOISE = false) Note: By enabling denoise, it will filter out noisy fields for the testcase.RUN_TEST_BEFORE_RECORD
(default RUN_TEST_BEFORE_RECORD = false) Note: It is used to maintain the same database state when mocking is disabled.ACCEPT_URL_REGEX_LIST
(default ACCEPT_URL_REGEX_LIST = []) Note: A list of regex which is used to filter out the urls which are required to be recorded and by default it is empty list. e.g.,ACCEPT_URL_REGEX_LIST=^/apiACCEPT_HEADER_REGEX_LIST
(default ACCEPT_HEADER_REGEX_LIST = []) Note: A list of regex which is used to filter out the headers which are required to be recorded and by default it is empty list. e.g.,ACCEPT_HEADER_REGEX_LIST=token:bearer tgffd,content-type\s*:\s*application\/jsonREJECT_URL_REGEX_LIST
(default REJECT_URL_REGEX_LIST = []) Note: A list of regex which is used to filter out the urls which are not required to be recorded and by default it is empty list. e.g.,REJECT_URL_REGEX_LIST=^/assetsREJECT_HEADER_REGEX_LIST
(default REJECT_HEADER_REGEX_LIST = []) Note: A list of regex which is used to filter out the headers which are not required to be recorded and by default it is empty list. e.g.,REJECT_HEADER_REGEX_LIST=token:token tgffd,content-length:\s*:\s*"100"SKIP_MOCK_OKHTTP
for okhttp service to be mocked or not (default SKIP_MOCK_OKHTTP = false)SKIP_MOCK_APACHE
for apache service to be mocked or not (default SKIP_MOCK_APACHE = false)SKIP_MOCK_GOOGLE_MAPS
for google_maps service to be mocked or not (default SKIP_MOCK_GOOGLE_MAPS = false)SKIP_MOCK_SQL
for sql service to be mocked or not (default SKIP_MOCK_SQL = false)SKIP_MOCK_REDIS
for redis service to be mocked or not (default SKIP_MOCK_REDIS = false)
-
Generate testcases
- To generate/capture TestCases set and run your application.
- Set
KEPLOY_MODE = record
(default "off") - Run your application.
- Make some API calls.
- Set
- To generate/capture TestCases set and run your application.
-
Run the testcases
-
Note: Before running tests stop the sample application.
- Set
KEPLOY_MODE = test
(default "off")-
Using IDE: (for local use-case we prefer running tests via IDE)
- Run your application.
- You can also run the application with coverage to see the test coverage.
-
If you want to run keploy tests along with other unit testcases. You will be required to set the
javaagent
again in your test profile just like below.-
Add below code in your testfile and run it with or without coverage.
@Test public void TestKeploy() throws InterruptedException { CountDownLatch countDownLatch = HaltThread.getInstance().getCountDownLatch(); Mode.setTestMode(); new Thread(() -> { <Your Application Class>.main(new String[]{""}); countDownLatch.countDown(); }).start(); countDownLatch.await(); assertTrue(AssertKTests.result(), "Keploy Test Result"); }
-
Using command line
-
Add maven-surefire-plugin to your pom.xml. In
<argLine> </argLine>
don't add jacoco agent if you don't want coverage report.<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <version>2.22.2</version> <configuration> <!-- <skipTests>true</skipTests> --> <argLine> -javaagent:<your full path to agent jar>.jar -javaagent:${settings.localRepository}/org/jacoco/org.jacoco.agent/0.8.7/org.jacoco.agent-0.8.7-runtime.jar=destfile=target/jacoco.exec--> </argLine> <systemPropertyVariables> <jacoco-agent.destfile>target/jacoco.exec </jacoco-agent.destfile> </systemPropertyVariables> </configuration> </plugin>
-
If you want coverage report also add Jacoco plugin to your pom.xml.
<plugin> <groupId>org.jacoco</groupId> <artifactId>jacoco-maven-plugin</artifactId> <version>0.8.5</version> <executions> <execution> <id>prepare-agent</id> <goals> <goal>prepare-agent</goal> </goals> </execution> <execution> <id>report</id> <phase>prepare-package</phase> <goals> <goal>report</goal> </goals> </execution> <execution> <id>post-unit-test</id> <phase>test</phase> <goals> <goal>report</goal> </goals> <configuration> <!-- Sets the path to the file which contains the execution data. --> <dataFile>target/jacoco.exec</dataFile> <!-- Sets the output directory for the code coverage report. --> <outputDirectory>target/my-reports</outputDirectory> </configuration> </execution> </executions> </plugin>
-
Run your tests using command :
mvn test
.
-
-
-
- Set
-
- Java-sdk also supports mocking feature for unit testcase, where you write your own unit test cases and use keploy generated mocks as stubs.
- Set
javaagent
in your unit test file configuration. - You just need to set the name of the mock as shown below.
@Test
public void testHttpCall() throws Exception {
new MockLib("okhttpCall"); //setting name of the mock
``` your unit test case code goes here ```
}
-
You can also provide location where your mocks can be stored using
KEPLOY_MOCK_PATH
. (default /src/test/e2e/mocks directory of your application) -
Generate mocks
- Record mocks by setting
KEPLOY_MODE=record
and run your test file. - You will be able to see editable and readable mocks at your provided location.
- Record mocks by setting
-
Run your unit testcases
- Just set
KEPLOY_MODE=test
, run your test file and you are good to go.
- Just set
π€© See, you didn't even need to create a stub for your unit test cases, it's all generated using the java-sdk mock library.
We'd love to collaborate with you to make Keploy great. To get started: