refactor: improve cleanup function naming and semantic clarity

- Rename cleanup_lingering_resources to preflight_cleanup_previous_resources
- Rename cleanup_infrastructure to cleanup_test_infrastructure
- Add separate stop_test_infrastructure function for containers
- Distinguish between stopping containers (immediate) and cleanup (automatic)
- Add comprehensive documentation explaining two-phase cleanup strategy
- Clarify container vs VM management differences in documentation
- Maintain API symmetry while being honest about actual operations

This improves code clarity by making function names accurately reflect
their actual behavior, especially the distinction between container
stopping (explicit) and deletion (automatic via testcontainers).

Author: josecelano

src/bin/e2e_config_tests.rs

@@ -25,11 +25,28 @@
 //!
 //! ## Test Workflow
 //!
-//! 1. **Container setup** - Build and start Docker container using `docker/provisioned-instance`
-//! 2. **SSH verification** - Ensure container is ready for Ansible connectivity
-//! 3. **Configuration** - Apply Ansible playbooks to configure services
-//! 4. **Validation** - Verify deployments are working correctly  
-//! 5. **Cleanup** - Stop and remove test containers
+//! 1. **Preflight cleanup** - Remove any artifacts from previous test runs that may have failed to clean up
+//! 2. **Container setup** - Build and start Docker container using `docker/provisioned-instance`
+//! 3. **SSH verification** - Ensure container is ready for Ansible connectivity
+//! 4. **Configuration** - Apply Ansible playbooks to configure services
+//! 5. **Validation** - Verify deployments are working correctly  
+//! 6. **Stop container** - Stop the test container (deletion handled automatically by testcontainers)
+//! 7. **Test infrastructure cleanup** - No-op for containers (automatic), called for symmetry with VMs
+//!
+//! ## Two-Phase Cleanup Strategy
+//!
+//! The cleanup process happens in two distinct phases:
+//!
+//! - **Phase 1 - Preflight cleanup**: Removes artifacts from previous test runs that may have
+//!   failed to clean up properly (executed at the start in main function)
+//! - **Phase 2 - Test infrastructure cleanup**: For containers, this is automatic via testcontainers
+//!   (called as no-op in main function for symmetry with VM workflows)
+//!
+//! ## Container vs VM Management
+//!
+//! - **Container stopping**: Happens immediately after tests (in test function) for resource management
+//! - **Container cleanup**: Automatic via testcontainers library (no explicit action needed)
+//! - **Symmetry**: Both workflows have stop+cleanup phases, but container cleanup is automatic
 //!
 //! This approach addresses network connectivity issues with LXD VMs on GitHub Actions
 //! while maintaining comprehensive testing of the configuration and deployment phases.
