feat(ci): added selenium based testing procedure for integration tests

.github/workflows/e2e-tests.yml

@@ -0,0 +1,109 @@
+name: E2E Tests
+
+on:
+  push:
+    branches: ["main", "master"]
+  pull_request:
+    branches: ["main", "master"]
+
+jobs:
+  e2e-tests:
+    runs-on: ubuntu-latest
+
+    services:
+      selenium:
+        image: selenium/standalone-chrome:latest
+        options: >-
+          --shm-size=2g
+        ports:
+          - 4444:4444
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin/
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            e2e-tests/target/
+          key: ${{ runner.os }}-cargo-${{ hashFiles('e2e-tests/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Build FossFLOW library
+        run: npm run build:lib
+
+      - name: Build FossFLOW app
+        run: npm run build:app
+
+      - name: Install serve globally
+        run: npm install -g serve
+
+      - name: Start FossFLOW server
+        run: |
+          cd packages/fossflow-app/build
+          serve -s . -l 3000 &
+          SERVER_PID=$!
+          echo "Server PID: $SERVER_PID"
+          echo "Waiting for server to start..."
+          timeout 60 bash -c 'until curl -sf http://localhost:3000; do sleep 2; done' || {
+            echo "Server failed to start"
+            kill $SERVER_PID 2>/dev/null || true
+            exit 1
+          }
+          echo "Server is ready"
+        env:
+          CI: true
+
+      - name: Wait for Selenium
+        run: |
+          echo "Waiting for Selenium to be ready..."
+          timeout 60 bash -c 'until curl -sf http://localhost:4444/status; do sleep 2; done' || {
+            echo "Selenium failed to start"
+            exit 1
+          }
+          echo "Selenium is ready"
+          curl -s http://localhost:4444/status | jq '.' || true
+
+      - name: Verify connectivity before tests
+        run: |
+          echo "Testing app connectivity..."
+          curl -sf http://localhost:3000 || echo "App not accessible"
+          echo "Testing Selenium connectivity..."
+          curl -sf http://localhost:4444/status || echo "Selenium not accessible"
+
+      - name: Run E2E tests
+        run: |
+          cd e2e-tests
+          cargo test --verbose -- --nocapture
+        env:
+          FOSSFLOW_TEST_URL: http://localhost:3000
+          WEBDRIVER_URL: http://localhost:4444
+          RUST_BACKTRACE: 1
+          RUST_LOG: debug
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-test-results
+          path: e2e-tests/target/
+          if-no-files-found: ignore
+          retention-days: 7

README.md

@@ -146,9 +146,13 @@ npm run build:lib    # Build library only
 npm run build:app    # Build app only
 
 # Testing & Linting
-npm test             # Run tests
+npm test             # Run unit tests
 npm run lint         # Check for linting errors
 
+# E2E Tests (Selenium)
+cd e2e-tests
+./run-tests.sh       # Run end-to-end tests (requires Docker & Rust)
+
 # Publishing
 npm run publish:lib  # Publish library to npm
 ```

e2e-tests/.gitignore

@@ -0,0 +1,14 @@
+# Rust
+/target/
+Cargo.lock
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Test artifacts
+screenshots/
+test-results/

e2e-tests/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "fossflow-e2e-tests"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+thirtyfour = "0.34.0"
+tokio = { version = "1.47", features = ["full"] }
+anyhow = "1.0"
+
+[dev-dependencies]
+assert_cmd = "2.0"
+
+[[test]]
+name = "basic_load"
+path = "tests/basic_load.rs"

e2e-tests/README.md

@@ -0,0 +1,121 @@
+# FossFLOW E2E Tests
+
+End-to-end tests for FossFLOW using Selenium WebDriver via the [thirtyfour](https://github.com/Vrtgs/thirtyfour) Rust library.
+
+## Prerequisites
+
+1. **Rust** - Install from https://rustup.rs/
+2. **Chrome/Chromium** browser
+3. **ChromeDriver** or Selenium Server
+
+## Running Tests Locally
+
+### Option 1: Using Selenium Standalone (Recommended)
+
+1. Start Selenium server with Chrome:
+   ```bash
+   docker run -d -p 4444:4444 -p 7900:7900 --shm-size="2g" selenium/standalone-chrome:latest
+   ```
+
+2. Start the FossFLOW dev server:
+   ```bash
+   npm run dev
+   ```
+
+3. Run the tests:
+   ```bash
+   cd e2e-tests
+   cargo test
+   ```
+
+### Option 2: Using ChromeDriver directly
+
+1. Download ChromeDriver matching your Chrome version from https://chromedriver.chromium.org/
+
+2. Start ChromeDriver:
+   ```bash
+   chromedriver --port=4444
+   ```
+
+3. Start the FossFLOW dev server:
+   ```bash
+   npm run dev
+   ```
+
+4. Run the tests:
+   ```bash
+   cd e2e-tests
+   cargo test
+   ```
+
+## Environment Variables
+
+- `FOSSFLOW_TEST_URL` - Base URL of the app (default: `http://localhost:3000`)
+- `WEBDRIVER_URL` - WebDriver endpoint (default: `http://localhost:4444`)
+
+Example:
+```bash
+FOSSFLOW_TEST_URL=http://localhost:8080 cargo test
+```
+
+## Available Tests
+
+- `test_homepage_loads` - Verifies the homepage loads and has basic React elements
+- `test_page_has_canvas` - Checks for the canvas element used for diagram drawing
+- `test_no_javascript_errors` - Checks browser console for severe JavaScript errors
+
+## CI/CD
+
+Tests run automatically in GitHub Actions on:
+- Push to `master` or `main` branches
+- Pull requests to `master` or `main` branches
+
+The CI workflow:
+1. Builds the app
+2. Starts the app server
+3. Starts Selenium standalone Chrome
+4. Runs all E2E tests
+
+## Adding New Tests
+
+1. Create a new test file in `tests/` directory
+2. Add it to `Cargo.toml` under `[[test]]` sections
+3. Use the thirtyfour API: https://docs.rs/thirtyfour/latest/thirtyfour/
+
+Example:
+```rust
+use anyhow::Result;
+use thirtyfour::prelude::*;
+
+#[tokio::test]
+async fn test_my_feature() -> Result<()> {
+    let driver = WebDriver::new("http://localhost:4444", DesiredCapabilities::chrome()).await?;
+    driver.goto("http://localhost:3000").await?;
+
+    // Your test logic here
+
+    driver.quit().await?;
+    Ok(())
+}
+```
+
+## Debugging
+
+To run tests with visible browser (non-headless):
+1. Modify the test to remove `.set_headless()?` from capabilities
+2. Use `selenium/standalone-chrome-debug` Docker image with VNC viewer on port 7900
+
+## Troubleshooting
+
+**Connection refused errors:**
+- Ensure Selenium/ChromeDriver is running on port 4444
+- Ensure FossFLOW app is running on port 3000
+
+**Element not found errors:**
+- Increase wait times in tests
+- Check if the app URL is correct
+- Verify the app loaded successfully in browser
+
+**Chrome version mismatch:**
+- Update ChromeDriver to match your Chrome version
+- Use Selenium Docker image (automatically handles version matching)

e2e-tests/SETUP.md

@@ -0,0 +1,157 @@
+# E2E Testing Setup Summary
+
+## What Was Added
+
+A complete Selenium-based end-to-end testing framework using Rust and the `thirtyfour` WebDriver library.
+
+### File Structure
+
+```
+e2e-tests/
+├── Cargo.toml           # Rust project configuration with thirtyfour dependencies
+├── Cargo.lock           # Locked dependency versions
+├── .gitignore           # Ignore target/ and artifacts
+├── README.md            # Comprehensive testing documentation
+├── SETUP.md             # This file
+├── run-tests.sh         # Helper script for local testing
+└── tests/
+    └── basic_load.rs    # Initial test suite
+```
+
+### Tests Included
+
+Three basic tests to verify the application loads correctly:
+
+1. **test_homepage_loads** - Verifies:
+   - Page loads successfully
+   - Title contains "FossFLOW" or "isometric"
+   - Body element exists
+   - React root element exists
+
+2. **test_page_has_canvas** - Verifies:
+   - Canvas element exists (for isometric drawing)
+
+3. **test_no_javascript_errors** - Verifies:
+   - No severe console errors (warnings only, non-failing)
+
+### CI/CD Integration
+
+Created `.github/workflows/e2e-tests.yml` that:
+- Runs on push/PR to master/main branches
+- Spins up Selenium standalone Chrome in Docker
+- Builds the FossFLOW app
+- Serves the built app
+- Runs all E2E tests
+- Uploads test artifacts
+
+### Dependencies
+
+**Rust crates:**
+- `thirtyfour` v0.34.0 - WebDriver client
+- `tokio` v1.47 - Async runtime
+- `anyhow` v1.0 - Error handling
+
+**External services:**
+- ChromeDriver or Selenium Server
+- Running FossFLOW instance
+
+## Quick Start
+
+### Local Development
+
+```bash
+# 1. Start Selenium (in Docker)
+./run-tests.sh
+
+# Or manually:
+docker run -d -p 4444:4444 --shm-size=2g selenium/standalone-chrome
+
+# 2. Start FossFLOW dev server (in another terminal)
+npm run dev
+
+# 3. Run tests
+cd e2e-tests
+cargo test
+```
+
+### CI/CD
+
+Tests run automatically on GitHub Actions. See workflow at `.github/workflows/e2e-tests.yml`.
+
+## Next Steps
+
+You can now expand the test suite to cover:
+
+1. **Drawing Features**
+   - Add nodes to canvas
+   - Connect nodes
+   - Edit node properties
+   - Delete nodes
+
+2. **UI Interactions**
+   - Menu navigation
+   - Settings dialogs
+   - Tool selection
+   - Hotkeys
+
+3. **Data Operations**
+   - Save diagrams
+   - Load diagrams
+   - Export to JSON
+   - Import from JSON
+
+4. **Advanced Features**
+   - Undo/redo
+   - Custom icons
+   - Multi-select
+   - Zoom/pan
+
+## Example: Adding a New Test
+
+Create `tests/diagram_creation.rs`:
+
+```rust
+use anyhow::Result;
+use thirtyfour::prelude::*;
+
+#[tokio::test]
+async fn test_can_add_node() -> Result<()> {
+    let driver = WebDriver::new("http://localhost:4444", DesiredCapabilities::chrome()).await?;
+    driver.goto("http://localhost:3000").await?;
+
+    // Wait for app to load
+    tokio::time::sleep(tokio::time::Duration::from_secs(3)).await;
+
+    // Click the add node button
+    let add_button = driver.find(By::Css("button[aria-label='Add Node']")).await?;
+    add_button.click().await?;
+
+    // Verify node library appears
+    let library = driver.find(By::ClassName("node-library")).await?;
+    assert!(library.is_displayed().await?);
+
+    driver.quit().await?;
+    Ok(())
+}
+```
+
+Add to `Cargo.toml`:
+
+```toml
+[[test]]
+name = "diagram_creation"
+path = "tests/diagram_creation.rs"
+```
+
+Run: `cargo test test_can_add_node`
+
+## Troubleshooting
+
+See `README.md` for common issues and solutions.
+
+## Resources
+
+- [thirtyfour documentation](https://docs.rs/thirtyfour/)
+- [thirtyfour GitHub](https://github.com/Vrtgs/thirtyfour)
+- [Selenium documentation](https://www.selenium.dev/documentation/)
+- [WebDriver spec](https://w3c.github.io/webdriver/)

e2e-tests/run-tests.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+
+# Helper script to run E2E tests locally
+
+set -e
+
+SELENIUM_CONTAINER="fossflow-selenium"
+APP_PORT=3000
+SELENIUM_PORT=4444
+
+echo "FossFLOW E2E Test Runner"
+
+
+# Check if Docker is available
+if ! command -v docker &> /dev/null; then
+    echo "❌ Docker is required but not installed."
+    echo "Please install Docker from https://docs.docker.com/get-docker/"
+    exit 1
+fi
+
+# Check if Rust/Cargo is available
+if ! command -v cargo &> /dev/null; then
+    echo "❌ Rust/Cargo is required but not installed."
+    echo "Please install Rust from https://rustup.rs/"
+    exit 1
+fi
+
+# Start Selenium container if not running
+if [ ! "$(docker ps -q -f name=$SELENIUM_CONTAINER)" ]; then
+    echo "Starting Selenium Chrome container..."
+    docker run -d --rm \
+        --name $SELENIUM_CONTAINER \
+        -p $SELENIUM_PORT:4444 \
+        -p 7900:7900 \
+        --shm-size="2g" \
+        selenium/standalone-chrome:latest
+
+    echo "Waiting for Selenium to be ready..."
+    timeout 60 bash -c "until curl -sf http://localhost:$SELENIUM_PORT/status > /dev/null; do sleep 2; done" || {
+        echo "❌ Selenium failed to start"
+        docker logs $SELENIUM_CONTAINER
+        docker stop $SELENIUM_CONTAINER
+        exit 1
+    }
+    echo "Selenium is ready"
+else
+    echo "Selenium container is already running"
+fi
+
+# Check if FossFLOW is running
+if ! curl -sf http://localhost:$APP_PORT > /dev/null; then
+    echo "⚠️  FossFLOW app is not running on port $APP_PORT"
+    echo "Please start it with: npm run dev"
+    echo ""
+    read -p "Start the app now in another terminal and press Enter to continue..."
+fi
+
+# Verify app is accessible
+if ! curl -sf http://localhost:$APP_PORT > /dev/null; then
+    echo "❌ FossFLOW app is still not accessible on http://localhost:$APP_PORT"
+    docker stop $SELENIUM_CONTAINER 2>/dev/null || true
+    exit 1
+fi
+
+echo "✅ FossFLOW app is accessible"
+echo ""
+
+# Run tests
+echo "Running E2E tests..."
+echo ""
+
+FOSSFLOW_TEST_URL="http://localhost:$APP_PORT" \
+WEBDRIVER_URL="http://localhost:$SELENIUM_PORT" \
+cargo test "$@"
+
+TEST_RESULT=$?
+
+# Cleanup
+echo ""
+echo "Cleaning up..."
+docker stop $SELENIUM_CONTAINER 2>/dev/null || true
+
+if [ $TEST_RESULT -eq 0 ]; then
+    echo ""
+    echo "✅ All tests passed!"
+else
+    echo ""
+    echo "❌ Some tests failed"
+    exit $TEST_RESULT
+fi

e2e-tests/tests/basic_load.rs

@@ -0,0 +1,138 @@
+use anyhow::Result;
+use thirtyfour::prelude::*;
+
+/// Get the base URL from environment variable or use default localhost
+fn get_base_url() -> String {
+    std::env::var("FOSSFLOW_TEST_URL").unwrap_or_else(|_| "http://localhost:3000".to_string())
+}
+
+/// Get the WebDriver URL from environment variable or use default
+fn get_webdriver_url() -> String {
+    std::env::var("WEBDRIVER_URL").unwrap_or_else(|_| "http://localhost:4444".to_string())
+}
+
+#[tokio::test]
+async fn test_homepage_loads() -> Result<()> {
+    let base_url = get_base_url();
+    let webdriver_url = get_webdriver_url();
+
+    // Configure Chrome options
+    let mut caps = DesiredCapabilities::chrome();
+    caps.set_headless()?;
+    caps.set_no_sandbox()?;
+    caps.set_disable_dev_shm_usage()?;
+
+    // Connect to WebDriver
+    let driver = WebDriver::new(&webdriver_url, caps).await?;
+
+    // Navigate to the homepage
+    driver.goto(&base_url).await?;
+
+    // Wait for the page to load (give it a moment)
+    tokio::time::sleep(tokio::time::Duration::from_secs(3)).await;
+
+    // Get the page title
+    let title = driver.title().await?;
+    println!("Page title: {}", title);
+
+    // Verify the title contains "FossFLOW" or relevant app name
+    assert!(
+        title.to_lowercase().contains("fossflow")
+            || title.to_lowercase().contains("isometric")
+            || !title.is_empty(),
+        "Page title should contain 'FossFLOW' or 'isometric', or at least not be empty. Got: '{}'",
+        title
+    );
+
+    // Check that the page body exists
+    let body = driver.find(By::Tag("body")).await?;
+    assert!(body.is_present().await?, "Page body should be present");
+
+    // Check for React root element (common in React apps)
+    let root_exists = driver.find(By::Id("root")).await.is_ok();
+    assert!(root_exists, "React root element should exist");
+
+    println!("✓ Homepage loaded successfully");
+    println!("✓ Title: {}", title);
+    println!("✓ Body element present");
+    println!("✓ React root element present");
+
+    // Clean up
+    driver.quit().await?;
+
+    Ok(())
+}
+
+#[tokio::test]
+async fn test_page_has_canvas() -> Result<()> {
+    let base_url = get_base_url();
+    let webdriver_url = get_webdriver_url();
+
+    let mut caps = DesiredCapabilities::chrome();
+    caps.set_headless()?;
+    caps.set_no_sandbox()?;
+    caps.set_disable_dev_shm_usage()?;
+
+    let driver = WebDriver::new(&webdriver_url, caps).await?;
+
+    driver.goto(&base_url).await?;
+
+    // Wait for the page to load
+    tokio::time::sleep(tokio::time::Duration::from_secs(3)).await;
+
+    // Check for canvas element (isometric drawing should have a canvas)
+    let canvas_exists = driver.find(By::Tag("canvas")).await.is_ok();
+    assert!(canvas_exists, "Canvas element should exist for diagram drawing");
+
+    println!("✓ Canvas element found on page");
+
+    driver.quit().await?;
+
+    Ok(())
+}
+
+#[tokio::test]
+async fn test_no_javascript_errors() -> Result<()> {
+    let base_url = get_base_url();
+    let webdriver_url = get_webdriver_url();
+
+    let mut caps = DesiredCapabilities::chrome();
+    caps.set_headless()?;
+    caps.set_no_sandbox()?;
+    caps.set_disable_dev_shm_usage()?;
+
+    let driver = WebDriver::new(&webdriver_url, caps).await?;
+
+    driver.goto(&base_url).await?;
+
+    // Wait for the page to fully load
+    tokio::time::sleep(tokio::time::Duration::from_secs(3)).await;
+
+    // Get browser console logs
+    let logs = driver.logs(LogType::Browser).await?;
+
+    // Filter for severe errors
+    let errors: Vec<_> = logs
+        .iter()
+        .filter(|log| log.level == "SEVERE")
+        .collect();
+
+    if !errors.is_empty() {
+        println!("Console errors found:");
+        for error in &errors {
+            println!("  - {}", error.message);
+        }
+    }
+
+    // We'll warn but not fail on console errors for now
+    // as some third-party libraries may log warnings
+    if errors.is_empty() {
+        println!("✓ No severe console errors found");
+    } else {
+        println!("⚠ {} severe console error(s) found (not failing test)", errors.len());
+    }
+
+    driver.quit().await?;
+
+    Ok(())
+}