Skip to content

Commit 6ba3c9e

Browse files
josecelanojosecelano
committed
docs: add decision record and refactor plan for TestEnvironment to TestContext rename
- Add decision record documenting naming choice for test context vs deployment environments - Create refactor plan with step-by-step approach for renaming TestEnvironment to TestContext - Reserve 'Environment' naming for future multi-environment deployment feature
1 parent 0d796a6 commit 6ba3c9e

File tree

3 files changed

+289
-7
lines changed

3 files changed

+289
-7
lines changed

‎docs/decisions/README.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,14 @@ This directory contains architectural decision records for the Torrust Tracker D
44

55
## Decision Index
66

7-
| Status | Date | Decision | Summary |
8-
| ----------- | ---------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
9-
| ✅ Accepted | 2025-09-10 | [LXD VMs over Containers](./lxd-vm-over-containers.md) | Use LXD virtual machines instead of containers for production alignment |
10-
| ✅ Accepted | 2025-09-09 | [Tera Minimal Templating Strategy](./tera-minimal-templating-strategy.md) | Use Tera with minimal variables and templates to avoid complexity and delimiter conflicts |
11-
| ✅ Accepted | - | [LXD over Multipass](./lxd-over-multipass.md) | Choose LXD containers over Multipass VMs for deployment testing |
12-
| ✅ Resolved | - | [Docker Testing Evolution](./docker-testing-evolution.md) | Evolution from Docker rejection to hybrid approach for split E2E testing |
13-
| ✅ Accepted | - | [Meson Removal](./meson-removal.md) | Remove Meson build system from the project |
7+
| Status | Date | Decision | Summary |
8+
| ----------- | ---------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
9+
| ✅ Accepted | 2025-09-29 | [Test Context vs Deployment Environment Naming](./test-context-vs-deployment-environment-naming.md) | Rename TestEnvironment to TestContext to avoid conflicts with multi-environment feature |
10+
| ✅ Accepted | 2025-09-10 | [LXD VMs over Containers](./lxd-vm-over-containers.md) | Use LXD virtual machines instead of containers for production alignment |
11+
| ✅ Accepted | 2025-09-09 | [Tera Minimal Templating Strategy](./tera-minimal-templating-strategy.md) | Use Tera with minimal variables and templates to avoid complexity and delimiter conflicts |
12+
| ✅ Accepted | - | [LXD over Multipass](./lxd-over-multipass.md) | Choose LXD containers over Multipass VMs for deployment testing |
13+
| ✅ Resolved | - | [Docker Testing Evolution](./docker-testing-evolution.md) | Evolution from Docker rejection to hybrid approach for split E2E testing |
14+
| ✅ Accepted | - | [Meson Removal](./meson-removal.md) | Remove Meson build system from the project |
1415

1516
## ADR Template
1617

