Skip to content

VERIFICATION_CHECKLIST.md

Latest commit

 

History

History
285 lines (225 loc) · 7 KB

VERIFICATION_CHECKLIST.md

File metadata and controls

285 lines (225 loc) · 7 KB

Window Manager Selection Verification Checklist

Implementation Verification

✅ Code Structure

  • EwmhAtoms structure defined with all required atoms
  • WmSelection structure implemented with proper lifecycle management
  • acquire() method for WM selection
  • check_existing_wm() for conflict detection
  • create_selection_window() for window creation
  • setup_selection_window() for property setup
  • setup_root_window() for root property setup
  • verify_selection() for selection verification
  • release() method for clean shutdown
  • Drop trait implementation for automatic cleanup

✅ Error Handling

  • Error::WmSelection variant added
  • Proper error messages for all failure scenarios
  • Error propagation throughout the call chain

✅ Integration

  • WmSelection::acquire() called in run()
  • WmSelection::acquire() called in run_with_backend()
  • Selection kept alive for program duration
  • Logging added for all major operations

✅ EWMH Compliance

  • _NET_SUPPORTING_WM_CHECK on selection window (points to self)
  • _NET_SUPPORTING_WM_CHECK on root window (points to selection window)
  • _NET_WM_NAME set to "FloatWM" on both windows
  • WM_NAME set for legacy compatibility
  • UTF-8 encoding using UTF8_STRING atom
  • Verification of successful selection

✅ Safety

  • Thread-safe ownership with AtomicBool
  • Null pointer checks before dereferencing
  • Proper memory management (XCB replies freed)
  • Window ID validation
  • Drop trait for resource cleanup

Testing Checklist

Compile-Time Tests

Run these tests to verify API structure:

cargo test wm_selection_api_tests

Expected: All tests pass (compile-time verification)

Build Verification

cargo build --release

Expected: Clean build with no errors or warnings

Runtime Verification (requires X11)

  1. No existing WM:

    # Stop any existing WM
# Run FloatWM
./target/release/floatwm

    Expected: FloatWM starts and acquires selection

  2. Check properties:

    xprop -root _NET_SUPPORTING_WM_CHECK _NET_WM_NAME

    Expected output:

    _NET_SUPPORTING_WM_CHECK(WINDOW): window id # 0x...
_NET_WM_NAME(UTF8_STRING) = "FloatWM"

  3. Check selection window:

    # Get the window ID from previous command
xprop -id 0x... _NET_SUPPORTING_WM_CHECK _NET_WM_NAME

    Expected output:

    _NET_SUPPORTING_WM_CHECK(WINDOW): window id # 0x... (same ID)
_NET_WM_NAME(UTF8_STRING) = "FloatWM"

  4. Existing WM conflict:

    # Start another WM first (e.g., i3, openbox)
# Then try to run FloatWM
./target/release/floatwm

    Expected: Error message about existing WM

Manual Verification Steps

Step 1: Clean Test Environment

# Ensure no WM is running
killall floatwm i3 openbox twm 2>/dev/null || true

Step 2: Run Test Script

./tests/wm_selection_test.sh

Expected output:

=== FloatWM Window Manager Selection Test ===
1. Checking for existing window manager...
   No window manager detected (good for testing)
2. Building FloatWM...
   Build successful
3. Running FloatWM...
   [FloatWM logs showing acquisition]
4. Checking if FloatWM acquired selection...
   SUCCESS: FloatWM is the active window manager!
   ✓ Test PASSED

Step 3: Property Verification

# Verify root properties
xprop -root | grep -E "NET_SUPPORTING_WM_CHECK|NET_WM_NAME"

# Verify selection window
WIN_ID=$(xprop -root _NET_SUPPORTING_WM_CHECK | grep -o "0x[0-9a-f]*" | head -1)
xprop -id $WIN_ID

Step 4: Conflict Detection

# Start a simple WM
openbox &

# Try to start FloatWM
./target/release/floatwm

Expected error:

Window manager selection error: Another window manager is already running (window: 0x...)

Code Quality Verification

Formatting

cargo fmt --check

Expected: No formatting suggestions

Linting

cargo clippy -- -D warnings

Expected: No warnings (or only allowed ones)

Documentation

cargo doc --no-deps --open

Expected: Documentation builds successfully

Log Output Verification

When running FloatWM, you should see these log messages:

[INFO] FloatWM starting with sensor support enabled
[INFO] Connected to X11 display: :0
[DEBUG] Using backend: Xcb
[DEBUG] Screen number: 0
[INFO] Acquiring window manager selection...
[DEBUG] Successfully interned EWMH atoms
[DEBUG] Created selection window: 12345678
[DEBUG] Set up selection window properties
[DEBUG] Set up root window properties
[DEBUG] Window manager selection verified successfully
[INFO] Successfully acquired window manager selection (window: 12345678)
[INFO] FloatWM is now the active window manager
[INFO] Selection window: 12345678
[INFO] Root window: 1234
[INFO] Initializing event loop...
[DEBUG] Registered default event handlers
[INFO] Starting main event loop

Exit Verification

Clean Exit

When FloatWM exits (e.g., SIGTERM), verify:

  1. Selection window is destroyed
  2. Root properties are removed
  3. No errors in logs
# After FloatWM exits
xprop -root _NET_SUPPORTING_WM_CHECK

Expected: Property no longer exists or is empty

Performance Verification

Memory Usage

# Check memory footprint
ps aux | grep floatwm

Expected: Minimal memory usage (should be < 10MB base)

Startup Time

time ./target/release/floatwm &

Expected: Fast startup (< 100ms to acquire selection)

Compliance Verification

EWMH Compliance Check

Use ewmh tool or xprop to verify:

# Check supported hints (future enhancement)
xprop -root _NET_SUPPORTED

# Check WM name
xprop -root _NET_WM_NAME

# Check client list (future enhancement)
xprop -root _NET_CLIENT_LIST

ICCCM Compliance

  • Selection window is override-redirect
  • Properties are correctly typed
  • Proper atom interning
  • Correct property formats (8, 16, or 32 bit)

Known Limitations

  1. Playwright Testing: Not applicable (X11 WM, not web-based)

    • Shell script testing used instead
    • Manual verification with xprop required

  2. Continuous Testing: Requires X11 server

    • Cannot test in headless CI without Xvfb
    • Consider adding Xvfb setup for CI

  3. Multi-Screen: Currently single-screen only

    • Future enhancement needed

  4. Selection Takeover: Doesn't handle external takeover yet

    • Future enhancement: Monitor SelectionClear events

Sign-Off Criteria

  • All code compiles without errors
  • No new clippy warnings introduced
  • Error handling covers all failure modes
  • EWMH protocol compliance verified
  • Conflict detection working
  • Clean shutdown verified
  • Documentation complete
  • Test scripts provided
  • Integration with main event loop complete

Notes

  • Implementation uses unsafe Rust for XCB FFI bindings
  • All unsafe blocks are documented and justified
  • Memory safety is maintained through careful pointer handling
  • Thread safety ensured through atomic operations