refactor: standardize TestEnvironment API with unified 'initialized' method

- Replace multiple constructor methods (new, with_ssh_user_and_init) with single 'initialized' method
- All e2e test binaries now use TestEnvironment::initialized with explicit SSH user 'torrust'
- Update e2e_provision_tests.rs and e2e_tests_full.rs to use consistent API
- Fix outdated documentation comments to reflect current implementation
- Update doctest examples to use new API
- Add TestEnvironmentType parameter to all environment creation calls

Benefits:
- Consistent API across all e2e tests
- Explicit SSH user configuration for all tests
- Clearer error messages with specific failure conditions
- Single entry point for test environment creation

Author: josecelano

src/bin/e2e_config_tests.rs

@@ -114,7 +114,7 @@ pub async fn main() -> Result<()> {
     let instance_name =
         InstanceName::new("torrust-tracker-vm".to_string()).expect("Valid hardcoded instance name");
 
-    let env = TestEnvironment::with_ssh_user_and_init(
+    let env = TestEnvironment::initialized(
         false,
         cli.templates_dir,
         "torrust",

src/bin/e2e_provision_tests.rs

@@ -23,7 +23,7 @@ use tracing::{error, info};
 
 // Import E2E testing infrastructure
 use torrust_tracker_deploy::config::InstanceName;
-use torrust_tracker_deploy::e2e::environment::TestEnvironment;
+use torrust_tracker_deploy::e2e::environment::{TestEnvironment, TestEnvironmentType};
 use torrust_tracker_deploy::e2e::tasks::{
     preflight_cleanup::cleanup_lingering_resources,
     virtual_machine::{
@@ -98,7 +98,13 @@ pub async fn main() -> Result<()> {
     let instance_name =
         InstanceName::new("torrust-tracker-vm".to_string()).expect("Valid hardcoded instance name");
 
-    let env = TestEnvironment::new(cli.keep, cli.templates_dir, instance_name)?;
+    let env = TestEnvironment::initialized(
+        cli.keep,
+        cli.templates_dir,
+        "torrust",
+        instance_name,
+        TestEnvironmentType::VirtualMachine,
+    )?;
 
     // Perform pre-flight cleanup to remove any lingering resources from interrupted tests
     cleanup_lingering_resources(&env)?;

src/bin/e2e_tests_full.rs

@@ -28,7 +28,7 @@ use tracing::{error, info};
 
 // Import E2E testing infrastructure
 use torrust_tracker_deploy::config::InstanceName;
-use torrust_tracker_deploy::e2e::environment::TestEnvironment;
+use torrust_tracker_deploy::e2e::environment::{TestEnvironment, TestEnvironmentType};
 use torrust_tracker_deploy::e2e::tasks::{
     preflight_cleanup::cleanup_lingering_resources,
     run_configure_command::run_configure_command,
@@ -97,7 +97,13 @@ pub async fn main() -> Result<()> {
     let instance_name =
         InstanceName::new("torrust-tracker-vm".to_string()).expect("Valid hardcoded instance name");
 
-    let env = TestEnvironment::new(cli.keep, cli.templates_dir, instance_name)?;
+    let env = TestEnvironment::initialized(
+        cli.keep,
+        cli.templates_dir,
+        "torrust",
+        instance_name,
+        TestEnvironmentType::VirtualMachine,
+    )?;
 
     // Perform pre-flight cleanup to remove any lingering resources from interrupted tests
     cleanup_lingering_resources(&env)?;

src/e2e/environment.rs

@@ -55,9 +55,6 @@ pub enum TestEnvironmentError {
     EnvironmentPreparationError { source: anyhow::Error },
 }
 
-/// Default SSH username for test environments
-const DEFAULT_SSH_USER: &str = "torrust";
-
 /// SSH private key filename for testing
 const SSH_PRIVATE_KEY_FILENAME: &str = "testing_rsa";
 
@@ -88,83 +85,10 @@ pub struct TestEnvironment {
 }
 
 impl TestEnvironment {
-    /// Creates a new test environment with configuration and services
+    /// Creates and initializes a new test environment with custom SSH user
     ///
-    /// This method only performs basic construction without side effects.
-    /// Call `init()` to perform environment initialization.
-    ///
-    /// # Arguments
-    ///
-    /// * `keep_env` - Whether to keep the environment after tests complete
-    /// * `templates_dir` - Path to the templates directory
-    /// * `instance_name` - Name for the instance to be deployed
-    ///
-    /// # Errors
-    ///
-    /// Returns an error if:
-    /// - Current directory cannot be determined
-    /// - Temporary directory creation fails
-    /// - SSH key setup fails
-    /// - Templates directory is invalid
-    ///
-    /// # Panics
-    ///
-    /// Panics if the provided `instance_name` is invalid (contains invalid characters
-    /// or is empty). This should not happen with well-formed instance names.
-    pub fn new(
-        keep_env: bool,
-        templates_dir: impl Into<std::path::PathBuf>,
-        instance_name: InstanceName,
-    ) -> Result<Self, TestEnvironmentError> {
-        Self::with_ssh_user(
-            keep_env,
-            templates_dir,
-            DEFAULT_SSH_USER,
-            instance_name,
-            TestEnvironmentType::VirtualMachine,
-        )
-    }
-
-    /// Creates and initializes a new test environment with custom SSH user in one step
-    ///
-    /// This is a convenience method that combines `with_ssh_user()` and `init()`.
-    /// Use this when you want the full setup in one call.
-    ///
-    /// # Arguments
-    ///
-    /// * `keep_env` - Whether to keep the environment after tests complete
-    /// * `templates_dir` - Path to the templates directory
-    /// * `ssh_user` - SSH username to use for connections
-    /// * `instance_name` - Name for the instance to be deployed
-    /// * `environment_type` - The type of test environment (Container or `VirtualMachine`)
-    ///
-    /// # Errors
-    ///
-    /// Returns an error if:
-    /// - Construction fails (see `with_ssh_user()` for details)
-    /// - Initialization fails (see `init()` for details)
-    pub fn with_ssh_user_and_init(
-        keep_env: bool,
-        templates_dir: impl Into<std::path::PathBuf>,
-        ssh_user: &str,
-        instance_name: InstanceName,
-        environment_type: TestEnvironmentType,
-    ) -> Result<Self, TestEnvironmentError> {
-        let env = Self::with_ssh_user(
-            keep_env,
-            templates_dir,
-            ssh_user,
-            instance_name,
-            environment_type,
-        )?;
-        env.init()?;
-        Ok(env)
-    }
-
-    /// Creates a new test environment with a custom SSH user
-    ///
-    /// This method only performs basic construction without side effects.
-    /// Call `init()` to perform environment initialization.
+    /// This method performs the complete setup including validation, SSH key setup,
+    /// template preparation, and environment initialization in a single call.
     ///
     /// # Arguments
     ///
@@ -177,44 +101,53 @@ impl TestEnvironment {
     /// # Errors
     ///
     /// Returns an error if:
+    /// - Input validation fails (empty or invalid templates directory)
     /// - Current directory cannot be determined
     /// - Temporary directory creation fails
     /// - SSH key setup fails
-    /// - Templates directory is invalid
-    fn with_ssh_user(
+    /// - Template preparation fails
+    pub fn initialized(
         keep_env: bool,
         templates_dir: impl Into<std::path::PathBuf>,
         ssh_user: &str,
         instance_name: InstanceName,
         environment_type: TestEnvironmentType,
     ) -> Result<Self, TestEnvironmentError> {
         let templates_dir = templates_dir.into();
+
         Self::validate_inputs(&templates_dir)?;
 
         let project_root = Self::get_project_root()?;
         let temp_dir = Self::create_temp_directory()?;
+
         let ssh_credentials = Self::setup_ssh_credentials(&project_root, &temp_dir, ssh_user)?;
+
         let config = Self::create_config(
             keep_env,
             ssh_credentials,
             instance_name,
             &templates_dir,
             &project_root,
         );
+
         let services = Services::new(&config);
 
-        Ok(Self {
+        let env = Self {
             config,
             services,
             temp_dir: Some(temp_dir),
             environment_type,
-        })
+        };
+
+        env.init()?;
+
+        Ok(env)
     }
 
     /// Initializes the test environment by preparing templates and logging setup
     ///
-    /// This method performs the actual environment setup with side effects.
-    /// Must be called after construction to make the environment ready for use.
+    /// This method performs the final environment setup with side effects.
+    /// It is called internally by `initialized()` as part of the initialization process.
     ///
     /// # Errors
     ///

src/e2e/tasks/container/run_provision_simulation.rs

@@ -62,13 +62,19 @@ use crate::infrastructure::ansible::AnsibleTemplateRenderer;
 ///
 /// ```rust,no_run
 /// use torrust_tracker_deploy::e2e::tasks::container::run_provision_simulation::run_provision_simulation;
-/// use torrust_tracker_deploy::e2e::environment::TestEnvironment;
+/// use torrust_tracker_deploy::e2e::environment::{TestEnvironment, TestEnvironmentType};
 /// use torrust_tracker_deploy::config::InstanceName;
 ///
 /// #[tokio::main]
 /// async fn main() -> anyhow::Result<()> {
 ///     let instance_name = InstanceName::new("test-container".to_string())?;
-///     let test_env = TestEnvironment::new(false, "./templates".to_string(), instance_name)?;
+///     let test_env = TestEnvironment::initialized(
+///         false,
+///         "./templates".to_string(),
+///         "torrust",
+///         instance_name,
+///         TestEnvironmentType::Container
+///     )?;
 ///     
 ///     let running_container = run_provision_simulation(&test_env).await?;
 ///     println!("Container provision simulation completed: {}", running_container.ssh_socket_addr());