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

Selenium WebDriver (for browser automation)

# 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

Environment Setup

# Setup test directories
make -f Makefile.ux-tests setup-ux-tests

Running Tests

# 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

# 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

#[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

// 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

Selenium not running

docker run -d -p 4444:4444 selenium/standalone-chrome:latest

Test server port conflicts
- Tests use port 8081 by default
- Make sure port is available or configure different port

Screenshots not saving

mkdir -p tests/ux_suite/reports/screenshots

Browser automation fails
- Check WebDriver compatibility with browser version
- Verify headless mode settings for CI environments

Debug Mode

# 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:

Write tests first - Define expected UX behavior in tests
Use test personas - Leverage existing user roles and data
Include screenshots - Visual validation for complex flows
Validate APIs - Ensure backend/frontend consistency
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.