‎docs/decisions/test-context-vs-deployment-environment-naming.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Decision: Test Context vs Deployment Environment Naming
2+
3+
## Status
4+
5+
Accepted
6+
7+
## Date
8+
9+
2025-09-29
10+
11+
## Context
12+
13+
The Torrust Tracker Deploy project has two distinct concepts that both could be called "environment":
14+
15+
1. **Testing Context (Current `TestEnvironment`)**: A test harness managing temporary resources, SSH keys, services, and cleanup for end-to-end testing.
16+
17+
2. **Multi-Environment Deployment (Planned Feature)**: Different deployment targets (dev, staging, production) with separate state, build artifacts, and persistent infrastructure.
18+
19+
This naming collision could mislead contributors and create ambiguity in the codebase.
20+
21+
## Decision
22+
23+
### Final Choice
24+
25+
- **`TestEnvironment` → `TestContext`**: Better represents a complete testing context with multiple resources
26+
- **Reserve `Environment` for multi-environment feature**: Aligns with industry standards (GitHub, AWS, Railway, Vercel)
27+
28+
### Alternatives Discarded
29+
30+
**For Testing Context:**
31+
32+
- `TestFixture`: Too narrow, implies single resource rather than complete context
33+
- `TestHarness`: Less familiar to some developers
34+
- `TestSetup`: Generic, less descriptive
35+
- `TestSandbox`: Could suggest security focus rather than resource management
36+
37+
**For Multi-Environment Feature:**
38+
39+
- `Context`: Used by Docker/Kubernetes but less intuitive for deployment targets
40+
- `Workspace`: Used by Terraform differently, could conflict with IDE workspaces
41+
- `Target`: Less descriptive of full environment concept
42+
- `Stage`: Implies sequence, less flexible
43+
- `Stack`: Implies specific architecture
44+
45+
## Why
46+
47+
- **TestContext** accurately describes managing a complete testing context with multiple resources and services
48+
- **Environment** is the industry standard for deployment targets, making it immediately intuitive for users
49+
- Clear conceptual separation: `TestContext` for temporary test infrastructure, `Environment` for persistent deployment targets
50+
| `TestContext` ✅ | Conveys complete context management | Slightly longer | Testing frameworks, .NET |
51+
| `TestSandbox` | Implies isolation | Could suggest security focus | Containerization |
52+
| `TestWorkspace` | Suggests temporary work area | Could conflict with IDE workspaces | IDE terminology |
53+
54+
### For Multi-Environment Feature (New Concept)
55+
56+
| Name | Pros | Cons | Industry Usage |
57+
| ---------------- | ---------------------------- | ------------------------------------- | ---------------------------- |
58+
| `Environment` ✅ | Industry standard, intuitive | Could conflict with test environment | GitHub, AWS, Railway, Vercel |
59+
| `Context` | Used by Docker/Kubernetes | Less intuitive for deployment targets | Docker, Kubernetes |
60+
| `Workspace` | Clear isolation concept | Used by Terraform differently | Terraform |
61+
| `Target` | Clear deployment meaning | Less descriptive of full environment | Build systems |
62+
| `Stage` | Common in CI/CD | Implies sequence, less flexible | AWS, CI/CD pipelines |
63+
| `Stack` | Complete infrastructure set | Implies specific architecture | Pulumi, CloudFormation |
64+
65+
## Decision
66+
67+
We will adopt the following naming strategy:
68+
69+
### 1. Rename `TestEnvironment` → `TestContext`
70+
71+
**Rationale:**
72+
73+
- `TestContext` better represents what the struct actually does: managing a complete testing context with multiple resources, configuration, and services
74+
- It's more accurate than "TestFixture" which implies a single resource
75+
- Common in testing frameworks and clearly distinguishes from deployment environments
76+
- Conveys the idea of a complete context that encompasses multiple concerns
77+
78+
### 2. Use `Environment` for Multi-Environment Feature
79+
80+
**Rationale:**
81+
82+
- `Environment` is the industry standard term used by GitHub Actions, AWS, Railway, Vercel, and most DevOps tools
83+
- Users will immediately understand commands like `deploy --environment dev` or `deploy --environment staging`
84+
- Aligns with common DevOps terminology and user expectations
85+
- Most intuitive for the target use case
86+
87+
### 3. Related Renames
88+
89+
- `TestEnvironmentError` → `TestContextError`
90+
- `TestEnvironmentType` → `TestContextType`
91+
- Update field names: `environment_type` → `context_type`
92+
- Update documentation and comments throughout
93+
94+
## Consequences
95+
96+
### Positive
97+
98+
- **Clear Conceptual Separation**: `TestContext` for temporary test infrastructure, `Environment` for persistent deployment targets
99+
- **Industry Alignment**: Users familiar with other DevOps tools will immediately understand the Environment concept
100+
- **Accurate Naming**: `TestContext` better describes the actual functionality
101+
- **Future-Proof**: Leaves `Environment` available for the more important multi-environment feature
102+
103+
### Negative
104+
105+
- **Refactoring Required**: Need to update existing code, tests, and documentation
106+
- **Temporary Disruption**: Developers working on branches will need to update their code
107+
- **Documentation Updates**: All references in docs and comments need updating
108+
109+
### Neutral
110+
111+
- **Learning Curve**: Minimal - `TestContext` is intuitive for developers familiar with testing frameworks
112+
113+
## Implementation Plan
114+
115+
1. Create this decision record
116+
2. Update `TestEnvironment` → `TestContext` in `src/e2e/environment.rs`
117+
3. Search for and update all references in other files
118+
4. Update documentation and module-level comments
119+
5. Update error types and messages
120+
6. Run tests to ensure no breakage
121+
122+
## Examples After Implementation
123+
124+
```rust
125+
// Test context usage
126+
let test_context = TestContext::initialized(
127+
false,
128+
"templates",
129+
&ssh_user,
130+
instance_name,
131+
ssh_private_key_path,
132+
ssh_public_key_path,
133+
TestContextType::Container,
134+
)?;
135+
136+
// Future environment usage (planned)
137+
deploy --environment dev
138+
deploy --environment staging
139+
deploy --environment production
140+
141+
struct Environment {
142+
name: String,
143+
build_dir: PathBuf,
144+
data_dir: PathBuf,
145+
config: EnvironmentConfig,
146+
}
147+
```
148+
149+
## Related Decisions
150+
151+
This decision enables future work on:
152+
153+
- Multi-environment deployment feature
154+
- Environment-specific configuration management
155+
- Independent state management per environment
156+
157+
## References
158+
159+
- Industry examples: GitHub Environments, AWS Environments, Docker Contexts, Terraform Workspaces
160+
- Testing terminology: xUnit TestFixture, .NET TestContext
161+
- Current codebase: `src/e2e/environment.rs`

