heroku · edmorley · Jul 19, 2022 · Jul 18, 2022 · Jul 19, 2022 · Jul 19, 2022
@@ -7,23 +7,19 @@
 // https://rust-lang.github.io/rust-clippy/stable/index.html
 #![warn(clippy::pedantic)]
 
-use libcnb_test::{assert_contains, TestConfig, TestRunner};
+use libcnb_test::{assert_contains, assert_empty, TestConfig, TestRunner};
 
 #[test]
 #[ignore]
 fn basic() {
     TestRunner::default().run_test(
         TestConfig::new("heroku/builder:22", "test-fixtures/empty-app"),
         |context| {
-            context
-                .prepare_container()
-                .start_with_shell_command("env", |container| {
-                    let env_stdout = container.logs_wait().stdout;
-
-                    assert_contains!(env_stdout, "ROLL_1D6=");
-                    assert_contains!(env_stdout, "ROLL_4D6=");
-                    assert_contains!(env_stdout, "ROLL_1D20=");
-                });
+            let log_output = context.run_shell_command("env");
+            assert_empty!(log_output.stderr);
+            assert_contains!(log_output.stdout, "ROLL_1D6=");
+            assert_contains!(log_output.stdout, "ROLL_4D6=");
+            assert_contains!(log_output.stdout, "ROLL_1D20=");
         },
     );
 }
@@ -7,7 +7,9 @@
 // https://rust-lang.github.io/rust-clippy/stable/index.html
 #![warn(clippy::pedantic)]
 
-use libcnb_test::{assert_contains, assert_not_contains, PackResult, TestConfig, TestRunner};
+use libcnb_test::{
+    assert_contains, assert_not_contains, ContainerConfig, PackResult, TestConfig, TestRunner,
+};
 use std::io::{Read, Write};
 use std::net;
 use std::net::ToSocketAddrs;
