feat: significantly improve test suite architecture and maintainabili…

[atzgg132]

Refactor and Modularize Test Suite: Utilities, Configuration, Metrics, and Documentation

Description

This PR significantly refactors the test suite for the Turbonomic Companion Operator to improve maintainability, modularity, and test reliability. The changes are backward-compatible and do not break existing tests.

---

Key Improvements

1. Modularization and Code Organization

• Test utilities and helpers have been moved to dedicated files (test_utils.go, metrics_test_utils.go, test_constants.go), reducing duplication and improving clarity.
• Test configuration is now managed in test_config.go, supporting environment-based overrides and validation.
• Shared constants (such as turboSA, timeouts, intervals) are now defined in a single location and referenced throughout the test suite.

2. Configuration Management

• The test suite now supports configuration via environment variables, allowing for flexible timeouts, retry intervals, namespace prefixes, and more.
• Configuration is validated at runtime to catch misconfigurations early.

3. Metrics Testing

• Introduced metrics_test_utils.go to provide reusable helpers for asserting and snapshotting Prometheus metrics.
• Metrics assertions are now more robust and can be reused across tests.

4. Test Suite Robustness

• Improved setup and teardown logic for test environments, including context cancellation and resource cleanup.
• Added utility functions for namespace and object management, reducing boilerplate in individual tests.
• Enhanced error handling and retry logic for flaky operations.

5. Documentation

• Added README_TEST_SUITE.md with detailed documentation on test architecture, configuration, usage patterns, and migration guidance for existing tests.

6. Technical Debt Resolution

• Removed all import cycles and duplicate constant definitions.
• Ensured all files build cleanly and pass go vet and linter checks.
• All tests pass locally (make test), and code coverage for the controller package is reported at 46.2%.

---

Files Added or Modified

• internal/controller/suite_test.go (refactored, now uses utilities and config)
• internal/controller/workload_resources_mutator.go (constant deduplication)
• internal/controller/test_utils.go (new, general test helpers)
• internal/controller/metrics_test_utils.go (new, metrics helpers)
• internal/controller/test_config.go (new, configuration management)
• internal/controller/test_constants.go (new, shared constants)
• internal/controller/README_TEST_SUITE.md (new, documentation)

---

Impact

• No breaking changes: All existing tests continue to work.
• Improved maintainability: New tests can be added with less boilerplate and more consistency.
• Better configuration: Test runs can be tuned for CI, local, or stress environments without code changes.
• Metrics coverage: Prometheus metrics can now be tested and asserted in a reusable way.

---

Migration

Existing tests can be gradually migrated to use the new utilities and configuration patterns. The documentation provides a migration guide and best practices.

---

This PR is ready for review. All tests pass, the codebase is more maintainable, and the test suite is now easier to extend and configure.