Allow testcontainers to have custom labels

core/src/main/java/org/testcontainers/containers/Container.java

@@ -79,6 +79,15 @@ public String getStderr() {
      */
     void addEnv(String key, String value);
 
+    /**
+     * Add a label to the container. Consider using {@link #withLabel(String, String)}
+     * for build a container in a fluent style.
+     *
+     * @param key   label key
+     * @param value label value
+     */
+    void addLabel(String key, String value);
+
     /**
      * Adds a file system binding. Consider using {@link #withFileSystemBind(String, String, BindMode)}
      * for building a container in a fluent style.
@@ -204,6 +213,22 @@ default SELF withEnv(String key, Function<Optional<String>, String> mapper) {
      */
     SELF withEnv(Map<String, String> env);
 
+    /**
+     * Add a label to the container.
+     *
+     * @param key   label key
+     * @param value label value
+     * @return this
+     */
+    SELF withLabel(String key, String value);
+
+    /**
+     * Add labels to the container.
+     * @param labels map of labels
+     * @return this
+     */
+    SELF withLabels(Map<String, String> labels);
+
     /**
      * Set the command that should be run in the container
      *

core/src/main/java/org/testcontainers/containers/GenericContainer.java

@@ -110,6 +110,9 @@ public class GenericContainer<SELF extends GenericContainer<SELF>>
     @NonNull
     private Map<String, String> env = new HashMap<>();
 
+    @NonNull
+    private Map<String, String> labels = new HashMap<>();
+
     @NonNull
     private String[] commandParts = new String[0];
 
@@ -473,6 +476,7 @@ private void applyConfiguration(CreateContainerCmd createCommand) {
         Map<String, String> labels = createCommand.getLabels();
         labels = new HashMap<>(labels != null ? labels : Collections.emptyMap());
         labels.putAll(DockerClientFactory.DEFAULT_LABELS);
+        labels.putAll(this.labels);
         createCommand.withLabels(labels);
     }
 
@@ -580,6 +584,14 @@ public void addEnv(String key, String value) {
         env.put(key, value);
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public void addLabel(String key, String value) {
+        labels.put(key, value);
+    }
+
     /**
      * {@inheritDoc}
      */
@@ -700,6 +712,24 @@ public SELF withEnv(Map<String, String> env) {
         return self();
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public SELF withLabel(String key, String value) {
+        this.addLabel(key, value);
+        return self();
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public SELF withLabels(Map<String, String> labels) {
+        labels.forEach(this::addLabel);
+        return self();
+    }
+
     /**
      * {@inheritDoc}
      */

core/src/test/java/org/testcontainers/junit/GenericContainerRuleTest.java

@@ -22,6 +22,7 @@
 import java.net.Socket;
 import java.time.Duration;
 import java.util.Arrays;
+import java.util.Map;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
 import java.util.regex.Matcher;
@@ -127,6 +128,15 @@ public static void setupContent() throws FileNotFoundException {
             .withExtraHost("somehost", "192.168.1.10")
             .withCommand("/bin/sh", "-c", "while true; do cat /etc/hosts | nc -l -p 80; done");
 
+    /**
+     * Create a container with a custom label for testing.
+     */
+    @ClassRule
+    public static GenericContainer alpineCustomLabel = new GenericContainer("alpine:3.2")
+            .withExposedPorts(80)
+            .withLabel("our.custom", "label")
+            .withCommand("/bin/sh", "-c", "while true; do cat /etc/hosts | nc -l -p 80; done");
+
 //    @Test
 //    public void simpleRedisTest() {
 //        String ipAddress = redis.getContainerIpAddress();
@@ -220,6 +230,14 @@ public void environmentFromMapTest() throws IOException {
         assertEquals("Environment variables can be passed into a command from a map", "42 and 50", line);
     }
 
+    @Test
+    public void customLabelTest() {
+        Map<String, String> labels = alpineCustomLabel.getCurrentContainerInfo().getConfig().getLabels();
+        assertTrue("org.testcontainers label is present", labels.containsKey("org.testcontainers"));
+        assertTrue("our.custom label is present", labels.containsKey("our.custom"));
+        assertEquals("our.custom label value is label", labels.get("our.custom"), "label");
+    }
+
     @Test
     public void customClasspathResourceMappingTest() throws IOException {
         // Note: This functionality doesn't work if you are running your build inside a Docker container;
@@ -341,7 +359,7 @@ public void copyToContainerTest() throws Exception {
 
         try (final GenericContainer alpineCopyToContainer = new GenericContainer("alpine:3.2")
                     .withCommand("top")){
-            
+
             alpineCopyToContainer.start();
             final MountableFile mountableFile = MountableFile.forClasspathResource("test_copy_to_container.txt");
             alpineCopyToContainer.copyFileToContainer(mountableFile, "/home/");

docs/usage/generic_containers.md

@@ -23,12 +23,15 @@ public static GenericContainer redis =
 
 // Set up a plain OS container and customize environment, 
 //   command and exposed ports. This just listens on port 80 
-//   and always returns '42'
+//   and always returns '42'.
+//   The container will have a custom label named 'our.custom'
+//   with a value 'label'.
 @ClassRule
 public static GenericContainer alpine =
 	new GenericContainer("alpine:3.2")
     		.withExposedPorts(80)
                .withEnv("MAGIC_NUMBER", "42")
+               .withLabel("our.custom", "label")
                .withCommand("/bin/sh", "-c", 
                "while true; do echo \"$MAGIC_NUMBER\" | nc -l -p 80; done");
 ```
@@ -46,4 +49,4 @@ The class rule provides methods for discovering how your tests can interact with
 For example, with the Redis example above, the following will allow your tests to access the Redis service:
 ```java
 String redisUrl = redis.getContainerIpAddress() + ":" + redis.getMappedPort(6379);
-```
+```

docs/usage/options.md

@@ -29,6 +29,14 @@ new GenericContainer(...)
 		.withEnv("API_TOKEN", "foo")
 ```
 
+### Labels
+
+To add a custom label to the container, use `withLabel`:
+```java
+new GenericContainer(...)
+        .withLabel("your.custom", "label")
+```
+
 ### Command
 
 By default the container will execute whatever command is specified in the image's Dockerfile. To override this, and specify a different command, use `withCommand`: