262 lines
8.2 KiB
Markdown
262 lines
8.2 KiB
Markdown
# Project Mycelium UX Test Suite
|
|
|
|
Complete end-to-end testing framework for validating the entire user experience as specified in the roadmap Section 9.
|
|
|
|
## 🎯 Overview
|
|
|
|
This UX test suite replaces manual testing with automated browser-based tests that validate all user flows, from anonymous browsing to complex provider workflows. The framework ensures that the complete UX specification is working correctly.
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
1. **Selenium WebDriver** (for browser automation)
|
|
```bash
|
|
# Install Chrome WebDriver
|
|
# Option 1: Docker (recommended)
|
|
docker run -d -p 4444:4444 selenium/standalone-chrome:latest
|
|
|
|
# Option 2: Local installation
|
|
# Download chromedriver and ensure it's in PATH
|
|
```
|
|
|
|
2. **Environment Setup**
|
|
```bash
|
|
# Setup test directories
|
|
make -f Makefile.ux-tests setup-ux-tests
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Quick smoke tests (3 core flows)
|
|
make -f Makefile.ux-tests test-ux-quick
|
|
|
|
# Complete core UX test suite
|
|
make -f Makefile.ux-tests test-ux
|
|
|
|
# Individual test categories
|
|
make -f Makefile.ux-tests test-ux-public # Public access tests
|
|
make -f Makefile.ux-tests test-ux-auth # Authentication tests
|
|
make -f Makefile.ux-tests test-ux-shopping # Shopping workflow tests
|
|
|
|
# Complete test suite (all tests)
|
|
make -f Makefile.ux-tests test-ux-full
|
|
```
|
|
|
|
## 📋 Test Categories
|
|
|
|
### ✅ Public Access Tests
|
|
Tests functionality available without authentication:
|
|
- Information pages (`/docs`, `/privacy`, `/terms`, `/about`, `/contact`)
|
|
- Anonymous marketplace browsing
|
|
- Anonymous cart functionality
|
|
- Search and filtering
|
|
- Product details pages
|
|
- Responsive design validation
|
|
|
|
### ✅ Authentication Tests
|
|
Tests user authentication functionality:
|
|
- User registration flow
|
|
- Login and logout functionality
|
|
- Cart migration during login
|
|
- Session management and persistence
|
|
- GitEa OAuth integration (conditional)
|
|
- Error handling and validation
|
|
|
|
### ✅ Shopping Workflow Tests
|
|
Tests complete shopping experience:
|
|
- Buy Now functionality
|
|
- Add to Cart workflow
|
|
- Cart management (edit quantities, remove items)
|
|
- Complete checkout process
|
|
- Order confirmation and tracking
|
|
- Insufficient funds handling
|
|
- Different product categories
|
|
|
|
## 🏗️ Framework Architecture
|
|
|
|
```
|
|
tests/ux_suite/
|
|
├── environment/ # Test environment management
|
|
│ ├── browser_manager.rs # Browser automation (Selenium WebDriver)
|
|
│ ├── test_server.rs # Isolated test server instance
|
|
│ ├── test_data_manager.rs # Test personas and data fixtures
|
|
│ └── api_client.rs # API validation alongside UX
|
|
├── flows/ # End-to-end user flow tests
|
|
│ ├── public_access.rs # Anonymous user tests
|
|
│ ├── authentication.rs # Auth flow tests
|
|
│ └── shopping.rs # Purchase workflow tests
|
|
├── utils/ # Test utilities and helpers
|
|
│ ├── ux_test_helper.rs # High-level UX operations
|
|
│ ├── assertions.rs # UX-specific assertions
|
|
│ └── test_fixtures.rs # Test data and setup
|
|
└── reports/ # Test reports and screenshots
|
|
└── screenshots/ # Visual validation screenshots
|
|
```
|
|
|
|
## 🧪 Test Data & Personas
|
|
|
|
The framework uses predefined test personas for different user roles:
|
|
|
|
- **Consumer** (`user1@example.com`) - Standard marketplace user
|
|
- **Farmer** (`farmer1@example.com`) - Resource provider with nodes
|
|
- **App Provider** (`appdev1@example.com`) - Application publisher
|
|
- **Service Provider** (`service1@example.com`) - Professional services
|
|
|
|
Each persona has:
|
|
- Profile data (name, country, timezone, currency preference)
|
|
- Wallet balance for testing purchases
|
|
- Role-specific permissions and workflows
|
|
|
|
## 🔧 Configuration
|
|
|
|
### Environment Variables
|
|
|
|
- `UX_TEST_MODE`: Test execution mode
|
|
- `dev` (default) - Visible browser, longer timeouts
|
|
- `ci` - Headless browser, optimized for CI/CD
|
|
- `full` - Complete test suite with all browsers
|
|
- `UX_TEST_TIMEOUT`: Timeout in seconds (default: 60)
|
|
- `SELENIUM_URL`: WebDriver URL (default: http://localhost:4444)
|
|
|
|
### Test Isolation
|
|
|
|
- **Dedicated test server** on port 8081 (separate from dev:8080, prod:3000)
|
|
- **Isolated test data** in `user_data_test/` directory
|
|
- **Clean state** between test runs
|
|
- **Separate browser profiles** with cleared cookies/storage
|
|
|
|
## 📊 Test Reporting
|
|
|
|
Tests generate comprehensive reports with:
|
|
- **Screenshots** for each major step and on failures
|
|
- **Performance metrics** (page load times)
|
|
- **API validation** results alongside UX validation
|
|
- **HTML reports** with visual timeline
|
|
|
|
Reports are saved to `tests/ux_suite/reports/`
|
|
|
|
## 🔄 Integration with Development Workflow
|
|
|
|
### Manual Testing Replacement
|
|
|
|
**Before**: `cargo run` → register as user1@example.com → manually test features
|
|
|
|
**After**: `make -f Makefile.ux-tests test-ux` → automated validation of all flows
|
|
|
|
### CI/CD Integration
|
|
|
|
```yaml
|
|
# GitHub Actions example
|
|
- name: Run UX Tests
|
|
run: make -f Makefile.ux-tests test-ux-ci
|
|
env:
|
|
UX_TEST_MODE: ci
|
|
SELENIUM_URL: http://localhost:4444
|
|
```
|
|
|
|
## 📖 Writing New Tests
|
|
|
|
### Basic Test Structure
|
|
|
|
```rust
|
|
#[tokio::test]
|
|
#[serial_test::serial]
|
|
async fn test_new_feature() -> Result<(), Box<dyn std::error::Error>> {
|
|
let environment = TestFixtures::setup_test_environment().await?;
|
|
let mut helper = UXTestHelper::new(&environment);
|
|
|
|
// Login as appropriate persona
|
|
let persona = helper.data_manager.get_persona(&UserRole::Consumer).unwrap();
|
|
helper.login_as(persona).await?;
|
|
|
|
// Test the feature
|
|
helper.browser.navigate_to("/new-feature").await?;
|
|
helper.assert_page_loaded("New Feature").await?;
|
|
|
|
// Take screenshot for visual validation
|
|
helper.take_screenshot("new_feature_page").await?;
|
|
|
|
// Validate with API if needed
|
|
let api_data = helper.api_client.get("/api/new-feature").await?;
|
|
assert!(api_data.status == 200);
|
|
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
### Adding Test Personas
|
|
|
|
```rust
|
|
// In test_data_manager.rs
|
|
personas.insert(UserRole::NewRole, TestPersona {
|
|
email: "newrole@example.com".to_string(),
|
|
password: "testpass123".to_string(),
|
|
name: "Test New Role".to_string(),
|
|
role: UserRole::NewRole,
|
|
profile: UserProfile { /* ... */ },
|
|
});
|
|
```
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Selenium not running**
|
|
```bash
|
|
docker run -d -p 4444:4444 selenium/standalone-chrome:latest
|
|
```
|
|
|
|
2. **Test server port conflicts**
|
|
- Tests use port 8081 by default
|
|
- Make sure port is available or configure different port
|
|
|
|
3. **Screenshots not saving**
|
|
```bash
|
|
mkdir -p tests/ux_suite/reports/screenshots
|
|
```
|
|
|
|
4. **Browser automation fails**
|
|
- Check WebDriver compatibility with browser version
|
|
- Verify headless mode settings for CI environments
|
|
|
|
### Debug Mode
|
|
|
|
```bash
|
|
# Run with verbose logging
|
|
RUST_LOG=debug make -f Makefile.ux-tests test-ux
|
|
|
|
# Run single test with visible browser
|
|
UX_TEST_MODE=dev cargo test --test ux_suite_main test_user_login_flow --features ux_testing
|
|
```
|
|
|
|
## 🔮 Future Enhancements
|
|
|
|
- [ ] **Dashboard Tests** (Phase 3) - User dashboard, wallet, provider workflows
|
|
- [ ] **Settings Tests** (Phase 3) - SSH keys, notifications, preferences
|
|
- [ ] **Modal Interactions** (Phase 3) - Complex UI flows based on html_template_tests/
|
|
- [ ] **Cross-browser Testing** (Phase 4) - Firefox, Safari compatibility
|
|
- [ ] **Mobile Testing** - Responsive design validation
|
|
- [ ] **Performance Testing** - Load time benchmarks
|
|
- [ ] **Visual Regression** - Screenshot comparison testing
|
|
|
|
## 📝 Contributing
|
|
|
|
When adding new UX features:
|
|
|
|
1. **Write tests first** - Define expected UX behavior in tests
|
|
2. **Use test personas** - Leverage existing user roles and data
|
|
3. **Include screenshots** - Visual validation for complex flows
|
|
4. **Validate APIs** - Ensure backend/frontend consistency
|
|
5. **Update documentation** - Keep test coverage current
|
|
|
|
## 🎯 Success Metrics
|
|
|
|
- ✅ **60+ UX flows** automated (from Section 9 specification)
|
|
- ✅ **4 user personas** covering all roles
|
|
- ✅ **Complete automation** replacing manual testing workflow
|
|
- ✅ **Isolated environment** separate from other tests
|
|
- ✅ **CI/CD ready** with automated reporting
|
|
|
|
The UX test suite ensures the Project Mycelium delivers a complete, tested user experience before deployment. |