Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation, chapter 'Testing environment variables:': add Kotlin test sample #1344

Merged
merged 1 commit into from
Mar 18, 2021
Merged

Documentation, chapter 'Testing environment variables:': add Kotlin test sample #1344

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
54 changes: 42 additions & 12 deletions docs/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12128,13 +12128,17 @@ fun main(args: Array<String>) : Unit = exitProcess(CommandLine(PicocliApp()).exe
=== Testing Environment Variables

Since picocli offers support for using <<Variable Interpolation,environment variables>> in the annotations, you may want to test this.
Depending on your programming language, your environment and your testing framework, you have several options:

==== Java 8+ with `withEnvironmentVariable`
Applications that use JUnit 5 or Java 8+ can use Stephan Birkner's https://github.com/stefanbirkner/system-lambda[System-Lambda] project for https://github.com/stefanbirkner/system-lambda#environment-variables[testing environment variables].
* **Java 8**: You can use Stephan Birkner's https://github.com/stefanbirkner/system-lambda[System-Lambda] project for testing https://github.com/stefanbirkner/system-lambda#environment-variables[environment variables]

Example usage:
* **Java + Junit 4**: You can use Stephan Birkner's https://stefanbirkner.github.io/system-rules[System-Rules] project for testing the https://stefanbirkner.github.io/system-rules/#EnvironmentVariables[environment variables].
* **Kotlin + Kotest**: Kotlin coders you may use the https://kotest.io/[Kotest] test framework which comes with https://kotest.io/docs/extensions/system_extensions.html#system-environment[System Environment] extension that allow you to test environment variables.

[source,java]
The listing below provides code samples for the three options mentioned above:

.Java 8
[source,java,role=primary]
----
import static com.github.stefanbirkner.systemlambda.SystemLambda.withEnvironmentVariable;
// ...
Expand All @@ -12153,16 +12157,13 @@ void testEnvVar() throws Exception {

String expected = String.format("" +
"Usage: <main class> [--option=<option>]%n" +
" --option=<option> Some options. Default: some-value%n");
" --option=<option> Some option. Default: some-value%n");
assertEquals(expected, actual);
}
----


==== JUnit 4 with `EnvironmentVariables`
Applications that use JUnit 4 can use Stephan Birkner's https://stefanbirkner.github.io/system-rules[System-Rules] project for https://stefanbirkner.github.io/system-rules/#EnvironmentVariables[testing environment variables].

[source,java]
.Java/JUnit 4
[source,java,role=secondary]
----
import org.junit.contrib.java.lang.system.EnvironmentVariables;
// ...
Expand All @@ -12183,16 +12184,45 @@ class MyTest {
environmentVariables.set("OTHER_VAR", "second value");

String actual = new CommandLine(new MyApp())
.getUsageMessage(CommandLine.Help.Ansi.OFF));
.getUsageMessage(CommandLine.Help.Ansi.OFF);

String expected = String.format("" +
"Usage: <main class> [--option=<option>]%n" +
" --option=<option> Some options. Default: some-value%n");
" --option=<option> Some option. Default: some-value%n");
assertEquals(expected, actual);
}
}
----

.Kotlin/Kotest
[source,kotlin,role=secondary]
----
import io.kotest.core.spec.style.StringSpec
import io.kotest.extensions.system.withEnvironment
import io.kotest.matchers.shouldBe
import picocli.CommandLine
import picocli.CommandLine.Command

class EnvironmentVarTest : StringSpec() {
init {
"env var" {
withEnvironment(mapOf("MYVAR" to "some-value", "OTHER_VAR" to "second value")) {
CommandLine(MyApp()).getUsageMessage(CommandLine.Help.Ansi.OFF) shouldBe
"Usage: <main class> [--option=<option>]" + System.lineSeparator() +
" --option=<option> Some option. Default: some-value" + System.lineSeparator()
}
}
}
}

@Command
class MyApp {
@CommandLine.Option(names = ["--option"], defaultValue = "\${env:MYVAR}",
description = ["Some option. Default: \${DEFAULT-VALUE}"])
lateinit var option: String
}
----

CAUTION: The latest versions of `com.github.stefanbirkner:system-rules`, 1.18 and 1.19, have an https://github.com/stefanbirkner/system-rules/issues/70[issue] that means the Environment Variables rule will not work in JUnit 5. Use System Rules version 1.17.2 instead when combining with JUnit 5.

=== Mocking
Expand Down