Skip to content

Commit a330757

Browse files
e5le5l
committed
Add tutorials and readme
1 parent 684d749 commit a330757

File tree

3 files changed

+355
-0
lines changed

3 files changed

+355
-0
lines changed

‎README.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Kotlin JUnit Sample
2+
3+
Tutorial: [Test code using JUnit in JVM](https://kotlinlang.org/docs/jvm-test-using-junit.htm)
4+
5+
Configuration guides: [Maven](maven.md) | [Gradle](gradle.md)
6+
7+
A sample project demonstrating how to write tests in Kotlin for Java applications. This project shows the migration path from Java tests to Kotlin tests while testing Java source code.
8+
9+
## Getting Started
10+
11+
### Prerequisites
12+
13+
- Java 17 or higher
14+
15+
### Running Tests
16+
17+
Using Maven:
18+
```bash
19+
cd initial # or cd complete
20+
./mvnw test
21+
```
22+
23+
Using Gradle:
24+
```bash
25+
cd initial # or cd complete
26+
./gradlew test
27+
```
28+
29+
## Project Structure
30+
31+
This repository contains two versions of the same project:
32+
33+
```
34+
kotlin-junit-sample/
35+
├── initial/ # Starting point with Java tests
36+
│ ├── src/
37+
│ │ ├── main/java/ # Java source code
38+
│ │ └── test/java/ # JUnit tests in Java
39+
│ ├── pom.xml # Maven configuration
40+
│ └── build.gradle.kts # Gradle configuration
41+
│
42+
└── complete/ # Final version with Kotlin tests
43+
├── src/
44+
│ ├── main/java/ # Same Java source code
45+
│ └── test/java/ # JUnit tests in Kotlin
46+
├── pom.xml # Maven with Kotlin support
47+
└── build.gradle.kts # Gradle with Kotlin plugin
48+
```
49+
50+
### Application Code
51+
52+
Both projects contain a simple Todo application with:
53+
- **TodoItem** - A Java class representing a todo item with title, description, completion status, and timestamps
54+
- **TodoRepository** - A Java repository class for managing todo items in memory
55+
56+
### Test Code
57+
58+
- **initial/**: Contains comprehensive JUnit 5 tests written in Java
59+
- **complete/**: Same tests converted to Kotlin, demonstrating idiomatic Kotlin testing patterns
60+
61+
## Technologies
62+
63+
- **Java**: 17
64+
- **Kotlin**: 2.2.20 (test code only in complete version)
65+
- **JUnit**: 5.11.0
66+
- **Build Tools**: Maven and Gradle (both supported)
67+
- **UI Library**: Jexer 1.6.0 (terminal UI library)

‎gradle.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Mixing Kotlin and Java in a Gradle Project
2+
3+
This guide shows how to configure a Gradle project to use both Kotlin and Java together.
4+
5+
## Step 1: Add Kotlin JVM Plugin
6+
7+
Add the Kotlin JVM plugin to your `build.gradle.kts`:
8+
9+
```kotlin
10+
plugins {
11+
// ... existing plugins ...
12+
kotlin("jvm") version "2.2.20"
13+
}
14+
```
15+
16+
## Step 2: Configure Kotlin JVM Toolchain
17+
18+
Set the JVM toolchain version to match your Java version:
19+
20+
```kotlin
21+
kotlin {
22+
jvmToolchain(17)
23+
}
24+
```
25+
26+
This ensures Kotlin uses the same JDK version as your Java code.
27+
28+
## Step 3: Add Kotlin Test Dependency
29+
30+
Add the Kotlin test library to your dependencies:
31+
32+
```kotlin
33+
dependencies {
34+
// ... existing dependencies ...
35+
36+
testImplementation(kotlin("test"))
37+
// ... other test dependencies ...
38+
}
39+
```
40+
41+
The `kotlin("test")` dependency provides Kotlin's test utilities and integrates with JUnit.
42+
43+
## Step 4: Verify Configuration
44+
45+
Run your tests to verify the configuration:
46+
47+
```bash
48+
./gradlew clean test
49+
```
50+
51+
## Directory Structure
52+
53+
With this configuration, you can mix Java and Kotlin files in the same source directories:
54+
55+
```
56+
src/
57+
├── main/
58+
│ ├── java/ # Java and Kotlin production code
59+
│ └── kotlin/ # Additional Kotlin production code (optional)
60+
└── test/
61+
├── java/ # Java and Kotlin test code
62+
└── kotlin/ # Additional Kotlin test code (optional)
63+
```
64+
65+
The Kotlin plugin automatically recognizes both `src/main/java` and `src/test/java` directories, so you can place `.kt` files alongside `.java` files in the same directories.
66+
67+
## Summary of Changes
68+
69+
1. **Plugin**: Added `kotlin("jvm")` plugin with version 2.2.20
70+
2. **Toolchain**: Configured `jvmToolchain(17)` to match Java version
71+
3. **Dependency**: Added `kotlin("test")` test dependency
72+
73+
The configuration ensures that:
74+
- Kotlin compiler runs before Java compiler
75+
- Both Java and Kotlin code can reference each other

‎maven.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# Mixing Kotlin and Java in a Maven Project
2+
3+
This guide shows how to configure a Maven project to use both Kotlin and Java together.
4+
5+
## Step 1: Add Kotlin Version Property
6+
7+
Add the Kotlin version property to your `pom.xml`:
8+
9+
```xml
10+
<properties>
11+
<!-- ... other properties ... -->
12+
<kotlin.version>2.2.20</kotlin.version>
13+
</properties>
14+
```
15+
16+
## Step 2: Add Dependencies
17+
18+
Add the required dependencies:
19+
20+
```xml
21+
<dependencies>
22+
<!-- ... existing dependencies ... -->
23+
24+
<!-- JUnit Jupiter engine is required at test runtime -->
25+
<dependency>
26+
<groupId>org.junit.jupiter</groupId>
27+
<artifactId>junit-jupiter-engine</artifactId>
28+
<scope>test</scope>
29+
</dependency>
30+
31+
<!-- Kotlin standard library needed to compile/run Kotlin tests -->
32+
<dependency>
33+
<groupId>org.jetbrains.kotlin</groupId>
34+
<artifactId>kotlin-stdlib</artifactId>
35+
<version>${kotlin.version}</version>
36+
<scope>test</scope>
37+
</dependency>
38+
</dependencies>
39+
```
40+
41+
## Step 3: Configure Kotlin Maven Plugin
42+
43+
Add the Kotlin Maven plugin configuration to `<pluginManagement>`:
44+
45+
```xml
46+
<build>
47+
<pluginManagement>
48+
<plugins>
49+
<!-- ... other plugins ... -->
50+
51+
<plugin>
52+
<groupId>org.jetbrains.kotlin</groupId>
53+
<artifactId>kotlin-maven-plugin</artifactId>
54+
<version>${kotlin.version}</version>
55+
<extensions>true</extensions>
56+
<executions>
57+
<execution>
58+
<id>compile</id>
59+
<goals>
60+
<goal>compile</goal>
61+
</goals>
62+
<configuration>
63+
<sourceDirs>
64+
<sourceDir>${project.basedir}/src/main/kotlin</sourceDir>
65+
<sourceDir>${project.basedir}/src/main/java</sourceDir>
66+
</sourceDirs>
67+
</configuration>
68+
</execution>
69+
<execution>
70+
<id>test-compile</id>
71+
<goals>
72+
<goal>test-compile</goal>
73+
</goals>
74+
<configuration>
75+
<sourceDirs>
76+
<sourceDir>${project.basedir}/src/test/kotlin</sourceDir>
77+
<sourceDir>${project.basedir}/src/test/java</sourceDir>
78+
</sourceDirs>
79+
</configuration>
80+
</execution>
81+
</executions>
82+
</plugin>
83+
</plugins>
84+
</pluginManagement>
85+
</build>
86+
```
87+
88+
## Step 4: Configure Maven Compiler Plugin for Mixed Compilation
89+
90+
Update the Maven Compiler plugin to work with Kotlin. Add this to `<pluginManagement>`:
91+
92+
```xml
93+
<plugin>
94+
<groupId>org.apache.maven.plugins</groupId>
95+
<artifactId>maven-compiler-plugin</artifactId>
96+
<version>3.14.0</version>
97+
<executions>
98+
<!-- Disable default compile phases -->
99+
<execution>
100+
<id>default-compile</id>
101+
<phase>none</phase>
102+
</execution>
103+
<execution>
104+
<id>default-testCompile</id>
105+
<phase>none</phase>
106+
</execution>
107+
<!-- Enable Java compilation after Kotlin -->
108+
<execution>
109+
<id>java-compile</id>
110+
<phase>compile</phase>
111+
<goals>
112+
<goal>compile</goal>
113+
</goals>
114+
</execution>
115+
<execution>
116+
<id>java-test-compile</id>
117+
<phase>test-compile</phase>
118+
<goals>
119+
<goal>testCompile</goal>
120+
</goals>
121+
</execution>
122+
</executions>
123+
</plugin>
124+
```
125+
126+
**Why this configuration?**
127+
- Disabling default Maven compiler phases ensures Kotlin compiles first
128+
- This allows Kotlin code to reference Java code and vice versa
129+
- The custom execution phases run Java compilation after Kotlin
130+
131+
## Step 5: Activate the Kotlin Plugin
132+
133+
Add the Kotlin plugin to the `<plugins>` section (outside `<pluginManagement>`):
134+
135+
```xml
136+
<build>
137+
<pluginManagement>
138+
<!-- ... -->
139+
</pluginManagement>
140+
141+
<plugins>
142+
<plugin>
143+
<groupId>org.jetbrains.kotlin</groupId>
144+
<artifactId>kotlin-maven-plugin</artifactId>
145+
<version>${kotlin.version}</version>
146+
<extensions>true</extensions>
147+
<executions>
148+
<execution>
149+
<id>compile</id>
150+
<goals>
151+
<goal>compile</goal>
152+
</goals>
153+
<configuration>
154+
<sourceDirs>
155+
<sourceDir>${project.basedir}/src/main/kotlin</sourceDir>
156+
<sourceDir>${project.basedir}/src/main/java</sourceDir>
157+
</sourceDirs>
158+
</configuration>
159+
</execution>
160+
<execution>
161+
<id>test-compile</id>
162+
<goals>
163+
<goal>test-compile</goal>
164+
</goals>
165+
<configuration>
166+
<sourceDirs>
167+
<sourceDir>${project.basedir}/src/test/kotlin</sourceDir>
168+
<sourceDir>${project.basedir}/src/test/java</sourceDir>
169+
</sourceDirs>
170+
</configuration>
171+
</execution>
172+
</executions>
173+
</plugin>
174+
</plugins>
175+
</build>
176+
```
177+
178+
## Step 6: Verify Configuration
179+
180+
Run your tests to verify the configuration:
181+
182+
```bash
183+
./mvnw clean test
184+
```
185+
186+
## Directory Structure
187+
188+
With this configuration, you can mix Java and Kotlin files in the same source directories:
189+
190+
```
191+
src/
192+
├── main/
193+
│ ├── java/ # Java and Kotlin production code
194+
│ └── kotlin/ # Additional Kotlin production code (optional)
195+
└── test/
196+
├── java/ # Java and Kotlin test code
197+
└── kotlin/ # Additional Kotlin test code (optional)
198+
```
199+
200+
The `kotlin-maven-plugin` configuration includes both `src/main/java` and `src/test/java` directories, so you can place `.kt` files alongside `.java` files in the same directories.
201+
202+
## Summary of Changes
203+
204+
1. **Property**: Added `kotlin.version` property
205+
2. **Dependency**: Added `kotlin-stdlib` with test scope
206+
3. **Dependency**: Added `junit-jupiter-engine` (required for test runtime)
207+
4. **Plugin**: Added `kotlin-maven-plugin` configuration
208+
5. **Plugin**: Modified `maven-compiler-plugin` to disable default phases
209+
6. **Plugin**: Activated `kotlin-maven-plugin` in `<plugins>` section
210+
211+
The configuration ensures that:
212+
- Kotlin compiler runs before Java compiler
213+
- Both Java and Kotlin code can reference each other

0 commit comments

Comments
 (0)