tfgrid/projectmycelium
11
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
bfc24070d7a442a062e02821d74420aee2e59146
projectmycelium/tests/tests_archive/ux_suite
History

README.md

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)

    # 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

    # 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

  1. Selenium not running

    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

    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

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