@@ -24,11 +26,11 @@ fn basic() {
         assert_contains!(context.pack_stdout, "---> Installing bundler");
         assert_contains!(context.pack_stdout, "---> Installing gems");
 
-        context
-            .prepare_container()
-            .env("PORT", TEST_PORT.to_string())
-            .expose_port(TEST_PORT)
-            .start_with_default_process(|container| {
+        context.start_container(
+            ContainerConfig::new()
+                .env("PORT", TEST_PORT.to_string())
+                .expose_port(TEST_PORT),
+            |container| {
                 std::thread::sleep(Duration::from_secs(2));
 
                 assert_eq!(
@@ -39,12 +41,13 @@ fn basic() {
                     .unwrap(),
                     "!dlroW olleH"
                 );
+            },
+        );
 
-                assert_contains!(
-                    container.shell_exec("ruby --version").stdout,
-                        "ruby 2.7.0p0"
-                );
-            });
+        assert_contains!(
+            context.run_shell_command("ruby --version").stdout,
+            "ruby 2.7.0p0"
+        );
 
         context.run_test(&config, |context| {
             assert_not_contains!(context.pack_stdout, "---> Installing bundler");

@@ -2,6 +2,9 @@
 
 ## [Unreleased]
 
+- Add `TestContext::start_container`, `TestContext::run_shell_command` and `ContainerConfig`. ([#469](https://github.com/heroku/libcnb.rs/pull/469))
+- Remove `TestContext::prepare_container` and `PrepareContainerContext`. To start a container use `TestContext::start_container` combined with `ContainerConfig` (or else the convenience function `TestContext::run_shell_command`) instead. ([#469](https://github.com/heroku/libcnb.rs/pull/469))
+
 ## [0.5.0] 2022-07-14
 
 - Add an `assert_empty!` macro, for improved UX over using `assert!` with `str::is_empty`. ([#451](https://github.com/heroku/libcnb.rs/pull/451))

@@ -15,7 +15,7 @@ Please use the same tag for feature requests.
 
 ```rust,no_run
 // In $CRATE_ROOT/tests/integration_test.rs
-use libcnb_test::{assert_contains, TestConfig, TestRunner};
+use libcnb_test::{assert_contains, ContainerConfig, TestConfig, TestRunner};
 
 // In your code you'll want to mark your function as a test with `#[test]`.
 // It is removed here for compatibility with doctest so this code in the readme
@@ -28,10 +28,11 @@ fn test() {
             assert_contains!(context.pack_stdout, "---> Installing Maven");
             assert_contains!(context.pack_stdout, "---> Running mvn package");
 
-            context
-                .prepare_container()
-                .expose_port(12345)
-                .start_with_default_process(|container| {
+            context.start_container(
+                ContainerConfig::new()
+                    .env("PORT", "12345")
+                    .expose_port(12345),
+                |container| {
                     assert_eq!(
                         call_test_fixture_service(
                             container.address_for_port(12345).unwrap(),
@@ -40,7 +41,8 @@ fn test() {
                         .unwrap(),
                         "enileC drabgaH"
                     );
-                });
+                },
+            );
         },
     );
 }

@@ -0,0 +1,198 @@
+use std::collections::HashMap;
+
+/// Config used when starting a container.
+///
+/// By default the container will run the CNB default process-type, however this can be
+/// overridden using [`ContainerConfig::entrypoint`] and [`ContainerConfig::command`].
+/// See: [CNB App Developer Guide: Run a multi-process app](https://buildpacks.io/docs/app-developer-guide/run-an-app/#run-a-multi-process-app)
+///
+/// # Example
+/// ```no_run
+/// use libcnb_test::{ContainerConfig, TestConfig, TestRunner};
+///
+/// TestRunner::default().run_test(
+///     TestConfig::new("heroku/builder:22", "test-fixtures/app"),
+///     |context| {
+///         // ...
+///         context.start_container(
+///             ContainerConfig::new().env("PORT", "12345").expose_port(12345),
+///             |container| {
+///                 // ...
+///             },
+///         );
+///     },
+/// );
+/// ```
+#[derive(Default)]
+pub struct ContainerConfig {
+    pub(crate) entrypoint: Option<Vec<String>>,
+    pub(crate) command: Option<Vec<String>>,
+    pub(crate) env: HashMap<String, String>,
+    pub(crate) exposed_ports: Vec<u16>,
+}
+
+impl ContainerConfig {
+    /// Creates an empty [`ContainerConfig`] instance.
+    ///
+    /// By default the container will run the CNB default process-type, however this can be
+    /// overridden using [`ContainerConfig::entrypoint`] and [`ContainerConfig::command`].
+    /// See: [CNB App Developer Guide: Run a multi-process app](https://buildpacks.io/docs/app-developer-guide/run-an-app/#run-a-multi-process-app)
+    ///
+    /// # Example
+    /// ```no_run
+    /// use libcnb_test::{ContainerConfig, TestConfig, TestRunner};
+    ///
+    /// TestRunner::default().run_test(
+    ///     TestConfig::new("heroku/builder:22", "test-fixtures/app"),
+    ///     |context| {
+    ///         // ...
+    ///         context.start_container(
+    ///             ContainerConfig::new().env("PORT", "12345").expose_port(12345),
+    ///             |container| {
+    ///                 // ...
+    ///             },
+    ///         );
+    ///     },
+    /// );
+    /// ```
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    ///
+    /// See: [CNB App Developer Guide: Run a multi-process app](https://buildpacks.io/docs/app-developer-guide/run-an-app/#run-a-multi-process-app)
+    ///
+    /// # Example
+    /// ```no_run
+    /// use libcnb_test::{ContainerConfig, TestConfig, TestRunner};
+    ///
+    /// TestRunner::default().run_test(
+    ///     TestConfig::new("heroku/builder:22", "test-fixtures/app"),
+    ///     |context| {
+    ///         // ...
+    ///         context.start_container(ContainerConfig::new().entrypoint(["worker"]), |container| {
+    ///             // ...
+    ///         });
+    ///     },
+    /// );
+    /// ```
+    pub fn entrypoint<I: IntoIterator<Item = S>, S: Into<String>>(
+        &mut self,
+        entrypoint: I,
+    ) -> &mut Self {
+        self.entrypoint = Some(entrypoint.into_iter().map(S::into).collect());
+        self
+    }
+
+    /// Set the container's `command` (CNB images have no default command).
+    ///
+    /// See: [CNB App Developer Guide: Run a multi-process app](https://buildpacks.io/docs/app-developer-guide/run-an-app/#run-a-multi-process-app)
+    ///
+    /// # Example
+    /// ```no_run
+    /// use libcnb_test::{ContainerConfig, TestConfig, TestRunner};
+    ///
+    /// TestRunner::default().run_test(
+    ///     TestConfig::new("heroku/builder:22", "test-fixtures/app"),
+    ///     |context| {
+    ///         // ...
+    ///         context.start_container(
+    ///             ContainerConfig::new().command(["--additional-arg1", "--additional-arg2"]),
+    ///             |container| {
+    ///                 // ...
+    ///             },
+    ///         );
+    ///     },
+    /// );
+    /// ```
+    pub fn command<I: IntoIterator<Item = S>, S: Into<String>>(&mut self, command: I) -> &mut Self {
+        self.command = Some(command.into_iter().map(S::into).collect());
+        self
+    }
+
+    /// Exposes a given port of the container to the host machine.
+    ///
+    /// The given port is mapped to a random port on the host machine. Use
+    /// [`crate::ContainerContext::address_for_port`] to obtain the local port for a mapped port.
+    ///
+    /// # Example
+    /// ```no_run
+    /// use libcnb_test::{ContainerConfig, TestConfig, TestRunner};
+    ///
+    /// TestRunner::default().run_test(
+    ///     TestConfig::new("heroku/builder:22", "test-fixtures/app"),
+    ///     |context| {
+    ///         // ...
+    ///         context.start_container(
+    ///             ContainerConfig::new().env("PORT", "12345").expose_port(12345),
+    ///             |container| {
+    ///                 let port_on_host = container.address_for_port(12345).unwrap();
+    ///                 // ...
+    ///             },
+    ///         );
+        ///     },
+    /// );
+    /// ```
+    pub fn expose_port(&mut self, port: u16) -> &mut Self {
+        self.exposed_ports.push(port);
+        self
+    }
+
+    /// Inserts or updates an environment variable mapping for the container.
+    ///
+    /// # Example
+    /// ```no_run
+    /// use libcnb_test::{ContainerConfig, TestConfig, TestRunner};
+    ///
+    /// TestRunner::default().run_test(
+    ///     TestConfig::new("heroku/builder:22", "test-fixtures/app"),
+    ///     |context| {
+    ///         // ...
+    ///         context.start_container(
+    ///             ContainerConfig::new()
+    ///                 .env("PORT", "5678")
+    ///                 .env("DEBUG", "true"),
+    ///             |container| {
+    ///                 // ...
+    ///             },
+    ///         );
+    ///     },
+    /// );
+    /// ```
+    pub fn env(&mut self, key: impl Into<String>, value: impl Into<String>) -> &mut Self {
+        self.env.insert(key.into(), value.into());
+        self
+    }
+
+    /// Adds or updates multiple environment variable mappings for the container.
+    ///
+    /// # Example
+    /// ```no_run
+    /// use libcnb_test::{ContainerConfig, TestConfig, TestRunner};
+    ///
+    /// TestRunner::default().run_test(
+    ///     TestConfig::new("heroku/builder:22", "test-fixtures/app"),
+    ///     |context| {
+    ///         // ...
+    ///         context.start_container(
+    ///             ContainerConfig::new().envs(vec![("PORT", "5678"), ("DEBUG", "true")]),
+    ///             |container| {
+    ///                 // ...
+    ///             },
+    ///         );
+    ///     },
+    /// );
+    /// ```
+    pub fn envs<K: Into<String>, V: Into<String>, I: IntoIterator<Item = (K, V)>>(
+        &mut self,
+        envs: I,
+    ) -> &mut Self {
+        envs.into_iter().for_each(|(key, value)| {
+            self.env(key.into(), value.into());
+        });
+
+        self
+    }
+}