‎docs/refactors/testenvironment-to-testcontext.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Refactor Plan: TestEnvironment to TestContext
2+
3+
## Overview
4+
5+
Rename `TestEnvironment` to `TestContext` throughout the codebase to avoid naming conflicts with the planned multi-environment deployment feature. This refactor will also rename the file `src/e2e/environment.rs` to `src/e2e/context.rs`.
6+
7+
## Scope
8+
9+
### Files to Modify
10+
11+
1. **Primary Module**
12+
13+
- `src/e2e/environment.rs` → `src/e2e/context.rs`
14+
15+
2. **Files Using TestEnvironment** (found via compilation errors)
16+
17+
- `src/e2e/tasks/container/preflight_cleanup.rs`
18+
- `src/e2e/tasks/container/run_provision_simulation.rs`
19+
- `src/e2e/tasks/preflight_cleanup.rs`
20+
- `src/e2e/tasks/run_configure_command.rs`
21+
- `src/e2e/tasks/run_test_command.rs`
22+
- `src/e2e/tasks/virtual_machine/cleanup_infrastructure.rs`
23+
- `src/e2e/tasks/virtual_machine/preflight_cleanup.rs`
24+
- `src/e2e/tasks/virtual_machine/run_provision_command.rs`
25+
26+
3. **Module Exports**
27+
- `src/e2e/mod.rs` - Update module declaration and re-exports
28+
29+
### Renames Required
30+
31+
| Current Name | New Name |
32+
| ------------------------ | -------------------- |
33+
| `TestEnvironment` | `TestContext` |
34+
| `TestEnvironmentError` | `TestContextError` |
35+
| `TestEnvironmentType` | `TestContextType` |
36+
| `environment_type` field | `context_type` field |
37+
| `src/e2e/environment.rs` | `src/e2e/context.rs` |
38+
39+
## Step-by-Step Plan
40+
41+
### Phase 1: Rename Main Types in environment.rs
42+
43+
1. **Rename struct**: `TestEnvironment` → `TestContext`
44+
2. **Rename error enum**: `TestEnvironmentError` → `TestContextError`
45+
3. **Rename type enum**: `TestEnvironmentType` → `TestContextType`
46+
4. **Update field names**: `environment_type` → `context_type`
47+
5. **Fix impl blocks**: Update all `impl TestEnvironment` to `impl TestContext`
48+
6. **Update documentation**: Change all references in doc comments
49+
7. **Update error messages**: Change "environment" to "context" in error strings where appropriate
50+
51+
### Phase 2: Update Import Statements
52+
53+
For each file in the "Files Using TestEnvironment" list:
54+
55+
1. Change `use crate::e2e::environment::TestEnvironment;` to `use crate::e2e::context::TestContext;`
56+
2. Update any usage of `TestEnvironment` to `TestContext`
57+
3. Update any usage of `TestEnvironmentError` to `TestContextError`
58+
4. Update any usage of `TestEnvironmentType` to `TestContextType`
59+
60+
### Phase 3: Rename File and Update Module System
61+
62+
1. **Rename file**: `src/e2e/environment.rs` → `src/e2e/context.rs`
63+
2. **Update module declaration**: In `src/e2e/mod.rs`:
64+
- Change `pub mod environment;` → `pub mod context;`
65+
- Update any re-exports from `environment` to `context`
66+
67+
### Phase 4: Update Import Paths
68+
69+
Update all import paths from:
70+
71+
- `crate::e2e::environment::*` → `crate::e2e::context::*`
72+
73+
### Phase 5: Verification
74+
75+
1. **Compile**: Ensure `cargo build` succeeds
76+
2. **Test**: Run `cargo test` to ensure no test breakage
77+
3. **Lint**: Run `cargo run --bin linter all` to ensure code quality
78+
4. **E2E Tests**: Run `cargo run --bin e2e-tests-full` to verify functionality
79+
80+
## Expected Changes Summary
81+
82+
- **8 files** with import statement updates
83+
- **1 file** renamed (`environment.rs` → `context.rs`)
84+
- **1 module file** updated (`src/e2e/mod.rs`)
85+
- **3 type names** changed throughout codebase
86+
- **Documentation and comments** updated for clarity
87+
88+
## Risk Assessment
89+
90+
**Low Risk**: This is a pure rename refactor with no logic changes.
91+
92+
**Potential Issues**:
93+
94+
- Import path mismatches if any imports are missed
95+
- Test breakage if test code uses the old names
96+
- Documentation references that need updating
97+
98+
**Mitigation**:
99+
100+
- Use compiler errors to guide the refactor
101+
- Run full test suite after completion
102+
- Use search tools to find any remaining references
103+
104+
## Testing Strategy
105+
106+
1. **Compilation Check**: Fix all compilation errors step by step
107+
2. **Unit Tests**: Ensure all existing tests pass with new names
108+
3. **E2E Tests**: Verify end-to-end functionality works
109+
4. **Integration Tests**: Check that all components work together
110+
111+
## Post-Refactor Validation
112+
113+
After completion, verify:
114+
115+
- [ ] All files compile without errors
116+
- [ ] All tests pass
117+
- [ ] No references to old names remain in codebase
118+
- [ ] Documentation is consistent with new naming
119+
- [ ] E2E tests function correctly with renamed types
120+

0 commit comments

Comments
 (0)