From b7dadf6c0378d2d07d9163ddba3f640234daaaf3 Mon Sep 17 00:00:00 2001 From: Swapnoneel Saha <121167506+Swpn0neel@users.noreply.github.com> Date: Fri, 3 Jan 2025 11:32:53 +0530 Subject: [PATCH 1/7] Updated the FAQ section and Added a new "Common Errors" section (#469) * updated slack url Signed-off-by: Swapnoneel Saha * updated the faq section Signed-off-by: Swapnoneel Saha * added common errors section Signed-off-by: Swapnoneel Saha * added detailed text and images Signed-off-by: Swapnoneel Saha --------- Signed-off-by: Swapnoneel Saha Co-authored-by: Animesh Pathak <53110238+Sonichigo@users.noreply.github.com> --- sidebars.js | 1 + .../keploy-explained/common-errors.md | 202 ++++++++++++++++++ .../version-2.0.0/keploy-explained/faq.md | 51 +++-- .../version-2.0.0-sidebars.json | 3 +- 4 files changed, 237 insertions(+), 20 deletions(-) create mode 100644 versioned_docs/version-2.0.0/keploy-explained/common-errors.md diff --git a/sidebars.js b/sidebars.js index bc95d6fcd..ca2aa8b38 100644 --- a/sidebars.js +++ b/sidebars.js @@ -11,6 +11,7 @@ module.exports = { "keploy-explained/how-keploy-works", "keploy-explained/why-keploy", "keploy-explained/faq", + "keploy-explained/common-errors", ], }, { diff --git a/versioned_docs/version-2.0.0/keploy-explained/common-errors.md b/versioned_docs/version-2.0.0/keploy-explained/common-errors.md new file mode 100644 index 000000000..e8fa350d5 --- /dev/null +++ b/versioned_docs/version-2.0.0/keploy-explained/common-errors.md @@ -0,0 +1,202 @@ +--- +id: common-errors +title: Common Errors in Keploy +sidebar_label: Common Errors +tags: + - explanation + - faq +--- + +Let's check some of the common errors that you might encounter while working with Keploy! + +[](https://camo.githubusercontent.com/74cbc79070c04e7077cfd86981c110678fe434e9269ea8f52eafb37b781cfb4a/68747470733a2f2f646f63732e6b65706c6f792e696f2f696d672f6b65706c6f792d6c6f676f2d6461726b2e7376673f733d32303026763d34) + +### 1. Dependency Not Found Error + +#### Description: + +This error occurs when Keploy cannot locate or access a required dependency, such as a database or external service. + +#### Possible Cause: + +- The dependency may not be running or is incorrectly configured. +- Networking issues may be preventing Keploy from connecting to external dependencies. + +#### Solution: + +- Verify that all required services (e.g., databases, third-party APIs) are active and accessible. +- Check the environment variables or configuration files to confirm the correct host and port details. +- Use network diagnostic tools (e.g., ping, traceroute) to identify connectivity issues. + +### 2. Unable to Record API Calls + +#### Description: + +Keploy fails to record incoming API traffic, meaning no tests are generated. + +#### Possible Cause: + +- Incorrect integration with the application. +- Keploy may not be correctly started with the application, or the SDK is not configured properly. +- The application may not be making API calls that are recognizable by Keploy. + +#### Solution: + +- Double-check the integration guide for the programming language you’re using. +- Ensure that Keploy is properly hooked into the API layer. +- Check Keploy logs for any missed or skipped requests. + +### 3. Test Replay Failure + +#### Description: + +Keploy is unable to replay recorded API requests. + +#### Possible Cause: + +- External services or databases may be in a different state than they were during recording. +- Non-deterministic values like timestamps, UUIDs, or random values are causing failures. + +#### Solution: + +- Leverage Keploy’s mocking capabilities to simulate external services and databases. +- Use configurations to handle or exclude non-deterministic values for consistent comparisons. +- Regularly reset the database state to match the conditions during recording. + +### 4. Response Mismatch Error + +#### Description: + +When Keploy replays API calls, it detects a mismatch between the recorded response and the current response. + +#### Possible Cause: + +- The application’s behavior has changed, leading to different responses. +- Changes in the response format, status codes, or headers that weren’t present during recording. + +#### Solution: + +- Review the application changes and determine if the mismatch is expected (e.g., new features). +- If the change is acceptable, update the test baseline to reflect the new behavior. +- Use Keploy’s flexible comparison options to ignore certain fields or values (like timestamps or version numbers). + +### 5. Incorrect Test Generation + +#### Description: + +Keploy generates tests that don’t properly reflect the API interactions. + +#### Possible Cause: + +- The API interaction may be too complex or involve custom logic that Keploy cannot automatically handle. +- API parameters may be missing or misinterpreted during recording. + +#### Solution: + +- Review the recorded test cases for correctness. +- Manually adjust the generated tests to include missing or misinterpreted parameters. +- Make use of Keploy’s API to refine the recording process if necessary. + +### 6. Database Connection Error during Test Replay + +#### Description: + +Keploy cannot connect to the database or other external systems during the replay of tests. + +#### Possible Cause: + +- The test environment may not have access to the same database as the original recording. +- Database credentials or host information could be incorrect or missing in the test environment. + +#### Solution: + +- Mirror the test environment configuration with the recording setup. +- Use database mocks or stubs for isolated testing. +- Double-check connection strings, credentials, and database availability. + +### 7. Missing or Invalid Configuration Error + +#### Description: + +Keploy cannot find a valid configuration file or encounters errors in the configuration. + +#### Possible Cause: + +- The Keploy configuration file (keploy.yaml or similar) is missing or contains invalid values. +- Environment variables required by Keploy may not be set. + +#### Solution: + +- Ensure the configuration file exists and follows the correct format. +- Populate all required fields with valid values. +- Check that environment variables are properly set. + +### 8. Timeout Errors + +#### Description: + +Keploy times out while recording or replaying API calls. + +#### Possible Cause: + +- Long-running API requests or slow external dependencies can cause timeout issues. +- Keploy may have low timeout settings for API calls. + +#### Solution: + +- Increase timeout settings in the Keploy configuration. +- Identify and optimize slow-performing APIs or dependencies. +- Use monitoring tools to analyze API performance. + +### 9. Insufficient Permissions + +#### Description: + +Keploy fails due to insufficient permissions when accessing files, networks, or other resources. + +#### Possible Cause: + +The user or service running Keploy may not have sufficient permissions to access resources like databases, APIs, or file systems. + +#### Solution: + +- Ensure that the user or service running Keploy has the necessary permissions. +- Review system permissions and provide the required access rights for Keploy to function properly. + +### 10. Version Compatibility Issues + +#### Description: + +Errors occur because of version mismatches between Keploy, its dependencies, or the application it’s testing. + +#### Possible Cause: + +- Using incompatible versions of Keploy or related SDKs with your application. +- Dependencies of Keploy (e.g., for mocking or replaying) may have updated and broken compatibility. + +#### Solution: + +- Verify version compatibility for Keploy and its SDKs. +- Consult Keploy documentation or release notes for known issues. +- Use version pinning to maintain a stable environment. + +### 11. Unsupported Protocol or API + +#### Description: + +Keploy does not support the protocol or API structure you are using (e.g., gRPC, SOAP, etc.). + +#### Possible Cause: + +- The application might use an API or protocol that Keploy doesn’t yet support (e.g., WebSocket, gRPC). + +#### Solution: + +- Confirm the supported protocols (currently HTTP/REST and GraphQL). +- Consider alternative tools or frameworks for unsupported protocols. + +If you’re still encountering issues after trying these solutions, feel free to reach out to the Keploy team or consult the community forums for additional support. Happy testing! + +import GetSupport from '../concepts/support.md' + + diff --git a/versioned_docs/version-2.0.0/keploy-explained/faq.md b/versioned_docs/version-2.0.0/keploy-explained/faq.md index b8522e0e1..d37749ce4 100644 --- a/versioned_docs/version-2.0.0/keploy-explained/faq.md +++ b/versioned_docs/version-2.0.0/keploy-explained/faq.md @@ -9,43 +9,56 @@ tags: Let's get to the heart of Keploy with some fun Q&A! -### 1. Is Keploy a unit testing framework? +### 1. What is Keploy? -Nope, doesn't replace your trusty unit testing frameworks like `go-test`, `JUnit`, `Pytest`, or `Jest`. Instead, it teams up with them to make your testing life a breeze, ensuring compatibility with your favorite tools and pipelines. +Keploy is an open-source testing platform designed to automatically generate test cases from existing API traffic. It allows users to record, replay, and compare API interactions, making it easier to write and maintain test suites. -### 2. Does Keploy replace unit tests entirely? +### 2. How does Keploy work? -Almost! Keploy aims to save you a whopping 80% of the testing effort. While it handles most cases, you might still want to write tests for some methods that aren't API-invokable. +Keploy works by recording incoming API calls during normal operations. It then replays these interactions in a test environment and compares the results to the initial responses to detect regressions or unexpected behavior in the code. -### 3. What code changes do I need to do? +### 3. Does Keploy support mocking? -Zero, zip, nada! For `Golang`, `Java`, `Python`, and `JavaScript` applications, Keploy plays nice with your existing codebase, requiring no code changes. +Yes, Keploy allows mocking external dependencies like databases and third-party services during test execution to ensure that tests run in isolation without relying on external systems. -### 4. How do I run keploy in my CI pipeline? +### 4. What are the prerequisites for using Keploy? -Simple as pie. No need to overhaul your CI pipeline; you can keep using the one that runs your unit tests. Keploy fits right in! +To use Keploy, you need: -### 5. Does Keploy support read after write to DB scenarios? +- A service or application that exposes APIs (e.g., REST or GraphQL). +- Keploy supports programming languages like Go, Node.js, Python, and Java, so the appropriate SDK for your environment should be installed. -Absolutely! Keploy keeps things in order, recording write and read requests in sequence. It expects your application to play by the rules and serves up the same database responses as it did during capture. +### 5. Is Keploy suitable for microservices architecture? -### 6. How does keploy handle fields like timestamps, random numbers (eg: uuids)? +Yes, Keploy is designed to work in microservices-based environments. It can record and replay API calls across services, making it ideal for testing distributed systems. -Keploy's got a keen eye for detail. If a request passes its deduplication algorithm, it's game time. Keploy sends a second request with the same parameters to check for differences in responses. Fields like timestamps and UUIDs get the spotlight as they're automatically flagged for comparison. From then on, they're out of the testing picture. +### 6. Does Keploy require code changes to integrate? -### 7. Can I use keploy to generate tests from production environments automatically? +Keploy can be integrated without any changes to the application code. However, adding Keploy SDKs may offer more fine-grained control for specific use cases. -Not just yet, but we're on it! We're cooking up a scalable deduplication algorithm to make it safe for production. If you're itching to explore this frontier, come chat with us on Slack. We'd love to join forces and put our system to the test with your systems. +### 7. Can Keploy help with CI/CD pipelines? -### 8. What if my application behaviour changes? +Yes, Keploy integrates with CI/CD pipelines to run automated tests on every commit or code change. This ensures that any regressions are detected early in the development process. -Change is the only constant in the tech world, right? If your app decides to switch things up, your test cases might break. No worries; you can mark the new behavior as normal. +### 8. Is Keploy scalable for large projects? -Got more questions? We're all ears (and code)👂. +Keploy is designed to be scalable. It can handle high traffic volumes and complex services in large-scale distributed systems. It is efficient for generating and managing test cases across services. - +Yes, Keploy can be used to test legacy systems, especially if they expose APIs. It can record traffic and replay calls without needing to modify the legacy codebase. + +### 10. Can Keploy be used with databases? + +Yes, Keploy can mock database responses during test replay. This helps isolate tests and ensures consistency during test execution. + +### 11. Is Keploy free to use? + +Yes, Keploy is open-source and free to use under the Apache 2.0 license. You can also contribute to its development on GitHub. + +### 12. Can I customize Keploy's behavior for specific APIs? + +Yes, Keploy provides configuration options to customize recording, replay, and comparison logic for specific APIs, giving users control over how their APIs are tested. Hope this helps you out, if you still have any questions, reach out to us . diff --git a/versioned_sidebars/version-2.0.0-sidebars.json b/versioned_sidebars/version-2.0.0-sidebars.json index a602fba3d..eeb3b3c20 100644 --- a/versioned_sidebars/version-2.0.0-sidebars.json +++ b/versioned_sidebars/version-2.0.0-sidebars.json @@ -164,7 +164,8 @@ "dependencies/postgres", "dependencies/http", "dependencies/redis", - "keploy-explained/faq" + "keploy-explained/faq", + "keploy-explained/common-errors" ] } ], From fcbd867a8e76dd8455877d1acb7c92b2dd29833e Mon Sep 17 00:00:00 2001 From: Sarthak Shyngle <50234097+Sarthak160@users.noreply.github.com> Date: Mon, 13 Jan 2025 19:55:51 +0530 Subject: [PATCH 2/7] feat: add steps to run keploy in karaf (#484) * feat: add steps to run keploy in karaf Signed-off-by: Sarthak Shyngle <50234097+Sarthak160@users.noreply.github.com> * refactor: update the karaf steps Signed-off-by: Sarthak160 * refactor: update the karaf steps Signed-off-by: Sarthak160 * refactor: update the karaf steps Signed-off-by: Sarthak160 --------- Signed-off-by: Sarthak Shyngle <50234097+Sarthak160@users.noreply.github.com> Signed-off-by: Sarthak160 Co-authored-by: Neha Gupta --- .../running-keploy/keploy-karaf.md | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md diff --git a/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md b/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md new file mode 100644 index 000000000..8a1ce8a65 --- /dev/null +++ b/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md @@ -0,0 +1,136 @@ +--- +id: keploy-karaf-example +title: Keploy Karaf Example +sidebar_label: Keploy Karaf Example +description: This section documents how to run keploy with Karaf +tags: + - keploy + - keploy karaf +keywords: + - keploy + - documentation + - running-guide +--- + +# Setting Up Keploy Agent in Apache Karaf for Local Development + +Follow these steps to set up and run the Keploy agent in Apache Karaf for your local development environment. + +--- + +## Step 1: Download Required JARs + +Use `wget` to download the necessary JAR files: + +- [java-agent-1.0-SNAPSHOT.jar](https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/java-agent-1.0-SNAPSHOT.jar) +- [org.jacoco.agent-0.8.12-runtime.jar](https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/org.jacoco.agent-0.8.12-runtime.jar) + +Run the following commands to download the files: + +```bash +wget https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/java-agent-1.0-SNAPSHOT.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: + + ```bash + export JAVA_OPTS="-javaagent:/path/to/java-agent-1.0-SNAPSHOT.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: + + ```bash + set JAVA_OPTS=-javaagent:/path/to/java-agent-1.0-SNAPSHOT.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 + ``` + + Replace `/path/to/` with the actual paths where you downloaded the JAR files. + +### Update `config.properties` + +1. Navigate to the `etc/config.properties` file in your Karaf installation. +2. Add the following entry under the `bootdelegation` section to allow OSGi bundles to access Keploy artifacts: + + ```properties + org.osgi.framework.bootdelegation = \ + com.sun.*, \ + javax.transaction, \ + javax.transaction.xa, \ + javax.xml.crypto, \ + javax.xml.crypto.*, \ + javax.security.cert, \ + jdk.nashorn.*, \ + sun.*, \ + jdk.internal.reflect, \ + jdk.internal.reflect.*, \ + org.apache.karaf.jaas.boot, \ + org.apache.karaf.jaas.boot.principal, \ + io.keploy.* + ``` + +--- + +## Step 3: Start Apache Karaf and Export Environment Variables + +1. Start Apache Karaf by navigating to the `bin` directory and running: + + ```bash + ./karaf + ``` + +2. Export the API key required for Keploy to function by running the following command in the same terminal session: + + ```bash + export API_KEY="" + ``` + + Replace the `API_KEY` value with your actual API key if different. + +3. Export the application path to point to your target folder containing Java classes: + + ```bash + export APP_PATH="/Users/sarthak_1/Downloads/karaf-sample/user-service" + ``` + + Replace the `APP_PATH` value with the absolute path to your application's target folder. + +--- + +## Step 4: 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: + + ```bash + keploy import postman --path="/path/to/YourPostmanCollection.json" + ``` + + Replace `/path/to/YourPostmanCollection.json` with the actual path to your Postman collection. + +--- + +## Step 5: Run Keploy Tests + +Use the following command to run the imported tests: + +```bash +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. From b40a90e1e6f17fdb3d68d397ee49182ec61cdf23 Mon Sep 17 00:00:00 2001 From: Neha Gupta Date: Mon, 13 Jan 2025 20:08:17 +0530 Subject: [PATCH 3/7] chore: remove extra spaces --- .../version-2.0.0/running-keploy/keploy-karaf.md | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md b/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md index 8a1ce8a65..eceafbab3 100644 --- a/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md +++ b/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md @@ -1,6 +1,6 @@ --- id: keploy-karaf-example -title: Keploy Karaf Example +title: Setting Up Keploy Agent in Apache Karaf for Local Development sidebar_label: Keploy Karaf Example description: This section documents how to run keploy with Karaf tags: @@ -12,12 +12,6 @@ keywords: - running-guide --- -# Setting Up Keploy Agent in Apache Karaf for Local Development - -Follow these steps to set up and run the Keploy agent in Apache Karaf for your local development environment. - ---- - ## Step 1: Download Required JARs Use `wget` to download the necessary JAR files: @@ -32,8 +26,6 @@ wget https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/java-agent- 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 @@ -82,8 +74,6 @@ wget https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/org.jacoco. io.keploy.* ``` ---- - ## Step 3: Start Apache Karaf and Export Environment Variables 1. Start Apache Karaf by navigating to the `bin` directory and running: @@ -108,8 +98,6 @@ wget https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/org.jacoco. Replace the `APP_PATH` value with the absolute path to your application's target folder. ---- - ## Step 4: Import Postman Collection 1. Ensure you have a Postman collection ready for your application. @@ -121,8 +109,6 @@ wget https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/org.jacoco. Replace `/path/to/YourPostmanCollection.json` with the actual path to your Postman collection. ---- - ## Step 5: Run Keploy Tests Use the following command to run the imported tests: From 1a83d339c1c52adfb8734eba01bac0e5dc9144bb Mon Sep 17 00:00:00 2001 From: Sarthak Shyngle <50234097+Sarthak160@users.noreply.github.com> Date: Mon, 13 Jan 2025 23:53:48 +0530 Subject: [PATCH 4/7] Update keploy-karaf.md Signed-off-by: Sarthak Shyngle <50234097+Sarthak160@users.noreply.github.com> --- .../version-2.0.0/running-keploy/keploy-karaf.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md b/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md index eceafbab3..136b7ee11 100644 --- a/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md +++ b/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md @@ -16,13 +16,13 @@ keywords: Use `wget` to download the necessary JAR files: -- [java-agent-1.0-SNAPSHOT.jar](https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/java-agent-1.0-SNAPSHOT.jar) +- [KeployAgent.jar](https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/KeployAgent.jar) - [org.jacoco.agent-0.8.12-runtime.jar](https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/org.jacoco.agent-0.8.12-runtime.jar) Run the following commands to download the files: ```bash -wget https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/java-agent-1.0-SNAPSHOT.jar +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 ``` @@ -35,7 +35,7 @@ wget https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/org.jacoco. 3. Add the paths of the downloaded agents under the `JAVA_OPTS` section. For example: ```bash - export JAVA_OPTS="-javaagent:/path/to/java-agent-1.0-SNAPSHOT.jar" + 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" ``` @@ -46,7 +46,7 @@ wget https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/org.jacoco. 3. Add the paths of the downloaded agents under the `JAVA_OPTS` section. For example: ```bash - set JAVA_OPTS=-javaagent:/path/to/java-agent-1.0-SNAPSHOT.jar + 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 ``` @@ -93,7 +93,7 @@ wget https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/org.jacoco. 3. Export the application path to point to your target folder containing Java classes: ```bash - export APP_PATH="/Users/sarthak_1/Downloads/karaf-sample/user-service" + 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. From 0cb47a1ae18da791b556b3dc8210b6b80efb7d2a Mon Sep 17 00:00:00 2001 From: Sarthak Shyngle <50234097+Sarthak160@users.noreply.github.com> Date: Wed, 15 Jan 2025 16:29:47 +0530 Subject: [PATCH 5/7] chore: add note for windows Signed-off-by: Sarthak Shyngle <50234097+Sarthak160@users.noreply.github.com> --- versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md b/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md index 136b7ee11..ff887f418 100644 --- a/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md +++ b/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md @@ -50,6 +50,8 @@ wget https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/org.jacoco. 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 ``` + **Note**: Windows support is not thoroughly tested. It is recommended to use macOS or Linux for better stability and compatibility. + Replace `/path/to/` with the actual paths where you downloaded the JAR files. ### Update `config.properties` From 6e3fe93a266264f73ec1a5846655267e22afc705 Mon Sep 17 00:00:00 2001 From: Sarthak Shyngle <50234097+Sarthak160@users.noreply.github.com> Date: Mon, 20 Jan 2025 05:19:13 +0530 Subject: [PATCH 6/7] docs: add api record instructions for karaf apps (#487) * Update keploy-karaf.md Signed-off-by: Sarthak Shyngle <50234097+Sarthak160@users.noreply.github.com> * Update keploy-karaf.md Signed-off-by: Sarthak Shyngle <50234097+Sarthak160@users.noreply.github.com> --------- Signed-off-by: Sarthak Shyngle <50234097+Sarthak160@users.noreply.github.com> --- .../running-keploy/keploy-karaf.md | 68 +++++++++++-------- 1 file changed, 39 insertions(+), 29 deletions(-) diff --git a/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md b/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md index ff887f418..e8c238423 100644 --- a/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md +++ b/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md @@ -57,34 +57,19 @@ wget https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/org.jacoco. ### Update `config.properties` 1. Navigate to the `etc/config.properties` file in your Karaf installation. -2. Add the following entry under the `bootdelegation` section to allow OSGi bundles to access Keploy artifacts: +2. Add the following entries under the `bootdelegation` section to allow OSGi bundles to access Keploy artifacts: ```properties org.osgi.framework.bootdelegation = \ - com.sun.*, \ - javax.transaction, \ - javax.transaction.xa, \ - javax.xml.crypto, \ - javax.xml.crypto.*, \ - javax.security.cert, \ - jdk.nashorn.*, \ - sun.*, \ - jdk.internal.reflect, \ - jdk.internal.reflect.*, \ - org.apache.karaf.jaas.boot, \ - org.apache.karaf.jaas.boot.principal, \ - io.keploy.* + ... \ + io.keploy.*, \ + javax.servlet, \ + javax.servlet.http ``` -## Step 3: Start Apache Karaf and Export Environment Variables +## Step 3: Export Environment Variables -1. Start Apache Karaf by navigating to the `bin` directory and running: - - ```bash - ./karaf - ``` - -2. Export the API key required for Keploy to function by running the following command in the same terminal session: +1. Export the API key specific to your user, as mentioned on [Keploy's User Dashboard](https://app.keploy.io/users), which is required for Keploy to function, by running the following command in the same terminal session: ```bash export API_KEY="" @@ -92,7 +77,7 @@ wget https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/org.jacoco. Replace the `API_KEY` value with your actual API key if different. -3. Export the application path to point to your target folder containing Java classes: +2. Export the application path to point to your target folder containing Java classes: ```bash export APP_PATH="/Users/path/to/karaf-sample/user-service" @@ -100,7 +85,25 @@ wget https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/org.jacoco. Replace the `APP_PATH` value with the absolute path to your application's target folder. -## Step 4: Import Postman Collection +## Step 4: Record Test Cases + +1. Restart Apache Karaf by setting the environment variable `KEPLOY_MODE` to `RECORD`: + + ```bash + export KEPLOY_MODE="RECORD" + ./karaf + ``` + +2. Record test cases using the following command: + + ```bash + 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: @@ -111,13 +114,20 @@ wget https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/org.jacoco. Replace `/path/to/YourPostmanCollection.json` with the actual path to your Postman collection. -## Step 5: Run Keploy Tests +## Step 6: Run Keploy Tests -Use the following command to run the imported tests: +1. Restart Apache Karaf by setting the environment variable `KEPLOY_MODE` to `test`: -```bash -keploy test --base-path="http://localhost:8181" -``` + ```bash + export KEPLOY_MODE="test" + ./karaf + ``` + +2. Use the following command to run the imported tests: + + ```bash + keploy test --base-path="http://localhost:8181" + ``` This assumes your Karaf application is running locally on port 8181. From 3d1c716dbf81272a6564eabc001331536303f2ac Mon Sep 17 00:00:00 2001 From: Sarthak Shyngle <50234097+Sarthak160@users.noreply.github.com> Date: Thu, 23 Jan 2025 12:28:46 +0530 Subject: [PATCH 7/7] chore: update windows karaf env step (#488) Signed-off-by: Sarthak Shyngle <50234097+Sarthak160@users.noreply.github.com> --- .../running-keploy/keploy-karaf.md | 22 +++++++++++++------ 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md b/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md index e8c238423..86312b7ec 100644 --- a/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md +++ b/versioned_docs/version-2.0.0/running-keploy/keploy-karaf.md @@ -28,7 +28,7 @@ wget https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/org.jacoco. ## Step 2: Configure Apache Karaf -### Update `JAVA_OPTS` for linux/mac in `setenv` File +### 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. @@ -39,20 +39,28 @@ wget https://keploy-enterprise.s3.us-west-2.amazonaws.com/agent-jars/org.jacoco. 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 +### 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: - ```bash - 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 + ```bat + 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 ``` - **Note**: Windows support is not thoroughly tested. It is recommended to use macOS or Linux for better stability and compatibility. +### 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: + +```bat +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 `/path/to/` with the actual paths where you downloaded the JAR files. +Replace the placeholder values with actual paths and keys as needed. ### Update `config.properties`