Skip to content

Commit 0b04261

Browse files
kiviewrnorth
authored andcommitted
Add JUnit5/Jupiter usage instructions to docs (#954)
1 parent 8f4554f commit 0b04261

File tree

2 files changed

+41
-5
lines changed

2 files changed

+41
-5
lines changed

docs/usage.md

Lines changed: 40 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -151,11 +151,48 @@ public class SimpleMySQLTest {
151151
}
152152
```
153153

154-
### JUnit 5
154+
### Jupiter / JUnit 5
155+
156+
#### Extension
157+
158+
Jupiter integration is provided by means of the `@Testcontainers` annotation.
159+
160+
The extension finds all fields that are annotated with `@Container` and calls their container lifecycle
161+
methods (methods on the `Startable` interface). Containers declared as static fields will be shared between test
162+
methods. They will be started only once before any test method is executed and stopped after the last test method has
163+
executed. Containers declared as instance fields will be started and stopped for every test method.
164+
165+
**Note:** This extension has only be tested with sequential test execution. Using it with parallel test execution is
166+
unsupported and may have unintended side effects.
167+
168+
*Example:*
169+
```java
170+
@Testcontainers
171+
class MyTestcontainersTests {
172+
173+
// will be shared between test methods
174+
@Container
175+
private static final MySQLContainer MY_SQL_CONTAINER = new MySQLContainer();
176+
177+
// will be started before and stopped after each test method
178+
@Container
179+
private PostgreSQLContainer postgresqlContainer = new PostgreSQLContainer()
180+
.withDatabaseName("foo")
181+
.withUsername("foo")
182+
.withPassword("secret");
183+
@Test
184+
void test() {
185+
assertTrue(MY_SQL_CONTAINER.isRunning());
186+
assertTrue(postgresqlContainer.isRunning());
187+
}
188+
}
189+
```
190+
191+
#### Vanilla Integration
155192

156-
**JUnit5**: As of now, you need to manually start the container in a `@BeforeAll`/`@BeforeEach` annotated method in your tests. Tear down will be done automatically on JVM exit, but you can of course also use an `@AfterAll`/`@AfterEach` annotated method to manually call the `close()` method on your container.
193+
As an alternative, you can manually start the container in a `@BeforeAll`/`@BeforeEach` annotated method in your tests. Tear down will be done automatically on JVM exit, but you can of course also use an `@AfterAll`/`@AfterEach` annotated method to manually call the `close()` method on your container.
157194

158-
Example of starting a container in a `@BeforeEach` annotated method:
195+
*Example of starting a container in a `@BeforeEach` annotated method:*
159196

160197
```java
161198
class SimpleMySQLTest {

modules/junit-jupiter/src/main/java/org/testcontainers/junit/jupiter/Testcontainers.java

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,7 @@
1111
* {@code @Testcontainers} is a JUnit Jupiter extension to activate automatic
1212
* startup and stop of containers used in a test case.
1313
*
14-
* <p>The test containers extension finds all fields of type
15-
* {@link org.testcontainers.lifecycle.Startable} that are annotated with
14+
* <p>The test containers extension finds all fields that are annotated with
1615
* {@link Container} and calls their container lifecycle methods. Containers
1716
* declared as static fields will be shared between test methods. They will be
1817
* started only once before any test method is executed and stopped after the

0 commit comments

Comments
 (0)