Skip to content

Commit 8788b4d

Browse files
koshachykoshachy
committed
KT-68693 Add instructions for Maven
1 parent 3b97fc4 commit 8788b4d

File tree

1 file changed

+249
-16
lines changed

1 file changed

+249
-16
lines changed

‎docs/topics/power-assert.md‎

Lines changed: 249 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,5 @@
11
[//]: # (title: Power-assert compiler plugin)
2-
3-
> The Power-assert compiler plugin is [Experimental](components-stability.md).
4-
> It may be changed at any time. Use it only for evaluation purposes.
5-
> We would appreciate your feedback in [YouTrack](https://kotl.in/issue).
6-
>
7-
{style="warning"}
2+
<primary-label ref="experimental-opt-in"/>
83

94
The Kotlin Power-assert compiler plugin improves the debugging experience
105
by providing detailed failure messages with contextual information.
@@ -37,6 +32,8 @@ The Power-assert plugin key features:
3732

3833
## Apply the plugin
3934

35+
### Gradle
36+
4037
To enable the Power-assert plugin, configure your `build.gradle(.kts)` file as follows:
4138

4239
<tabs group="build-script">
@@ -45,8 +42,8 @@ To enable the Power-assert plugin, configure your `build.gradle(.kts)` file as f
4542
```kotlin
4643
// build.gradle.kts
4744
plugins {
48-
kotlin("multiplatform") version "2.0.0"
49-
kotlin("plugin.power-assert") version "2.0.0"
45+
kotlin("multiplatform") version "%kotlinVersion%"
46+
kotlin("plugin.power-assert") version "%kotlinVersion%"
5047
}
5148
```
5249

@@ -56,16 +53,14 @@ plugins {
5653
```groovy
5754
// build.gradle
5855
plugins {
59-
id 'org.jetbrains.kotlin.multiplatform' version '2.0.0'
60-
id 'org.jetbrains.kotlin.plugin.power-assert' version '2.0.0'
56+
id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%'
57+
id 'org.jetbrains.kotlin.plugin.power-assert' version '%kotlinVersion%'
6158
}
6259
```
6360

6461
</tab>
6562
</tabs>
6663

67-
## Configure the plugin
68-
6964
The Power-assert plugin provides several options to customize its behavior:
7065

7166
* **`functions`**: A list of fully-qualified function paths. The Power-assert plugin will transform the calls to these functions. If not specified, only `kotlin.assert()` calls will be transformed by default.
@@ -110,13 +105,84 @@ powerAssert {
110105
}
111106
```
112107

113-
## Use the plugin
108+
### Maven
109+
110+
To enable the Power-assert compiler plugin in a Maven project, update the `<plugin>` section of `kotlin-maven-plugin`
111+
in the `pom.xml` file:
112+
113+
```xml
114+
<build>
115+
<plugins>
116+
<plugin>
117+
<artifactId>kotlin-maven-plugin</artifactId>
118+
<groupId>org.jetbrains.kotlin</groupId>
119+
<version>%kotlinVersion%</version>
120+
<executions>
121+
<execution>
122+
<id>compile</id>
123+
<phase>process-sources</phase>
124+
<goals>
125+
<goal>compile</goal>
126+
</goals>
127+
</execution>
128+
<execution>
129+
<id>test-compile</id>
130+
<phase>process-test-sources</phase>
131+
<goals>
132+
<goal>test-compile</goal>
133+
</goals>
134+
</execution>
135+
</executions>
136+
137+
<configuration>
138+
<!-- Specify the Power-assert plugin -->
139+
<compilerPlugins>
140+
<plugin>power-assert</plugin>
141+
</compilerPlugins>
142+
</configuration>
143+
144+
<!-- Add the Power-assert plugin dependency -->
145+
<dependencies>
146+
<dependency>
147+
<groupId>org.jetbrains.kotlin</groupId>
148+
<artifactId>kotlin-maven-power-assert</artifactId>
149+
<version>%kotlinVersion%</version>
150+
</dependency>
151+
</dependencies>
152+
</plugin>
153+
</plugins>
154+
</build>
155+
```
156+
157+
You can customize which functions the Power-assert plugin transforms by using the `function` option.
158+
For example, you can include `kotlin.test.assertTrue()`, `kotlin.test.assertEquals()`, and others.
159+
If not specified, only `kotlin.assert()` calls are transformed by default.
160+
161+
Specify this option in the `<configuration>` section of `kotlin-maven-plugin`:
162+
163+
```xml
164+
<configuration>
165+
<!-- Specify the functions to transform -->
166+
<pluginOptions>
167+
<option>power-assert:function=kotlin.assert</option>
168+
<option>power-assert:function=kotlin.test.assertTrue</option>
169+
<option>power-assert:function=kotlin.test.AssertEquals</option>
170+
</pluginOptions>
171+
</configuration>
172+
```
173+
174+
## Use the power-assert plugin
114175

115176
This section provides examples of using the Power-assert compiler plugin.
116177

117-
See the complete code of the build script file `build.gradle.kts` for all these examples:
178+
See the complete code of the build script file `build.gradle.kts` or `pom.xml` for all these examples:
179+
180+
<tabs group="build-script">
181+
<tab title="Gradle (Kotlin)" group-key="kotlin">
118182

119183
```kotlin
184+
// build.gradle.kts
185+
120186
import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
121187

122188
plugins {
@@ -146,6 +212,130 @@ powerAssert {
146212
```
147213
{initial-collapse-state="collapsed" collapsible="true"}
148214

215+
</tab>
216+
217+
<tab title="Maven" group-key="maven">
218+
219+
```xml
220+
<!-- pom.xml -->
221+
<?xml version="1.0" encoding="UTF-8"?>
222+
<project xmlns="http://maven.apache.org/POM/4.0.0"
223+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
224+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
225+
<modelVersion>4.0.0</modelVersion>
226+
227+
<groupId>com.example</groupId>
228+
<artifactId>maven-power-assert-plugin-demo</artifactId>
229+
<version>1.0-SNAPSHOT</version>
230+
231+
<properties>
232+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
233+
<kotlin.code.style>official</kotlin.code.style>
234+
<kotlin.compiler.jvmTarget>1.8</kotlin.compiler.jvmTarget>
235+
</properties>
236+
237+
<repositories>
238+
<repository>
239+
<id>mavenCentral</id>
240+
<url>https://repo1.maven.org/maven2/</url>
241+
</repository>
242+
</repositories>
243+
244+
<build>
245+
<sourceDirectory>src/main/kotlin</sourceDirectory>
246+
<testSourceDirectory>src/test/kotlin</testSourceDirectory>
247+
<plugins>
248+
<plugin>
249+
<groupId>org.jetbrains.kotlin</groupId>
250+
<artifactId>kotlin-maven-plugin</artifactId>
251+
<version>%kotlinVersion%</version>
252+
<executions>
253+
<execution>
254+
<id>compile</id>
255+
<phase>compile</phase>
256+
<goals>
257+
<goal>compile</goal>
258+
</goals>
259+
</execution>
260+
<execution>
261+
<id>test-compile</id>
262+
<phase>test-compile</phase>
263+
<goals>
264+
<goal>test-compile</goal>
265+
</goals>
266+
</execution>
267+
</executions>
268+
269+
<configuration>
270+
<compilerPlugins>
271+
<plugin>power-assert</plugin>
272+
</compilerPlugins>
273+
274+
<pluginOptions>
275+
<option>plugin:power-assert:function=kotlin.assert</option>
276+
<option>plugin:power-assert:function=kotlin.require</option>
277+
<option>plugin:power-assert:function=kotlin.test.assertTrue</option>
278+
<option>plugin:power-assert:function=kotlin.test.assertEquals</option>
279+
<option>plugin:power-assert:function=kotlin.test.assertNull</option>
280+
<option>plugin:power-assert:function=org.example.AssertScope.assert</option>
281+
</pluginOptions>
282+
</configuration>
283+
284+
<dependencies>
285+
<dependency>
286+
<groupId>org.jetbrains.kotlin</groupId>
287+
<artifactId>kotlin-maven-power-assert</artifactId>
288+
<version>%kotlinVersion%</version>
289+
</dependency>
290+
</dependencies>
291+
292+
</plugin>
293+
<plugin>
294+
<artifactId>maven-surefire-plugin</artifactId>
295+
<version>2.22.2</version>
296+
</plugin>
297+
<plugin>
298+
<artifactId>maven-failsafe-plugin</artifactId>
299+
<version>2.22.2</version>
300+
</plugin>
301+
<plugin>
302+
<groupId>org.codehaus.mojo</groupId>
303+
<artifactId>exec-maven-plugin</artifactId>
304+
<version>1.6.0</version>
305+
<configuration>
306+
<mainClass>MainKt</mainClass>
307+
</configuration>
308+
</plugin>
309+
</plugins>
310+
</build>
311+
312+
<dependencies>
313+
<dependency>
314+
<groupId>org.jetbrains.kotlin</groupId>
315+
<artifactId>kotlin-test-junit5</artifactId>
316+
<version>%kotlinVersion%</version>
317+
<scope>test</scope>
318+
</dependency>
319+
<dependency>
320+
<groupId>org.junit.jupiter</groupId>
321+
<artifactId>junit-jupiter</artifactId>
322+
<version>5.10.0</version>
323+
<scope>test</scope>
324+
</dependency>
325+
<dependency>
326+
<groupId>org.jetbrains.kotlin</groupId>
327+
<artifactId>kotlin-stdlib</artifactId>
328+
<version>%kotlinVersion%</version>
329+
</dependency>
330+
</dependencies>
331+
</project>
332+
```
333+
{initial-collapse-state="collapsed" collapsible="true"}
334+
335+
</tab>
336+
</tabs>
337+
338+
149339
### Assert function
150340

151341
Consider the following test with the `assert()` function:
@@ -245,9 +435,12 @@ The Power-assert plugin can transform various functions beyond `assert` which is
245435
Functions like `require()`, `check()`, `assertTrue()`, `assertEqual()` and others can also be transformed,
246436
if they have a form that allows taking a `String` or `() -> String` value as the last parameter.
247437

248-
Before using a new function in a test, specify the function in the `powerAssert {}` block of your build script file.
438+
Before using a new function in a test, add the function to your build file.
249439
For example, the `require()` function:
250440

441+
<tabs group="build-script">
442+
<tab title="Gradle (Kotlin)" group-key="kotlin">
443+
251444
```kotlin
252445
// build.gradle.kts
253446
import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
@@ -258,6 +451,22 @@ powerAssert {
258451
}
259452
```
260453

454+
</tab>
455+
<tab title="Maven" group-key="maven">
456+
457+
```xml
458+
<!-- pom.xml -->
459+
<configuration>
460+
<pluginOptions>
461+
<option>power-assert:function=kotlin.assert</option>
462+
<option>power-assert:function=kotlin.require</option>
463+
</pluginOptions>
464+
</configuration>
465+
```
466+
</tab>
467+
</tabs>
468+
469+
261470
After adding the function, you can use it in your tests:
262471

263472
```kotlin
@@ -349,15 +558,39 @@ class AssertScopeImpl : AssertScope {
349558
}
350559
```
351560

352-
Add these functions to the `powerAssert {}` block to make them available for the Power-assert plugin:
561+
Add these functions to your build file to make them available for the Power-assert plugin:
562+
563+
<tabs group="build-script">
564+
<tab title="Gradle (Kotlin)" group-key="kotlin">
353565

354566
```kotlin
567+
// build.gradle.kts
568+
import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
569+
355570
@OptIn(ExperimentalKotlinGradlePluginApi::class)
356571
powerAssert {
357572
functions = listOf("kotlin.assert", "kotlin.test.assert", "org.example.AssertScope.assert")
358573
}
359574
```
360575

576+
</tab>
577+
<tab title="Maven" group-key="maven">
578+
579+
```xml
580+
<!-- pom.xml -->
581+
<configuration>
582+
<pluginOptions>
583+
<option>power-assert:function=kotlin.assert</option>
584+
<option>power-assert:function=kotlin.require</option>
585+
<option>power-assert:function=org.example.AssertScope.assert</option>
586+
</pluginOptions>
587+
</configuration>
588+
```
589+
</tab>
590+
</tabs>
591+
592+
593+
361594
> You should specify the full name of the package where you declare the `AssertScope.assert()` function.
362595
>
363596
{style="tip"}

0 commit comments

Comments
 (0)