Add docs for copyFile API

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

@@ -1,41 +1,68 @@
 package org.testcontainers.junit;
 
+import com.google.common.io.Files;
+import com.google.common.io.Resources;
+import org.junit.Before;
 import org.junit.Test;
 import org.testcontainers.containers.BindMode;
 import org.testcontainers.containers.GenericContainer;
 import org.testcontainers.containers.SelinuxContext;
 import org.testcontainers.utility.MountableFile;
 
+import java.io.File;
 import java.io.IOException;
 import java.util.Map;
 
+import static org.junit.Assert.assertArrayEquals;
 import static org.rnorth.visibleassertions.VisibleAssertions.assertFalse;
 import static org.rnorth.visibleassertions.VisibleAssertions.assertTrue;
 import static org.testcontainers.TestImages.TINY_IMAGE;
 
 public class CopyFileToContainerTest {
-    private static String containerPath = "/tmp/mappable-resource/";
+    public static String destinationOnHost;
+    private static String directoryInContainer = "/tmp/mappable-resource/";
     private static String fileName = "test-resource.txt";
 
+    @Before
+    public void setup() throws IOException {
+        destinationOnHost = File.createTempFile("testcontainers", null).getAbsolutePath();
+    }
+
     @Test
     public void checkFileCopied() throws IOException, InterruptedException {
+        // copyToContainer {
         try (
             GenericContainer<?> container = new GenericContainer<>(TINY_IMAGE)
                 .withCommand("sleep", "3000")
-                .withCopyFileToContainer(MountableFile.forClasspathResource("/mappable-resource/"), containerPath)
+                // withCopyFileToContainer ensure that a file or directory will be copied to the container
+                // before starting. In this case, we map a classpath directory to a directory inside the container
+                .withCopyFileToContainer(MountableFile.forClasspathResource("/mappable-resource/"), directoryInContainer)
         ) {
             container.start();
-            String filesList = container.execInContainer("ls", "/tmp/mappable-resource").getStdout();
+
+            // at this point directoryInContainer should exist, and should contain copies of file(s)
+            String filesList = container.execInContainer("ls", directoryInContainer).getStdout();
             assertTrue("file list contains the file", filesList.contains(fileName));
+
+        // }
+
+            // copyFileFromContainer {
+            container.copyFileFromContainer(directoryInContainer + fileName, destinationOnHost);
+            // }
         }
+
+        assertArrayEquals(
+            Files.toByteArray(new File(destinationOnHost)),
+            Resources.toByteArray(CopyFileToContainerTest.class.getResource("/mappable-resource/" + fileName))
+        );
     }
 
     @Test
     public void shouldUseCopyForReadOnlyClasspathResources() throws Exception {
         try (
             GenericContainer<?> container = new GenericContainer<>(TINY_IMAGE)
                 .withCommand("sleep", "3000")
-                .withClasspathResourceMapping("/mappable-resource/", containerPath, BindMode.READ_ONLY)
+                .withClasspathResourceMapping("/mappable-resource/", directoryInContainer, BindMode.READ_ONLY)
         ) {
             container.start();
             String filesList = container.execInContainer("ls", "/tmp/mappable-resource").getStdout();

docs/features/files.md

@@ -1,7 +1,26 @@
 # Files and volumes
 
+## Copying files to and from containers
+
+Files can be copied into the container before startup, or can be copied from the container after the container has started.
+
+### Copying to a container before startup
+
+<!--codeinclude-->
+[Copying files to a container](../../core/src/test/java/org/testcontainers/junit/CopyFileToContainerTest.java) inside_block:copyToContainer
+<!--/codeinclude-->
+
+### Copying a file from a running container
+
+<!--codeinclude-->
+[Copying files from a container](../../core/src/test/java/org/testcontainers/junit/CopyFileToContainerTest.java) inside_block:copyFileFromContainer
+<!--/codeinclude-->
+
 ## File mapping
 
+!!! warning
+    This feature is not supported for all Docker environments. Consider using the `copy` APIs instead.
+
 It is possible to map a file or directory from your FileSystem into the container as a volume using `withFileSystemBind`:
 ```java
 String pathToFile = System.getProperty("user.home") + "/.aws";
@@ -11,10 +30,14 @@ new GenericContainer(...)
 
 ## Volume mapping
 
+!!! warning
+    This feature is not supported for all Docker environments. Consider using the `copy` APIs instead.
+
 It is possible to map a file or directory **on the classpath** into the container as a volume using `withClasspathResourceMapping`:
 ```java
 new GenericContainer(...)
         .withClasspathResourceMapping("redis.conf",
                                       "/etc/redis.conf",
                                       BindMode.READ_ONLY)
 ```
+