|
1 | | -# Example Employee-Manager App |
| 1 | +<h1 align="center"> Keploy Java Samples </h1> |
| 2 | +<p align="center"> |
2 | 3 |
|
3 | | -A sample Employee-Manager app to test Keploy integration capabilities using [SpringBoot](https://spring.io) and |
4 | | -[PostgreSQL](https://www.postgresql.org/). |
| 4 | + <a href="CODE_OF_CONDUCT.md" alt="Contributions welcome"> |
| 5 | + <img src="https://img.shields.io/badge/Contributions-Welcome-brightgreen?logo=github" /></a> |
| 6 | + |
| 7 | + <a href="https://join.slack.com/t/keploy/shared_invite/zt-12rfbvc01-o54cOG0X1G6eVJTuI_orSA" alt="Slack"> |
| 8 | + <img src="https://github.com/keploy/samples-go/blob/main/.github/slack.svg?raw=true" /></a> |
| 9 | + |
| 10 | + <a href="https://opensource.org/licenses/Apache-2.0" alt="License"> |
| 11 | + <img src="https://github.com/keploy/samples-go/blob/main/.github/License-Apache_2.0-blue.svg?raw=true" /></a> |
| 12 | +</p> |
5 | 13 |
|
6 | | -**Note** :- Issue Creation is disabled on this Repository, please visit [here](https://github.com/keploy/keploy/issues/new/choose) to submit Issue. |
| 14 | +This repo contains the sample for [Keploy's](https://keploy.io) Java Application. Please feel free to contribute if you'd like submit a sample for another use-case or library. |
7 | 15 |
|
8 | | -## Pre-requisites |
| 16 | +>**Note** :- Issue Creation is disabled on this Repository, please visit [here](https://github.com/keploy/keploy/issues/new/choose) to submit Issue. |
9 | 17 |
|
10 | | -- [Java 8+](https://docs.spring.io/spring-boot/docs/current/reference/html/getting-started.html#getting-started.installing) |
11 | 18 |
|
12 | | -## Quick Installation of "KEPLOY" server |
| 19 | +## Sample Apps with Keploy |
13 | 20 |
|
14 | | -### **MacOS** |
| 21 | +1. [employee-manager](https://github.com/keploy/samples-java/tree/main/employee-manager) |
15 | 22 |
|
16 | | -<details> |
17 | | -<summary>MacOS</summary> |
| 23 | +## Community Support ❤️ |
18 | 24 |
|
19 | | -```shell |
20 | | -curl --silent --location "https://github.com/keploy/keploy/releases/latest/download/keploy_darwin_all.tar.gz" | tar xz -C /tmp |
| 25 | +### 🤔 Questions? |
| 26 | +Reach out to us. We're here to help! |
21 | 27 |
|
22 | | -sudo mkdir -p /usr/local/bin && sudo mv /tmp/keploy /usr/local/bin && keploy |
23 | | -``` |
| 28 | +[](https://join.slack.com/t/keploy/shared_invite/zt-12rfbvc01-o54cOG0X1G6eVJTuI_orSA) |
| 29 | +[](https://www.linkedin.com/company/keploy/) |
| 30 | +[](https://www.youtube.com/channel/UC6OTg7F4o0WkmNtSoob34lg) |
| 31 | +[](https://twitter.com/Keployio) |
24 | 32 |
|
25 | | -</details> |
| 33 | +### 💖 Let's Build Together! |
| 34 | +Whether you're a newbie coder or a wizard 🧙♀️, your perspective is golden. Take a peek at our: |
26 | 35 |
|
27 | | -### **Linux** |
28 | | - |
29 | | -<details> |
30 | | -<summary>Linux</summary> |
31 | | - |
32 | | -```shell |
33 | | -curl --silent --location "https://github.com/keploy/keploy/releases/latest/download/keploy_linux_amd64.tar.gz" | tar xz -C /tmp |
34 | | - |
35 | | -sudo mkdir -p /usr/local/bin && sudo mv /tmp/keploy /usr/local/bin && keploy |
36 | | -``` |
37 | | - |
38 | | -</details> |
39 | | - |
40 | | -<details> |
41 | | -<summary>Linux ARM</summary> |
42 | | - |
43 | | -```shell |
44 | | -curl --silent --location "https://github.com/keploy/keploy/releases/latest/download/keploy_linux_arm64.tar.gz" | tar xz -C /tmp |
45 | | - |
46 | | -sudo mkdir -p /usr/local/bin && sudo mv /tmp/keploy /usr/local/bin && keploy |
47 | | -``` |
48 | | - |
49 | | - |
50 | | -</details> |
51 | | - |
52 | | -### **Windows** |
53 | | - |
54 | | -<details> |
55 | | -<summary>Windows</summary> |
56 | | - |
57 | | -- Download |
58 | | - the [Keploy Windows AMD64](https://github.com/keploy/keploy/releases/latest/download/keploy_windows_amd64.tar.gz), and |
59 | | - extract the files from the zip folder. |
60 | | -- Run the `keploy.exe` file. |
61 | | - |
62 | | -</details> |
63 | | - |
64 | | -<details> |
65 | | -<summary>Windows ARM</summary> |
66 | | - |
67 | | -- Download |
68 | | - the [Keploy Windows ARM64](https://github.com/keploy/keploy/releases/latest/download/keploy_windows_arm64.tar.gz), and |
69 | | - extract the files from the zip folder. |
70 | | -- Run the `keploy.exe` file. |
71 | | - |
72 | | -</details> |
73 | | - |
74 | | -## Build configuration |
75 | | - |
76 | | -[Find the latest release](https://search.maven.org/artifact/io.keploy/keploy-sdk) of the Keploy Java SDK at maven |
77 | | -central. |
78 | | - |
79 | | -Add *keploy-sdk* as a dependency to your *pom.xml*: |
80 | | - |
81 | | - <dependency> |
82 | | - <groupId> io.keploy </groupId> |
83 | | - <artifactId> keploy-sdk </artifactId> |
84 | | - <version> N.N.N </version> (eg: 1.2.8) |
85 | | - </dependency> |
86 | | - |
87 | | -or to *build.gradle*: |
88 | | - |
89 | | - implementation 'io.keploy:keploy-sdk:N.N.N' (eg: 1.2.8) |
90 | | - |
91 | | -## Usage |
92 | | -- Refer [this](https://github.com/gouravkrosx/java-sdk#usage). |
93 | | - |
94 | | -## Setup Employee-Manager App |
95 | | - |
96 | | -```bash |
97 | | -git clone https://github.com/keploy/samples-java |
98 | | -``` |
99 | | - |
100 | | -## Agent-jar |
101 | | -Download the latest version (1.2.8) of agent jar from [here](https://central.sonatype.com/artifact/io.keploy/agent/1.2.8) and add this jar to main directory. |
102 | | - |
103 | | - |
104 | | -### Start PostgreSQL instance |
105 | | -Download docker dekstop from [here](https://docs.docker.com/get-docker/). |
106 | | -```bash |
107 | | -docker-compose up -d |
108 | | -``` |
109 | | - |
110 | | -### Maven clean install |
111 | | - |
112 | | -```shell |
113 | | -mvn clean install -Dmaven.test.skip=true |
114 | | -``` |
115 | | - |
116 | | -### Set KEPLOY_MODE to record |
117 | | - |
118 | | -- To record testcases use `KEPLOY_MODE` and `DENOISE` as env variables. Set `KEPLOY` to `record` mode and mark `DENOISE` as `true`. Also add |
119 | | - |
120 | | -`-javaagent:path of agent jar` like this 👇. |
121 | | - |
122 | | - |
123 | | - |
124 | | - |
125 | | - |
126 | | -## Generate testcases |
127 | | - |
128 | | -To generate testcases we just need to **make some API calls.** You can use [Postman](https://www.postman.com/) |
129 | | -, [Hoppscotch](https://hoppscotch.io/), or simply `curl` |
130 | | - |
131 | | -### 1. Make an employee entry |
132 | | - |
133 | | -```bash |
134 | | -curl --location --request POST 'http://localhost:8080/api/employees' \ |
135 | | ---header 'Content-Type: application/json' \ |
136 | | ---data-raw '{ |
137 | | - "firstName": "Myke", |
138 | | - "lastName": "Tyson", |
139 | | - |
140 | | - "timestamp":1 |
141 | | -}' |
142 | | -``` |
143 | | - |
144 | | -this will return the response or an entry. The timestamp would automatically be ignored during testing because it'll |
145 | | -always be different. |
146 | | - |
147 | | -``` |
148 | | -{ |
149 | | - "id": 1, |
150 | | - "firstName": "Myke", |
151 | | - "lastName": "Tyson", |
152 | | - |
153 | | - "timestamp": 1661493301 |
154 | | -} |
155 | | -``` |
156 | | - |
157 | | -### 2. Fetch recorded info about employees |
158 | | - |
159 | | -```bash |
160 | | -curl --location --request GET 'http://localhost:8080/api/employees/1' |
161 | | -``` |
162 | | - |
163 | | -or by querying through the browser `http://localhost:8080/api/employees/1` |
164 | | - |
165 | | -Now both these API calls were captured as **editable** testcases and written to `test/e2e/keploy-tests` folder. The |
166 | | -keploy directory would also have `mocks` folder. |
167 | | - |
168 | | - |
169 | | - |
170 | | -Now, let's see the magic! 🪄💫 |
171 | | - |
172 | | -## Test mode |
173 | | - |
174 | | -There are 2 ways to test the application with Keploy. |
175 | | - |
176 | | -1. [Unit Test File](/README.md#testing-using-unit-test-file) |
177 | | -2. [Without Unit Test File](/README.md#testing-without-using-unit-test-file) |
178 | | - |
179 | | -### **Testing using Unit Test File** |
180 | | - |
181 | | - |
182 | | -- Set `KEPLOY_MODE = test` (default "off") |
183 | | - |
184 | | -_NOTE: You will be required to set the `javaagent` again in your test profile just like below._ |
185 | | - |
186 | | - |
187 | | - |
188 | | -- Now that we have our testcase captured, run the unit test file (`SampleJavaApplication_Test.java`) already present in |
189 | | -the sample app repo. |
190 | | - |
191 | | -- If not present, you can make and add below code in `SampleJavaApplication_Test.java` in the test module of your sample application. |
192 | | - |
193 | | -```java |
194 | | - @Test |
195 | | - public void TestKeploy() throws InterruptedException { |
196 | | - |
197 | | - CountDownLatch countDownLatch = HaltThread.getInstance().getCountDownLatch(); |
198 | | - Mode.setTestMode(); |
199 | | - |
200 | | - new Thread(() -> { |
201 | | - <Your Application Class>.main(new String[]{""}); |
202 | | - countDownLatch.countDown(); |
203 | | - }).start(); |
204 | | - |
205 | | - countDownLatch.await(); |
206 | | - assertTrue(AssertKTests.result(), "Keploy Test Result"); |
207 | | - } |
208 | | -``` |
209 | | -- **Using IDE:** _(for local use-case we prefer running tests via IDE)_ |
210 | | - 1. Run your application. |
211 | | - 2. You can also run the application with coverage to see the test coverage. |
212 | | - |
213 | | -- **Using command line** |
214 | | - 1. Add maven-surefire-plugin to your *pom.xml*. In `<argLine> </argLine>` don't add jacoco agent if you don't want coverage report. |
215 | | - |
216 | | - ```xml |
217 | | - <plugin> |
218 | | - <groupId>org.apache.maven.plugins</groupId> |
219 | | - <artifactId>maven-surefire-plugin</artifactId> |
220 | | - <version>2.22.2</version> |
221 | | - <configuration> |
222 | | - |
223 | | - <!-- <skipTests>true</skipTests> --> |
224 | | - <argLine> |
225 | | - -javaagent:<your full path to agent jar>.jar |
226 | | - -javaagent:${settings.localRepository}/org/jacoco/org.jacoco.agent/0.8.7/org.jacoco.agent-0.8.7-runtime.jar=destfile=target/jacoco.exec |
227 | | - </argLine> |
228 | | - |
229 | | - <systemPropertyVariables> |
230 | | - <jacoco-agent.destfile>target/jacoco.exec |
231 | | - </jacoco-agent.destfile> |
232 | | - </systemPropertyVariables> |
233 | | - </configuration> |
234 | | - </plugin> |
235 | | - ``` |
236 | | - |
237 | | - 2. If you want coverage report also add Jacoco plugin to your *pom.xml*. |
238 | | - |
239 | | - ```xml |
240 | | - <plugin> |
241 | | - <groupId>org.jacoco</groupId> |
242 | | - <artifactId>jacoco-maven-plugin</artifactId> |
243 | | - <version>0.8.7</version> |
244 | | - <executions> |
245 | | - <execution> |
246 | | - <id>prepare-agent</id> |
247 | | - <goals> |
248 | | - <goal>prepare-agent</goal> |
249 | | - </goals> |
250 | | - </execution> |
251 | | - <execution> |
252 | | - <id>report</id> |
253 | | - <phase>prepare-package</phase> |
254 | | - <goals> |
255 | | - <goal>report</goal> |
256 | | - </goals> |
257 | | - </execution> |
258 | | - <execution> |
259 | | - <id>post-unit-test</id> |
260 | | - <phase>test</phase> |
261 | | - <goals> |
262 | | - <goal>report</goal> |
263 | | - </goals> |
264 | | - <configuration> |
265 | | - <!-- Sets the path to the file which contains the execution data. --> |
266 | | - |
267 | | - <dataFile>target/jacoco.exec</dataFile> |
268 | | - <!-- Sets the output directory for the code coverage report. --> |
269 | | - <outputDirectory>target/my-reports</outputDirectory> |
270 | | - </configuration> |
271 | | - </execution> |
272 | | - </executions> |
273 | | - </plugin> |
274 | | - ``` |
275 | | - 3. Run your tests using command : `mvn test`. |
276 | | - |
277 | | - |
278 | | -It will create .html files as test-reports which can be found in your target folder !! |
279 | | - |
280 | | -**_We got 53% without writing any testcases. 🎉_** |
281 | | - |
282 | | -Go to the Keploy Console TestRuns Page to get deeper insights on what testcases ran, what failed. |
283 | | - |
284 | | - |
285 | | - |
286 | | -### **Testing without using Unit Test File** |
287 | | - |
288 | | -To test using `KEPLOY_MODE` env variable, set the same to `test` mode. |
289 | | - |
290 | | -``` |
291 | | -export KEPLOY_MODE=test |
292 | | -``` |
293 | | - |
294 | | -Now simply run the application either by ide or using command: |
295 | | - |
296 | | -```shell |
297 | | -java -javaagent:<your full path to agent jar>.jar -jar <your full path to appliation jar>.jar |
298 | | -``` |
299 | | - |
300 | | -Keploy will run all the captures test-cases, compare and show the results on the console. |
301 | | - |
302 | | -```shell |
303 | | -10b3ddd5-42fa-48e7-b98a-b47257272e39 total tests: 2 |
304 | | -2022-08-26 14:13:08.993 INFO 11560 --- [ Thread-4] io.keploy.service.GrpcService : testing 1 of 2 testcase id: [ae4a6c91-712a-4566-bf0d-97d708f94b2d] |
305 | | -2022-08-26 14:13:08.994 INFO 11560 --- [ Thread-4] io.keploy.service.GrpcService : testing 2 of 2 testcase id: [4843e03e-76a8-4194-99cb-f62740978d15] |
306 | | -2022-08-26 14:13:09.061 INFO 11560 --- [nio-8080-exec-1] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring DispatcherServlet 'dispatcherServlet' |
307 | | -2022-08-26 14:13:09.061 INFO 11560 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet : Initializing Servlet 'dispatcherServlet' |
308 | | -2022-08-26 14:13:09.062 INFO 11560 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet : Completed initialization in 1 ms |
309 | | -Hibernate: insert into employees (email, first_name, last_name, timestamp) values (?, ?, ?, ?) |
310 | | -2022-08-26 14:13:09.247 INFO 11560 --- [pool-3-thread-1] io.keploy.service.GrpcService : result : testcase id: [ae4a6c91-712a-4566-bf0d-97d708f94b2d] passed: true |
311 | | -Hibernate: select employee0_.id as id1_0_0_, employee0_.email as email2_0_0_, employee0_.first_name as first_na3_0_0_, employee0_.last_name as last_nam4_0_0_, employee0_.timestamp as timestam5_0_0_ from employees employee0_ where employee0_.id=? |
312 | | -2022-08-26 14:13:09.291 INFO 11560 --- [pool-3-thread-1] io.keploy.service.GrpcService : result : testcase id: [4843e03e-76a8-4194-99cb-f62740978d15] passed: true |
313 | | -2022-08-26 14:13:09.388 INFO 11560 --- [ Thread-4] io.keploy.service.GrpcService : test run completed with run id [1e81233d-e3be-4a4a-afda-a800902ad965] |
314 | | -2022-08-26 14:13:09.388 INFO 11560 --- [ Thread-4] io.keploy.service.GrpcService : || passed overall: TRUE || |
315 | | -2022-08-26 14:13:19.408 INFO 11560 --- [ionShutdownHook] j.LocalContainerEntityManagerFactoryBean : Closing JPA EntityManagerFactory for persistence unit 'default' |
316 | | -2022-08-26 14:13:19.410 INFO 11560 --- [ionShutdownHook] com.zaxxer.hikari.HikariDataSource : HikariPool-1 - Shutdown initiated... |
317 | | -2022-08-26 14:13:19.414 INFO 11560 --- [ionShutdownHook] com.zaxxer.hikari.HikariDataSource : HikariPool-1 - Shutdown completed. |
318 | | -``` |
319 | | -
|
320 | | - |
321 | | -
|
322 | | -## Let's add a Bug in the App |
323 | | -
|
324 | | -Now let's introduce a bug! Let's try changing something like adding some extra headers in |
325 | | -controllers `./EmployeeController.java` on line 35 like : |
326 | | -
|
327 | | -```java |
328 | | -return ResponseEntity.ok().header("MyNewHeader","abc").body(employee); |
329 | | -``` |
330 | | -
|
331 | | -Let's run the test-file to see if Keploy catches the regression introduced. |
332 | | -
|
333 | | -```shell |
334 | | -mvn test |
335 | | -``` |
336 | | -
|
337 | | -You'll notice the failed test-case in the output. |
338 | | -
|
339 | | -```shell |
340 | | -2022-08-26 13:10:10.289 TRACE 70155 --- [nio-8080-exec-2] o.h.type.descriptor.sql.BasicBinder : binding parameter [1] as [BIGINT] - [1] |
341 | | -2022-08-26 13:10:10.307 INFO 70155 --- [pool-3-thread-1] io.keploy.service.GrpcService : result : testcase id: [d42a3724-2c78-4f42-8dc6-d25a9b611c7c] passed: false |
342 | | -2022-08-26 13:10:10.312 INFO 70155 --- [ Thread-1] io.keploy.service.GrpcService : test run completed with run id [fcb61332-1025-463f-854e-6f406bce870d] |
343 | | -2022-08-26 13:10:10.312 INFO 70155 --- [ Thread-1] io.keploy.service.GrpcService : || passed overall: FALSE || |
344 | | -``` |
345 | | -
|
346 | | -To deep dive the problem go to [test runs](http://localhost:6789/testruns) |
347 | | -
|
348 | | - |
349 | | -
|
350 | | -
|
351 | | -**In case of any query, refer to video below,** |
352 | | -
|
353 | | -[](https://youtu.be/Ssm4TnTkbLs) |
| 36 | +📜 [Contribution Guidelines](https://github.com/keploy/keploy/blob/main/CONTRIBUTING.md) |
354 | 37 |
|
| 38 | +❤️ [Code of Conduct](https://github.com/keploy/keploy/blob/main/CODE_OF_CONDUCT.md) |
0 commit comments