Skip to main content
Version: 2.0.0

Setting Up Keploy Agent in Apache Karaf for Local Development​

Step 1: Download Required JARs​

Use wget to download the necessary JAR files:

Run the following commands to download the files:

wget https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/KeployAgent.jar
wget https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/org.jacoco.agent-0.8.12-runtime.jar

Step 2: Configure Apache Karaf​

Update JAVA_OPTS for Linux/Mac in setenv File​

  1. Navigate to the bin directory of your Apache Karaf installation.

  2. Open the setenv file for editing.

  3. Add the paths of the downloaded agents under the JAVA_OPTS section. For example:

    export JAVA_OPTS="-javaagent:/path/to/KeployAgent.jar"
    export JAVA_OPTS="$JAVA_OPTS -javaagent:/path/to/org.jacoco.agent-0.8.12-runtime.jar=address=*,port=36320,destfile=jacoco-it.exec,output=tcpserver"

Update JAVA_OPTS for Windows in setenv.bat File​

  1. Navigate to the bin directory of your Apache Karaf installation.

  2. Open the setenv.bat file for editing.

  3. Add the paths of the downloaded agents under the JAVA_OPTS section. For example:

    set JAVA_OPTS=-javaagent:/path/to/KeployAgent.jar
    set JAVA_OPTS=%JAVA_OPTS% -javaagent:/path/to/org.jacoco.agent-0.8.12-runtime.jar=address=*,port=36320,destfile=jacoco-it.exec,output=tcpserver

Set Environment Variables as Java System Properties on Windows​

On Windows, all environment variables should be passed as -D system properties for Java. Update the JAVA_OPTS section in setenv.bat to include the required variables. For example:

set JAVA_OPTS=%JAVA_OPTS% -DAPI_KEY=xRp5nyiQ+B6yltBUpw==
set JAVA_OPTS=%JAVA_OPTS% -DKEPLOY_MODE=RECORD
set JAVA_OPTS=%JAVA_OPTS% -javaagent:/path/to/org.jacoco.agent-0.8.12-runtime.jar=address=*,port=36320,destfile=jacoco-it.exec,output=tcpserver

Replace the placeholder values with actual paths and keys as needed.

Update config.properties​

  1. Navigate to the etc/config.properties file in your Karaf installation.

  2. Add the following entries under the bootdelegation section to allow OSGi bundles to access Keploy artifacts:

    org.osgi.framework.bootdelegation = \
        ... \
        io.keploy.*, \
        javax.servlet, \
        javax.servlet.http

Step 3: Export Environment Variables​

  1. Export the API key specific to your user, as mentioned on Keploy's User Dashboard, which is required for Keploy to function, by running the following command in the same terminal session:

    export API_KEY="<API_KEY>"

    Replace the API_KEY value with your actual API key if different.

  2. Export the application path to point to your target folder containing Java classes:

    export APP_PATH="/Users/path/to/karaf-sample/user-service"

    Replace the APP_PATH value with the absolute path to your application's target folder.

Step 4: Record Test Cases​

  1. Restart Apache Karaf by setting the environment variable KEPLOY_MODE to RECORD:

    export KEPLOY_MODE="RECORD"
    ./karaf

  2. Record test cases using the following command:

    keploy record --base-url="http://localhost:8181"

  3. Make a series of API calls to your application's endpoints.

  4. After completing the API calls, press Ctrl+C in the session where you are running the Keploy binary to stop recording.

Step 5: Or Use Import Postman Collection​

  1. Ensure you have a Postman collection ready for your application.

  2. Run the following command to import the Postman collection as Keploy tests:

    keploy import postman --path="/path/to/YourPostmanCollection.json"

    Replace /path/to/YourPostmanCollection.json with the actual path to your Postman collection.

Step 6: Run Keploy Tests​

  1. Restart Apache Karaf by setting the environment variable KEPLOY_MODE to test:

    export KEPLOY_MODE="test"
    ./karaf

  2. Use the following command to run the imported tests:

    keploy test --base-path="http://localhost:8181"

This assumes your Karaf application is running locally on port 8181.

After running the tests, a coverage.xml file will be generated in the root directory of your project. This file contains the test coverage report, which can be used for further analysis or integrated with CI/CD pipelines.