From 60452e1a1644ba3656736596af05d8f2aff9f989 Mon Sep 17 00:00:00 2001 From: Janne Koschinski <janne@kuschku.de> Date: Fri, 12 Feb 2021 16:28:08 +0100 Subject: [PATCH] Cleanup API and documentation --- README.md | 69 ++++++++----------- .../testcontainersci/api/providedContainer.kt | 8 ++- 2 files changed, 34 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 00bc3eb..827fd73 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,39 @@ -# Kotlin Bitflags +# Testcontainers-CI -Kotlin-Bitflags is a utility library to simplify implementing bitflags in Kotlin. It integrates with Kotlin unsigned -types and Java Enumsets. This especially useful when interacting with binary protocols from Kotlin. +Testcontainers-CI allows you to easily use testcontainers whenever you can, but use containers created through other +means whenever you can’t. -## Using Kotlin-Bitflags +When running your CI in docker, you can’t launch new containers without DinD, but thanks to Gitlab Ci Services you can +run a docker container with the desired service and use it in your code easily. -After adding this module to your dependencies, you'll have to implement the related interfaces in your classes: +This project simplifies this process, by providing a façade for both types of containers. -```kotlin -enum class MessageFlag( - override val value: UInt, -) : Flag<UInt> { - Self(0x01u), - Highlight(0x02u), - Redirected(0x04u), - ServerMsg(0x08u), - Backlog(0x80u); - - companion object : Flags<UInt, MessageFlag> { - override val all: Set<MessageFlag> = values().toEnumSet() - } -} -``` - -This allows you to then use this elsewhere to e.g initialize a field from discrete values -```kotlin -// Construct from varargs or an array -val field = MessageFlag.of(MessageFlag.Self, MessageFlag.Highlight) +## Using Testcontainers-CI -val values = listOf(MessageFlag.Self, MessageFlag.Highlight) -// Or from a collection -val field = MessageFlag.of(values) -// Or use the to helper -val field = values.toEnumSet() -``` +After adding this module to your dependencies, you can just wrap your calls creating testcontainers with the +`providedContainer` function, and it’ll return either the Testcontainer, or the provided container, whichever is +available in the current environment. -You can also convert such a field into the raw binary value easily ```kotlin -// Returns in this case UInt -field.toBits() +@CiContainers +class MyLittleTest { + private val container = providedContainer("REDIS_CONTAINER") { + GenericContainer(DockerImageName.parse("redis:5.0.3-alpine")) + .withExposedPorts(6379); + } + + @Test + fun test() { + println(container.address) + println(container.getMappedPort(6379)) + } +} ``` -Additional utility functions are available: -```kotlin -// Empty field -MessageFlag.none() -// Get all non-null values -MessageFlag.validValues() +```yaml + services: + - name: "redis:5.0.3-alpine" + alias: "test_redis_instance" + variables: + REDIS_CONTAINER: "test_redis_instance" ``` diff --git a/src/main/kotlin/de/justjanne/testcontainersci/api/providedContainer.kt b/src/main/kotlin/de/justjanne/testcontainersci/api/providedContainer.kt index ce43039..5a0fb2a 100644 --- a/src/main/kotlin/de/justjanne/testcontainersci/api/providedContainer.kt +++ b/src/main/kotlin/de/justjanne/testcontainersci/api/providedContainer.kt @@ -10,16 +10,18 @@ package de.justjanne.testcontainersci.api import de.justjanne.testcontainersci.implementation.GitlabCiProvidedContainer +import de.justjanne.testcontainersci.implementation.TestContainersProvidedContainer +import org.testcontainers.containers.GenericContainer import java.net.InetAddress /** * Build a provided container from an environment variable and a builder for a local container */ -fun providedContainer( +fun <T : GenericContainer<T>> providedContainer( envVariable: String, - containerBuilder: () -> ProvidedContainer + containerBuilder: () -> T ) = when { !System.getenv(envVariable).isNullOrEmpty() -> GitlabCiProvidedContainer(InetAddress.getByName(System.getenv(envVariable))) - else -> containerBuilder() + else -> TestContainersProvidedContainer(containerBuilder()) } -- GitLab