From eda8753d94894619408f8c51b941a9d02cf3230f Mon Sep 17 00:00:00 2001
From: Ed Morley <501702+edmorley@users.noreply.github.com>
Date: Fri, 17 Nov 2023 12:10:47 +0000
Subject: [PATCH] libcnb-test: Document Docker resource teardown (#743)

Fixes #374.
GUS-W-14511364.
---
 CHANGELOG.md                    | 1 +
 libcnb-test/src/test_context.rs | 4 +++-
 libcnb-test/src/test_runner.rs  | 2 ++
 3 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6fd2f44d..91fd027d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Improved the consistency of all user-facing libcnb.rs error message wordings. ([#722](https://github.com/heroku/libcnb.rs/pull/722))
 - The assistance error message shown when the necessary cross-compilation tools are not found now also includes the `rustup target add` step. ([#729](https://github.com/heroku/libcnb.rs/pull/729))
+- Updated the documentation for `TestRunner::build` and `TestContext::start_container` to mention when Docker resource teardown occurs. ([#743](https://github.com/heroku/libcnb.rs/pull/743))
 
 ### Fixed
 
diff --git a/libcnb-test/src/test_context.rs b/libcnb-test/src/test_context.rs
index 6d75f7d6..807b349d 100644
--- a/libcnb-test/src/test_context.rs
+++ b/libcnb-test/src/test_context.rs
@@ -25,7 +25,9 @@ pub struct TestContext<'a> {
 }
 
 impl<'a> TestContext<'a> {
-    /// Starts a container using the provided [`ContainerConfig`].
+    /// Starts a detached container using the provided [`ContainerConfig`].
+    ///
+    /// After the passed function has returned, the Docker container is removed.
     ///
     /// If you wish to run a shell command and don't need to customise the configuration, use
     /// the convenience function [`TestContext::run_shell_command`] instead.
diff --git a/libcnb-test/src/test_runner.rs b/libcnb-test/src/test_runner.rs
index f24fafb7..08de7782 100644
--- a/libcnb-test/src/test_runner.rs
+++ b/libcnb-test/src/test_runner.rs
@@ -31,6 +31,8 @@ impl TestRunner {
     /// crate, packages it as a buildpack and then invokes [pack](https://buildpacks.io/docs/tools/pack/)
     /// to build a new Docker image with the buildpacks specified by the passed [`BuildConfig`].
     ///
+    /// After the passed test function has returned, the Docker image and volumes created by Pack are removed.
+    ///
     /// Since this function is supposed to only be used in integration tests, failures are not
     /// signalled via [`Result`] values. Instead, this function panics whenever an unexpected error
     /// occurred to simplify testing code.