Add docs for copyFile API (#4661)

Co-authored-by: Sumit Anvekar <[email protected]>
Co-authored-by: Richard North <[email protected]>
Co-authored-by: Eddú Meléndez <[email protected]>

Author: 4 people

core/src/test/java/org/testcontainers/containers/GenericContainerTest.java

@@ -82,11 +82,13 @@ public void shouldReportErrorAfterWait() {
     @Test
     public void shouldCopyTransferableAsFile() {
         try (
+            // transferableFile {
             GenericContainer<?> container = new GenericContainer<>(TestImages.TINY_IMAGE)
                 .withStartupCheckStrategy(new NoopStartupCheckStrategy())
                 .withCopyToContainer(Transferable.of("test"), "/tmp/test")
                 .waitingFor(new WaitForExitedState(state -> state.getExitCodeLong() > 0))
                 .withCommand("sh", "-c", "grep -q test /tmp/test && exit 100")
+            // }
         ) {
             assertThatThrownBy(container::start)
                 .hasStackTraceContaining("Wait strategy failed. Container exited with code 100")
@@ -97,11 +99,13 @@ public void shouldCopyTransferableAsFile() {
     @Test
     public void shouldCopyTransferableAsFileWithFileMode() {
         try (
+            // transferableWithFileMode {
             GenericContainer<?> container = new GenericContainer<>(TestImages.TINY_IMAGE)
                 .withStartupCheckStrategy(new NoopStartupCheckStrategy())
                 .withCopyToContainer(Transferable.of("test", 0777), "/tmp/test")
                 .waitingFor(new WaitForExitedState(state -> state.getExitCodeLong() > 0))
                 .withCommand("sh", "-c", "ls -ll /tmp | grep '\\-rwxrwxrwx\\|test' && exit 100")
+            // }
         ) {
             assertThatThrownBy(container::start)
                 .hasStackTraceContaining("Wait strategy failed. Container exited with code 100")

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

@@ -1,42 +1,65 @@
 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.TestImages;
 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.assertj.core.api.Assertions.assertThat;
 
 public class CopyFileToContainerTest {
 
-    private static String containerPath = "/tmp/mappable-resource/";
+    private 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 {
         try (
+            // copyToContainer {
             GenericContainer<?> container = new GenericContainer<>(TestImages.TINY_IMAGE)
                 .withCommand("sleep", "3000")
-                .withCopyFileToContainer(MountableFile.forClasspathResource("/mappable-resource/"), containerPath)
+                .withCopyFileToContainer(
+                    MountableFile.forClasspathResource("/mappable-resource/"),
+                    directoryInContainer
+                )
+            // }
         ) {
             container.start();
-            String filesList = container.execInContainer("ls", "/tmp/mappable-resource").getStdout();
+            String filesList = container.execInContainer("ls", directoryInContainer).getStdout();
             assertThat(filesList).as("file list contains the file").contains(fileName);
+
+            // copyFileFromContainer {
+            container.copyFileFromContainer(directoryInContainer + fileName, destinationOnHost);
+            // }
         }
+
+        assertThat(Files.toByteArray(new File(destinationOnHost)))
+            .isEqualTo(Resources.toByteArray(getClass().getResource("/mappable-resource/" + fileName)));
     }
 
     @Test
     public void shouldUseCopyForReadOnlyClasspathResources() throws Exception {
         try (
             GenericContainer<?> container = new GenericContainer<>(TestImages.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,5 +1,36 @@
 # Files and volumes
 
+## Copying files
+
+Files can be copied into the container before startup, or can be copied from the container after the container has started.
+
+!!! note
+    This is the recommended approach for portability cross-docker environments.
+
+### Copying to a container before startup
+
+<!--codeinclude-->
+[Copying files using MountableFile](../../core/src/test/java/org/testcontainers/junit/CopyFileToContainerTest.java) inside_block:copyToContainer
+<!--/codeinclude-->
+
+Using `Transferable`, file content will be placed in the specified location.
+
+<!--codeinclude-->
+[Copying files using Transferable](../../core/src/test/java/org/testcontainers/containers/GenericContainerTest.java) inside_block:transferableFile
+<!--/codeinclude-->
+
+Setting file mode is also possible. 
+
+<!--codeinclude-->
+[Copying files using Transferable with file mode](../../core/src/test/java/org/testcontainers/containers/GenericContainerTest.java) inside_block:transferableWithFileMode
+<!--/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
 
 It is possible to map a file or directory from your FileSystem into the container as a volume using `withFileSystemBind`:
@@ -18,3 +49,4 @@ new GenericContainer(...)
                                       "/etc/redis.conf",
                                       BindMode.READ_ONLY)
 ```
+