@@ -51,7 +68,7 @@ use torrust_tracker_deploy::domain::{Environment, EnvironmentName};
 use torrust_tracker_deploy::e2e::context::{TestContext, TestContextType};
 use torrust_tracker_deploy::e2e::tasks::{
     container::{
-        cleanup_infrastructure::cleanup_infrastructure,
+        cleanup_infrastructure::{cleanup_test_infrastructure, stop_test_infrastructure},
         run_provision_simulation::run_provision_simulation,
     },
     preflight_cleanup,
@@ -126,10 +143,16 @@ pub async fn main() -> Result<()> {
     let test_context =
         TestContext::from_environment(false, environment, TestContextType::Container)?.init()?;
 
-    preflight_cleanup::cleanup_lingering_resources(&test_context)?;
+    // Cleanup any artifacts from previous test runs that may have failed to clean up
+    // This ensures a clean slate before starting new tests
+    preflight_cleanup::preflight_cleanup_previous_resources(&test_context)?;
 
     let test_result = run_configuration_tests(&test_context).await;
 
+    // Cleanup test infrastructure created during this test run
+    // For containers, this is automatic via testcontainers (no-op), but called for symmetry with VMs
+    cleanup_test_infrastructure();
+
     let test_duration = test_start.elapsed();
 
     info!(
@@ -178,8 +201,9 @@ async fn run_configuration_tests(test_context: &TestContext) -> Result<()> {
     )
     .await?;
 
-    // Step 4: Cleanup container
-    cleanup_infrastructure(running_container);
+    // Stop test infrastructure (container) created during this test run
+    // This stops the container immediately after tests - deletion is automatic via testcontainers
+    stop_test_infrastructure(running_container);
 
     info!("Configuration tests completed successfully");
 

src/bin/e2e_provision_tests.rs

@@ -28,10 +28,19 @@
 //!
 //! ## Test Workflow
 //!
-//! 1. **Preflight cleanup** - Remove any lingering test resources
+//! 1. **Preflight cleanup** - Remove any artifacts from previous test runs that may have failed to clean up
 //! 2. **Infrastructure provisioning** - Create VMs/containers using `OpenTofu`
 //! 3. **Basic validation** - Verify VM is created and cloud-init completed
-//! 4. **Cleanup** - Remove test resources
+//! 4. **Test infrastructure cleanup** - Remove test resources created during this run
+//!
+//! ## Two-Phase Cleanup Strategy
+//!
+//! The cleanup process happens in two distinct phases:
+//!
+//! - **Phase 1 - Preflight cleanup**: Removes artifacts from previous test runs that may have
+//!   failed to clean up properly (executed at the start in main function)
+//! - **Phase 2 - Test infrastructure cleanup**: Destroys resources created specifically during
+//!   the current test run (executed at the end in main function)
 //!
 //! This split allows provisioning tests to run reliably on GitHub Actions
 //! while configuration tests can be handled separately with different infrastructure.
@@ -46,7 +55,8 @@ use tracing::{error, info};
 use torrust_tracker_deploy::domain::{Environment, EnvironmentName};
 use torrust_tracker_deploy::e2e::context::{TestContext, TestContextType};
 use torrust_tracker_deploy::e2e::tasks::virtual_machine::{
-    cleanup_infrastructure::cleanup_infrastructure, preflight_cleanup::cleanup_lingering_resources,
+    cleanup_infrastructure::cleanup_test_infrastructure,
+    preflight_cleanup::preflight_cleanup_previous_resources,
     run_provision_command::run_provision_command,
 };
 use torrust_tracker_deploy::logging::{self, LogFormat};
@@ -127,14 +137,17 @@ pub async fn main() -> Result<()> {
         TestContext::from_environment(cli.keep, environment, TestContextType::VirtualMachine)?
             .init()?;
 
-    // Perform pre-flight cleanup to remove any lingering resources from interrupted tests
-    cleanup_lingering_resources(&test_context)?;
+    // Cleanup any artifacts from previous test runs that may have failed to clean up
+    // This ensures a clean slate before starting new tests
+    preflight_cleanup_previous_resources(&test_context)?;
 
     let test_start = Instant::now();
 
     let provision_result = run_provisioning_test(&test_context).await;
 
-    cleanup_infrastructure(&test_context);
+    // Always cleanup test infrastructure created during this test run
+    // This ensures proper resource cleanup regardless of test success or failure
+    cleanup_test_infrastructure(&test_context);
 
     let test_duration = test_start.elapsed();
 

src/bin/e2e_tests_full.rs

@@ -35,11 +35,20 @@
 //!
 //! ## Test Workflow
 //!
-//! 1. **Preflight cleanup** - Remove any lingering test resources
+//! 1. **Preflight cleanup** - Remove any artifacts from previous test runs that may have failed to clean up
 //! 2. **Infrastructure provisioning** - Create LXD VMs using `OpenTofu`
 //! 3. **Configuration** - Apply Ansible playbooks for software installation
 //! 4. **Validation** - Verify deployments are working correctly
-//! 5. **Cleanup** - Remove test resources
+//! 5. **Test infrastructure cleanup** - Remove test resources created during this run
+//!
+//! ## Two-Phase Cleanup Strategy
+//!
+//! The cleanup process happens in two distinct phases:
+//!
+//! - **Phase 1 - Preflight cleanup**: Removes artifacts from previous test runs that may have
+//!   failed to clean up properly (executed at the start in main function)
+//! - **Phase 2 - Test infrastructure cleanup**: Destroys resources created specifically during
+//!   the current test run (executed at the end in main function)
 //!
 //! The test suite supports different VM providers (LXD, Multipass) and includes
 //! comprehensive logging and error reporting.
@@ -57,8 +66,8 @@ use torrust_tracker_deploy::e2e::tasks::{
     run_configure_command::run_configure_command,
     run_test_command::run_test_command,
     virtual_machine::{
-        cleanup_infrastructure::cleanup_infrastructure,
-        preflight_cleanup::cleanup_lingering_resources,
+        cleanup_infrastructure::cleanup_test_infrastructure,
+        preflight_cleanup::preflight_cleanup_previous_resources,
         run_provision_command::run_provision_command,
     },
 };
@@ -135,8 +144,9 @@ pub async fn main() -> Result<()> {
         TestContext::from_environment(cli.keep, environment, TestContextType::VirtualMachine)?
             .init()?;
 
-    // Perform pre-flight cleanup to remove any lingering resources from interrupted tests
-    cleanup_lingering_resources(&test_context)?;
+    // Cleanup any artifacts from previous test runs that may have failed to clean up
+    // This ensures a clean slate before starting new tests
+    preflight_cleanup_previous_resources(&test_context)?;
 
     let test_start = Instant::now();
 
@@ -147,7 +157,9 @@ pub async fn main() -> Result<()> {
         Err(_) => Ok(()), // Skip validation if deployment failed
     };
 
-    cleanup_infrastructure(&test_context);
+    // Always cleanup test infrastructure created during this test run
+    // This ensures proper resource cleanup regardless of test success or failure
+    cleanup_test_infrastructure(&test_context);
 
     let test_duration = test_start.elapsed();
 

src/e2e/tasks/container/cleanup_infrastructure.rs

@@ -1,43 +1,48 @@
-//! Container cleanup task for E2E testing
+//! Container management task for E2E testing
 //!
-//! This module provides the E2E testing task for cleaning up Docker containers
-//! after test completion. It handles the transition from running to stopped
-//! container state and ensures proper resource cleanup.
+//! This module provides container management functionality for E2E testing,
+//! including stopping containers and handling automatic cleanup through testcontainers.
+//! It distinguishes between stopping containers (immediate) and cleanup (automatic).
 //!
 //! ## Key Operations
 //!
-//! - Stops running Docker containers
-//! - Cleans up container resources
-//! - Provides logging for cleanup operations
+//! - **Stop**: Immediately stops running Docker containers
+//! - **Cleanup**: Automatic deletion handled by testcontainers library
+//! - Provides logging for container operations
+//!
+//! ## Container vs VM Difference
+//!
+//! Unlike VMs that require explicit infrastructure destruction, Docker containers
+//! managed by testcontainers are automatically deleted when they go out of scope.
+//! This module provides both stop and cleanup functions for API symmetry.
 //!
 //! ## Integration
 //!
-//! This task is specifically designed for container-based E2E testing workflows
-//! and should be used as the final step in container test scenarios.
+//! This task is specifically designed for container-based E2E testing workflows.
 
 use tracing::info;
 
 use crate::e2e::containers::RunningProvisionedContainer;
 
-/// Cleanup a running Docker container
+/// Stop a running Docker container
 ///
-/// This function stops a running Docker container and performs cleanup operations.
-/// It transitions the container from running to stopped state and ensures proper
-/// resource cleanup.
+/// This function stops a running Docker container, transitioning it from running
+/// to stopped state. The actual container deletion is handled automatically by
+/// the testcontainers library when the container goes out of scope.
 ///
 /// # Arguments
 ///
-/// * `running_container` - The running container to be cleaned up
+/// * `running_container` - The running container to be stopped
 ///
 /// # Returns
 ///
 /// This function consumes the running container and returns nothing, ensuring
-/// the container cannot be used after cleanup.
+/// the container cannot be used after stopping.
 ///
 /// # Example
 ///
 /// ```rust,no_run
-/// use torrust_tracker_deploy::e2e::tasks::container::cleanup_infrastructure::cleanup_infrastructure;
+/// use torrust_tracker_deploy::e2e::tasks::container::cleanup_infrastructure::stop_test_infrastructure;
 /// use torrust_tracker_deploy::e2e::containers::StoppedProvisionedContainer;
 ///
 /// #[tokio::main]
@@ -47,17 +52,17 @@ use crate::e2e::containers::RunningProvisionedContainer;
 ///     
 ///     // ... perform tests ...
 ///     
-///     cleanup_infrastructure(running_container);
-///     println!("Container cleanup completed");
+///     stop_test_infrastructure(running_container);
+///     println!("Container stopped successfully");
 ///     Ok(())
 /// }
 /// ```
-pub fn cleanup_infrastructure(running_container: RunningProvisionedContainer) {
+pub fn stop_test_infrastructure(running_container: RunningProvisionedContainer) {
     let container_id = running_container.container_id().to_string();
 
     info!(
         container_id = %container_id,
-        "Starting container cleanup"
+        "Stopping test container"
     );
 
     // Transition container from running to stopped state
@@ -66,6 +71,23 @@ pub fn cleanup_infrastructure(running_container: RunningProvisionedContainer) {
     info!(
         container_id = %container_id,
         status = "success",
-        "Container cleanup completed successfully"
+        "Container stopped successfully - deletion handled automatically by testcontainers"
+    );
+}
+
+/// Cleanup test infrastructure for containers (no-op)
+///
+/// For containers managed by testcontainers, cleanup (deletion) is handled automatically
+/// when containers go out of scope. This function is provided for API symmetry with
+/// VM-based workflows that require explicit infrastructure destruction.
+///
+/// # Note
+///
+/// This function does nothing for containers. The actual cleanup is automatic.
+/// Use `stop_test_infrastructure()` to stop running containers.
+pub fn cleanup_test_infrastructure() {
+    info!(
+        operation = "container_cleanup",
+        "Container cleanup is automatic via testcontainers - no action needed"
     );
 }

src/e2e/tasks/container/preflight_cleanup.rs

@@ -14,7 +14,8 @@ use tracing::{info, warn};
 
 /// Performs pre-flight cleanup for Docker-based E2E tests
 ///
-/// This function is specifically designed for Docker-based E2E tests that use
+/// This function cleans up any artifacts remaining from previous test runs that may have
+/// failed to clean up properly. It's designed for Docker-based E2E tests that use
 /// testcontainers for container lifecycle management. It cleans up directories
 /// and any hanging Docker containers from previous interrupted test runs.
 ///
@@ -29,7 +30,9 @@ use tracing::{info, warn};
 /// # Errors
 ///
 /// Returns an error if directory cleanup fails and would prevent new test runs.
-pub fn cleanup_lingering_resources(env: &TestContext) -> Result<(), PreflightCleanupError> {
+pub fn preflight_cleanup_previous_resources(
+    env: &TestContext,
+) -> Result<(), PreflightCleanupError> {
     info!(
         operation = "preflight_cleanup_docker",
         "Starting pre-flight cleanup for Docker-based E2E tests"
@@ -49,6 +52,7 @@ pub fn cleanup_lingering_resources(env: &TestContext) -> Result<(), PreflightCle
         status = "success",
         "Pre-flight cleanup for Docker-based E2E tests completed successfully"
     );
+
     Ok(())
 }
 

src/e2e/tasks/preflight_cleanup.rs

@@ -11,7 +11,7 @@ use crate::infrastructure::adapters::opentofu::EmergencyDestroyError;
 use tracing::{info, warn};
 
 // Re-export functions from the new modular structure for backward compatibility
-pub use crate::e2e::tasks::container::preflight_cleanup::cleanup_lingering_resources;
+pub use crate::e2e::tasks::container::preflight_cleanup::preflight_cleanup_previous_resources;
 
 /// Errors that can occur during pre-flight cleanup operations
 #[derive(Debug)]

src/e2e/tasks/virtual_machine/cleanup_infrastructure.rs

@@ -23,11 +23,12 @@ use tracing::{info, warn};
 
 use crate::e2e::context::TestContext;
 
-/// Clean up test infrastructure
+/// Clean up test infrastructure created during VM-based E2E tests
 ///
-/// This function destroys the test infrastructure using `OpenTofu`.
-/// If `keep_env` is set in the environment configuration, the cleanup
-/// is skipped and the environment is preserved.
+/// This function destroys the test infrastructure using `OpenTofu` for resources
+/// that were created specifically during this test run. If `keep_env` is set in
+/// the environment configuration, the cleanup is skipped and the environment is
+/// preserved for debugging purposes.
 ///
 /// # Arguments
 ///
@@ -39,7 +40,7 @@ use crate::e2e::context::TestContext;
 /// - Otherwise, attempts to destroy infrastructure using `OpenTofu`
 /// - Logs success or failure appropriately
 /// - Does not return errors - failures are logged as warnings
-pub fn cleanup_infrastructure(test_context: &TestContext) {
+pub fn cleanup_test_infrastructure(test_context: &TestContext) {
     if test_context.keep_env {
         let instance_name = &test_context.environment.instance_name();
         info!(

src/e2e/tasks/virtual_machine/preflight_cleanup.rs

@@ -15,9 +15,9 @@ use tracing::{info, warn};
 
 /// Performs comprehensive pre-flight cleanup for VM-based E2E tests
 ///
-/// This function cleans up any lingering resources from previous test runs
-/// that may have been interrupted before cleanup, including directories,
-/// `OpenTofu` infrastructure, and LXD resources.
+/// This function cleans up any artifacts remaining from previous test runs that may have
+/// been interrupted before cleanup, including directories, `OpenTofu` infrastructure,
+/// and LXD resources. This ensures a clean slate for new test execution.
 ///
 /// # Arguments
 ///
@@ -30,7 +30,7 @@ use tracing::{info, warn};
 /// # Errors
 ///
 /// Returns an error if cleanup fails and would prevent new test runs.
-pub fn cleanup_lingering_resources(
+pub fn preflight_cleanup_previous_resources(
     test_context: &TestContext,
 ) -> Result<(), PreflightCleanupError> {
     info!(