Implement CLI Command: `torrust-tracker-deployer test`

[josecelano]

Parent Epic: #2 - Scaffolding for main app

Related:

• Application Layer Test Command Handler
• Provision CLI Command Implementation
• ADR: Test Command as Smoke Test
• Full Specification: docs/issues/implement-test-cli-command.md

Overview

Implement the presentation layer (CLI interface) for the test command, enabling users to verify deployment infrastructure through the command-line interface. The application layer TestCommandHandler is already implemented and performs validation checks for cloud-init completion, Docker installation, and Docker Compose installation.

This task focuses exclusively on creating the user-facing CLI subcommand that calls the existing business logic, following the same architectural pattern used in the configure command controller.

Goals

• Create presentation layer controller for test CLI subcommand
• Implement error handling with actionable help messages
• Integrate with existing TestCommandHandler business logic
• Follow DDD patterns consistent with other CLI commands (provision, configure, destroy)
• Provide clear user feedback during validation workflow
• Enable end-to-end deployment workflow verification via CLI

🏗️ Architecture Requirements

DDD Layer: Presentation
Module Path: src/presentation/controllers/test/
Pattern: CLI Subcommand Controller (orchestrates Application layer command handler)

Module Structure

src/presentation/controllers/test/
├── mod.rs          # Module documentation and re-exports
├── handler.rs      # Main controller implementation
├── errors.rs       # Presentation-layer error types
└── tests/          # Unit tests for controller logic
    └── mod.rs

Key Requirements

• Follow presentation layer conventions from src/presentation/controllers/configure/
• No business logic in presentation layer - delegate all validation to TestCommandHandler
• Error types must implement .help() methods with actionable troubleshooting guidance
• Use ProgressReporter for user feedback during multi-step validation
• Support both ExecutionContext pattern and direct dependency injection

Implementation Plan

Phase 1: Module Structure and Error Types (1-2 hours)

• Create src/presentation/controllers/test/ directory
• Create mod.rs with module documentation
• Implement errors.rs with all error variants and .help() methods
• Create tests/mod.rs skeleton

Phase 2: Controller Implementation (2-3 hours)

• Implement TestCommandController struct in handler.rs
• Implement workflow methods: validate env name, create handler, test infrastructure, complete
• Setup ProgressReporter for 4-step workflow
• Implement both API levels (ExecutionContext + direct injection)

Phase 3: CLI Integration (1 hour)

• Add Test variant to Commands enum in main.rs
• Implement command dispatch for test subcommand
• Update src/presentation/controllers/mod.rs to export test controller

Phase 4: Testing (2-3 hours)

• Write unit tests for error .help() messages
• Write integration tests for success and error scenarios
• Test with real provisioned environment

Phase 5: Documentation and Manual Testing (2-3 hours)

• Add rustdoc documentation for all public APIs
• Update docs/console-commands.md with test command usage
• Complete manual E2E workflow test (see full spec)

Phase 6: Quality Assurance (30 minutes)

• Run pre-commit checks: ./scripts/pre-commit.sh
• Fix any linting issues
• Ensure all tests pass

Acceptance Criteria

Note for Contributors: These criteria define what the PR reviewer will check. Use this as your pre-review checklist before submitting the PR.

Quality Checks:

• Pre-commit checks pass: ./scripts/pre-commit.sh

Task-Specific Criteria:

• CLI command torrust-tracker-deployer test <environment-name> executes successfully
• Command validates environment name and provides clear error for invalid names
• Progress reporter shows 4 workflow steps: validate env, create handler, test infrastructure, complete
• All validation checks (cloud-init, Docker, Docker Compose) are delegated to TestCommandHandler
• All error types implement .help() with specific troubleshooting steps
• Module structure matches configure controller pattern
• Both API levels implemented (ExecutionContext + direct injection)
• Documentation updated in docs/console-commands.md
• Manual E2E test completes full deployment workflow using only CLI commands

User Experience Examples

Success case:

$ torrust-tracker-deployer test my-env
[1/3] Validating cloud-init completion... ✓
[2/3] Validating Docker installation... ✓
[3/3] Validating Docker Compose installation... ✓
✓ Infrastructure validation completed successfully

Error case - environment not provisioned:

$ torrust-tracker-deployer test my-env
Error: Environment 'my-env' does not have instance IP set

Environment 'my-env' must be provisioned before testing.

Provision infrastructure:
  torrust-tracker-deployer provision my-env

Notes

• The controller only orchestrates - all validation logic is in TestCommandHandler
• Follow the exact same pattern as configure controller for consistency
• See the full specification for complete details including:
  • Complete code examples
  • Error type implementations
  • Manual testing workflow (10 steps)
  • Design rationale and future enhancements

Estimated Total Time: 8-12 hours