Skip to content

Commit bea2258

Browse files
SanskritiHarmukhSanskritiHarmukh
authored
Refactoring the readme for java sample app (#22)
* refactored readme for java sample app Signed-off-by: SanskritiHarmukh <sanskritiharmukh1908@gmail.com> * edited the link for test modes Signed-off-by: SanskritiHarmukh <sanskritiharmukh1908@gmail.com> * removed unnecessary image Signed-off-by: SanskritiHarmukh <sanskritiharmukh1908@gmail.com> * Revert "removed unnecessary image" This reverts commit 7102606. Signed-off-by: SanskritiHarmukh <sanskritiharmukh1908@gmail.com> * Revert "edited the link for test modes" This reverts commit 2da56bd. Signed-off-by: SanskritiHarmukh <sanskritiharmukh1908@gmail.com> * refactored from java-sdk Signed-off-by: SanskritiHarmukh <sanskritiharmukh1908@gmail.com> * Fixed the image for video Signed-off-by: SanskritiHarmukh <sanskritiharmukh1908@gmail.com> --------- Signed-off-by: SanskritiHarmukh <sanskritiharmukh1908@gmail.com>
1 parent e2c2e08 commit bea2258

2 files changed

Lines changed: 172 additions & 86 deletions

File tree

‎README.md‎

Lines changed: 172 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -2,30 +2,108 @@
22

33
A sample Employee-Manager app to test Keploy integration capabilities using [SpringBoot](https://spring.io) and PostgreSQL.
44

5-
### Pre-requisites
5+
## Pre-requisites
66

77
- [Java 8+](https://docs.spring.io/spring-boot/docs/current/reference/html/getting-started.html#getting-started.installing)
88

9-
## Installation
9+
## Quick Installation
1010

11-
### Start keploy server (macOS)
11+
### **MacOS**
1212

1313
```shell
1414
curl --silent --location "https://github.com/keploy/keploy/releases/latest/download/keploy_darwin_all.tar.gz" | tar xz -C /tmp
1515

1616
sudo mv /tmp/keploy /usr/local/bin && keploy
1717
```
18-
### Start keploy server (Linux)
18+
19+
### **Linux**
20+
21+
<details>
22+
<summary>Linux</summary>
1923

2024
```shell
2125
curl --silent --location "https://github.com/keploy/keploy/releases/latest/download/keploy_linux_amd64.tar.gz" | tar xz -C /tmp
2226

27+
sudo mv /tmp/keploy /usr/local/bin && keploy
28+
```
29+
</details>
30+
31+
<details>
32+
<summary>Linux ARM</summary>
33+
34+
```shell
35+
curl --silent --location "https://github.com/keploy/keploy/releases/latest/download/keploy_linux_arm64.tar.gz" | tar xz -C /tmp
2336

2437
sudo mv /tmp/keploy /usr/local/bin && keploy
2538
```
2639

40+
The UI can be accessed at http://localhost:6789
41+
</details>
42+
43+
### **Windows**
44+
45+
<details>
46+
<summary>Windows</summary>
47+
48+
49+
- Download the [Keploy Windows AMD64](https://github.com/keploy/keploy/releases/latest/download/keploy_windows_amd64.tar.gz), and extract the files from the zip folder.
50+
51+
- Run the `keploy.exe` file.
52+
53+
</details>
54+
55+
<details>
56+
<summary>Windows ARM</summary>
57+
58+
- Download the [Keploy Windows ARM64](https://github.com/keploy/keploy/releases/latest/download/keploy_windows_arm64.tar.gz), and extract the files from the zip folder.
59+
60+
- Run the `keploy.exe` file.
61+
62+
</details>
63+
64+
## Build configuration
65+
66+
[Find the latest release](https://search.maven.org/artifact/io.keploy/keploy-sdk) of the Keploy Java SDK at maven
67+
central.
68+
69+
Add *keploy-sdk* as a dependency to your *pom.xml*:
70+
71+
<dependency>
72+
<groupId>io.keploy</groupId>
73+
<artifactId>keploy-sdk</artifactId>
74+
<version>N.N.N</version> (eg: 1.2.5)
75+
</dependency>
76+
77+
or to *build.gradle*:
78+
79+
implementation 'io.keploy:keploy-sdk:N.N.N' (eg: 1.2.5)
80+
81+
## Usage
82+
83+
- **For Spring based application**
2784

28-
### Setup Employee-Manager App
85+
Add `@Import(KeployMiddleware.class)` below `@SpringBootApplication` in your main class.
86+
87+
- **Run along with agent to mock external calls of your API 🤩🔥**
88+
89+
- Download the latest - Download the latest agent jar
90+
from [here](https://search.maven.org/artifact/io.keploy/keploy-sdk/1.2.5/jar) (eg: 1.2.5)
91+
92+
- Prefix `-javaagent:` with absolute classpath of agent jar (eg: `-javaagent:<your full path to agent jar>/agent-1.2.5.jar`) is possible through 3 ways:-
93+
94+
1. **Using Intellij :** Go to Edit Configuration-> add VM options -> paste _java agent_ edited above.
95+
96+
2. **Using Command Line :**
97+
```
98+
export JAVA_OPTS="$JAVA_OPTS -javaagent:<your full path to agent jar>/agent-1.2.5.jar"
99+
```
100+
101+
3. **Running via Tomcat Server :**
102+
```
103+
export CATALINA_OPTS="$CATALINA_OPTS -javaagent:<your full path to agent jar>/agent-1.2.5.jar"
104+
```
105+
106+
## Setup Employee-Manager App
29107
30108
```bash
31109
git clone https://github.com/keploy/samples-java
@@ -40,6 +118,12 @@ docker-compose up -d
40118
```shell
41119
mvn clean install
42120
```
121+
### Set KEPLOY_MODE to record
122+
123+
```
124+
To record testcases use `KEPLOY_MODE` env variable and set the same to `record` mode.
125+
```
126+
43127
### Run the application
44128

45129
```shell
@@ -64,7 +148,7 @@ curl --location --request POST 'http://localhost:8080/api/employees' \
64148
}'
65149
```
66150

67-
this will return the resonse or an entry . The timestamp would automatically be ignored during testing because it'll always be different.
151+
this will return the resonse or an entry. The timestamp would automatically be ignored during testing because it'll always be different.
68152

69153
```
70154
{
@@ -80,128 +164,125 @@ this will return the resonse or an entry . The timestamp would automatically be
80164

81165
```bash
82166
curl --location --request GET 'http://localhost:8080/api/employees/1'
83-
84167
```
85168

86169
or by querying through the browser `http://localhost:8080/api/employees/1`
87170

88-
Now both these API calls were captured as a testcase and should be visible on the [Keploy console](http://localhost:8081/testlist).
89-
If you're using Keploy cloud, open [this](https://app.keploy.io/testlist).
90-
91-
You should be seeing an app named `myApp` with the test cases we just captured.
171+
Now both these API calls were captured as **editable** testcases and written to `test/e2e/keploy-tests` folder. The keploy directory would also have `mocks` folder.
92172

93173
![testcases](https://i.imgur.com/rhNndcF.png)
94174

175+
95176
Now, let's see the magic! 🪄💫
96177

97178
## Test mode
98179

99180
There are 2 ways to test the application with Keploy.
100181

101-
1. [Unit Test File](https://docs.keploy.io/docs/java/run-your-first-app-tutorial#testing-using-unit-test-file)
102-
2. [KEPLOY_MODE environment variable](https://docs.keploy.io/docs/java/run-your-first-app-tutorial#testing-using-keploy_mode-env-variable)
182+
1. [Unit Test File](/README.md#testing-using-unit-test-file)
183+
2. [KEPLOY_MODE environment variable](/README.md#testing-using-keploy_mode-env-variable)
103184

104-
### Testing using Unit Test File
185+
### **Testing using Unit Test File**
105186

106187
Now that we have our testcase captured, run the unit test file (``SampleJavaApplication_Test.java`) already present in the sample app repo.
107188

108189
If not present, you can add ``SampleJavaApplication_Test.java`` in the test module of your sample application.
109190

110191
```java
111-
@Test
112-
public void TestKeploy() throws InterruptedException {
113-
114-
CountDownLatch countDownLatch = HaltThread.getInstance().getCountDownLatch();
115-
mode.setTestMode();
192+
@Test
193+
public void TestKeploy() throws InterruptedException {
194+
CountDownLatch countDownLatch = HaltThread.getInstance().getCountDownLatch();
195+
mode.setTestMode();
116196

117-
new Thread(() -> {
118-
SamplesJavaApplication.main(new String[]{""});
119-
countDownLatch.countDown();
120-
}).start();
197+
new Thread(() -> {
198+
SamplesJavaApplication.main(new String[]{""});
199+
countDownLatch.countDown();
200+
}).start();
121201

122-
countDownLatch.await();
123-
}
202+
countDownLatch.await();
203+
}
124204

125205
```
126206

127-
To automatically download and run the captured test-cases. Let's run the test-file.
207+
1. To automatically download and run the captured test-cases. Let's run the test-file.
128208

129209
2. To get test coverage, in addition to above follow below instructions.
130210

131211
3. Add maven-surefire-plugin to your *pom.xml*.
132212

133-
```xml
134-
<plugin>
135-
<groupId>org.apache.maven.plugins</groupId>
136-
<artifactId>maven-surefire-plugin</artifactId>
137-
<version>2.22.2</version>
138-
<configuration>
139-
140-
<!-- <skipTests>true</skipTests> -->
141-
142-
<systemPropertyVariables>
143-
<jacoco-agent.destfile>target/jacoco.exec
144-
</jacoco-agent.destfile>
145-
</systemPropertyVariables>
146-
</configuration>
147-
</plugin>
148-
```
213+
```xml
214+
<plugin>
215+
<groupId>org.apache.maven.plugins</groupId>
216+
<artifactId>maven-surefire-plugin</artifactId>
217+
<version>2.22.2</version>
218+
<configuration>
219+
220+
<!-- <skipTests>true</skipTests> -->
221+
222+
<systemPropertyVariables>
223+
<jacoco-agent.destfile>target/jacoco.exec</jacoco-agent.destfile>
224+
</systemPropertyVariables>
225+
</configuration>
226+
</plugin>
227+
```
149228
4. Add Jacoco plugin to your *pom.xml*.
150229

151-
```xml
152-
<plugin>
153-
<groupId>org.jacoco</groupId>
154-
<artifactId>jacoco-maven-plugin</artifactId>
155-
<version>0.8.5</version>
156-
<executions>
157-
<execution>
158-
<id>prepare-agent</id>
159-
<goals>
160-
<goal>prepare-agent</goal>
161-
</goals>
162-
</execution>
163-
<execution>
164-
<id>report</id>
165-
<phase>prepare-package</phase>
166-
<goals>
167-
<goal>report</goal>
168-
</goals>
169-
</execution>
170-
<execution>
171-
<id>post-unit-test</id>
172-
<phase>test</phase>
173-
<goals>
174-
<goal>report</goal>
175-
</goals>
176-
<configuration>
177-
<!-- Sets the path to the file which contains the execution data. -->
178-
179-
<dataFile>target/jacoco.exec</dataFile>
180-
<!-- Sets the output directory for the code coverage report. -->
181-
<outputDirectory>target/my-reports</outputDirectory>
182-
</configuration>
183-
</execution>
184-
</executions>
185-
</plugin>
186-
```
230+
```xml
231+
<plugin>
232+
<groupId>org.jacoco</groupId>
233+
<artifactId>jacoco-maven-plugin</artifactId>
234+
<version>0.8.5</version>
235+
<executions>
236+
<execution>
237+
<id>prepare-agent</id>
238+
<goals>
239+
<goal>prepare-agent</goal>
240+
</goals>
241+
</execution>
242+
<execution>
243+
<id>report</id>
244+
<phase>prepare-package</phase>
245+
<goals>
246+
<goal>report</goal>
247+
</goals>
248+
</execution>
249+
<execution>
250+
<id>post-unit-test</id>
251+
<phase>test</phase>
252+
<goals>
253+
<goal>report</goal>
254+
</goals>
255+
<configuration>
256+
<!-- Sets the path to the file which contains the execution data. -->
257+
258+
<dataFile>target/jacoco.exec</dataFile>
259+
<!-- Sets the output directory for the code coverage report. -->
260+
<outputDirectory>target/my-reports</outputDirectory>
261+
</configuration>
262+
</execution>
263+
</executions>
264+
</plugin>
265+
```
187266

188267
5. Run your tests using command : `mvn test`.
189268

190269
It will create .html files as test-reports which can be found in your target folder !!
191270

192271

193-
**We got 75.3% without writing any testcases. 🎉 **
272+
**_We got 75.3% without writing any testcases. 🎉_**
194273

195274

196275

197276
Go to the Keploy Console TestRuns Page to get deeper insights on what testcases ran, what failed.
198277

199-
![testruns](https://raw.githubusercontent.com/keploy/samples-java/blob/main/src/main/resources/AllTestPass_outer.png "Recent testruns")
278+
200279

201280
![testruns](https://i.imgur.com/tg6OT0n.png "Summary")
202281

203282

204-
### Testing using `KEPLOY_MODE` Env Variable
283+
284+
285+
### **Testing using **KEPLOY_MODE** Env Variable**
205286

206287
To test using `KEPLOY_MODE` env variable, set the same to `test` mode.
207288

@@ -243,14 +324,15 @@ Hibernate: select employee0_.id as id1_0_, employee0_.email as email2_0_, employ
243324
Now let's introduce a bug! Let's try changing something like adding some extra headers in controllers `./EmployeeController.java` on line 35 like :
244325
245326
```java
246-
...
247-
return ResponseEntity.ok().header("MyNewHeader","abc").body(employee);
248-
...
327+
return ResponseEntity.ok().header("MyNewHeader","abc").body(employee);
249328
```
250329
251330
Let's run the test-file to see if Keploy catches the regression introduced.
252331
253-
`mvn test`
332+
333+
```shell
334+
mvn test
335+
```
254336
255337
You'll notice the failed test-case in the output.
256338
@@ -261,8 +343,12 @@ You'll notice the failed test-case in the output.
261343
2022-08-26 13:10:10.312 INFO 70155 --- [ Thread-1] io.keploy.service.GrpcService : || passed overall: FALSE ||
262344
```
263345
264-
To deep dive the problem go to [test runs](http://localhost:8081/testruns)
346+
To deep dive the problem go to [test runs](http://localhost:6789/testruns)
265347
266348
![testruns](https://i.imgur.com/qwP8r4d.png "Recent testruns")
267349
268350
351+
**In case of any query, refer to video below,**
352+
353+
[![java-sample](https://user-images.githubusercontent.com/74777863/217864311-94a3dc0c-90bc-4551-aca2-87e82e3d24cb.png)](https://youtu.be/Ssm4TnTkbLs)
354+

‎src/main/resources/Video.png‎

33.6 KB
Loading

0 commit comments

Comments
 (0)