dev-test-linux

What this skill does

<EXTREMELY-IMPORTANT>
## Gate Reminder

Before taking screenshots or running E2E tests, you MUST complete all 6 gates from dev-tdd:

```
GATE 1: BUILD
GATE 2: LAUNCH (with file-based logging)
GATE 3: WAIT
GATE 4: CHECK PROCESS
GATE 5: READ LOGS ← MANDATORY, CANNOT SKIP
GATE 6: VERIFY LOGS
THEN: E2E tests/screenshots
```

**You loaded dev-tdd earlier. Follow the gates now.**
</EXTREMELY-IMPORTANT>

## Contents

- [Tool Availability Gate](#tool-availability-gate)
- [When to Use Linux Automation](#when-to-use-linux-automation)
- [Detect Display Server](#detect-display-server)
- [Wayland: ydotool](#wayland-ydotool)
- [X11: xdotool](#x11-xdotool)
- [Screenshots](#screenshots)
- [D-Bus Control](#d-bus-control)
- [Accessibility (AT-SPI)](#accessibility-at-spi)
- [Complete E2E Examples](#complete-e2e-examples)

# Linux Desktop Automation

<EXTREMELY-IMPORTANT>
## Tool Availability Gate

Verify automation tools are installed before proceeding.

```bash
# Detect display server (check for Wayland vs X11)
echo $XDG_SESSION_TYPE  # "wayland" or "x11"

# Wayland tools check (verify ydotool, wtype, grim, slurp)
which ydotool || echo "MISSING: ydotool"
which wtype || echo "MISSING: wtype"
which grim || echo "MISSING: grim"
which slurp || echo "MISSING: slurp"

# X11 tools check (verify xdotool, xclip, scrot)
which xdotool || echo "MISSING: xdotool"
which xclip || echo "MISSING: xclip"
which scrot || echo "MISSING: scrot"

# D-Bus check (verify dbus-send availability)
which dbus-send || echo "MISSING: dbus-send"
```

**If missing (Wayland):**
```
STOP: Cannot proceed with Wayland automation.

Missing tools for Wayland E2E testing.

Install with:
  # Arch
  sudo pacman -S ydotool wtype grim slurp

  # Debian/Ubuntu
  sudo apt install ydotool wtype grim slurp

  # Nix
  nix-env -iA nixpkgs.ydotool nixpkgs.wtype nixpkgs.grim nixpkgs.slurp

Start ydotool daemon:
  sudo systemctl enable --now ydotool
  # Or for user service:
  systemctl --user enable --now ydotool

Reply when installed and I'll continue testing.
```

**This gate is non-negotiable. Missing tools = full stop.**
</EXTREMELY-IMPORTANT>

<EXTREMELY-IMPORTANT>
## When to Use Linux Automation

Use Linux automation (ydotool/xdotool) for:
- Linux native application automation
- GTK/Qt application testing
- System-wide keyboard/mouse control
- Window management testing
- D-Bus service interaction
- Accessibility testing (AT-SPI)

Do NOT use Linux automation for:
- Testing web applications (use Chrome MCP or Playwright)
- macOS desktop automation (use dev-test-hammerspoon)
- Cross-platform testing

Related skills:
- Read `${CLAUDE_SKILL_DIR}/../../skills/dev-test-chrome/SKILL.md` and follow its instructions.
- Read `${CLAUDE_SKILL_DIR}/../../skills/dev-test-playwright/SKILL.md` and follow its instructions.
- Chrome MCP skill - for debugging
- Playwright skill - for CI/CD

### Rationalization Prevention

| Thought | Reality |
|---------|---------|
| "I can test the app manually" | AUTOMATE IT with ydotool/xdotool |
| "Web testing tools work for desktop apps" | NO. Use native Linux tools |
| "ydotool daemon is hard to set up" | One-time setup. Do it. |
| "X11 is deprecated, skip xdotool" | Many systems still use X11. Support both. |
| "D-Bus is too complex" | D-Bus gives precise control. Learn it. |

### Display Server Detection

```bash
# Detect display server and choose appropriate tools
if [ "$XDG_SESSION_TYPE" = "wayland" ]; then
    # Use ydotool, wtype, grim
else
    # Use xdotool, xclip, scrot
fi
```

Always detect display server before choosing tools.
</EXTREMELY-IMPORTANT>

## Detect Display Server

```bash
# Check display server type (Wayland or X11)
if [ "$XDG_SESSION_TYPE" = "wayland" ]; then
    echo "Using Wayland tools (ydotool, wtype, grim)"
else
    echo "Using X11 tools (xdotool, xclip, scrot)"
fi
```

## Wayland: ydotool

Requires ydotoold daemon running.

### Keyboard Input

```bash
# Type text (simple text input to focused window)
ydotool type "hello world"

# Type with delay (type text with microsecond delay between keys)
ydotool type --delay 50 "slow typing"

# Press Enter key (send Enter key using keycode format)
ydotool key 28:1 28:0

# Press Escape key (send Escape key)
ydotool key 1:1 1:0

# Press Ctrl+C (send Ctrl+C combination)
ydotool key 29:1 46:1 46:0 29:0

# Press Ctrl+V (send Ctrl+V combination)
ydotool key 29:1 47:1 47:0 29:0

# Press Alt+Tab (send Alt+Tab combination)
ydotool key 56:1 15:1 15:0 56:0

# Common keycodes reference
# 1=Escape, 14=Backspace, 15=Tab, 28=Enter, 29=Ctrl, 42=LShift
# 56=Alt, 57=Space, 100=RightAlt, 125=Super/Win
```

### Alternative: wtype (Wayland-native)

```bash
# Type text (simple text input to focused window)
wtype "hello world"

# Press Ctrl+C (send Ctrl+C combination)
wtype -M ctrl -k c

# Press Ctrl+Shift+S (send Ctrl+Shift+S combination)
wtype -M ctrl -M shift -k s

# Press Enter (send Enter key)
wtype -k Return

# Press Escape (send Escape key)
wtype -k Escape
```

Available modifiers: shift, ctrl, alt, logo (super)

### Mouse Input

```bash
# Move mouse to absolute position (move cursor to screen coordinates)
ydotool mousemove --absolute 100 200

# Move mouse relative (move cursor by relative offset)
ydotool mousemove 50 -30

# Click left button (send left mouse click)
ydotool click 1

# Click right button (send right mouse click)
ydotool click 3

# Double click (send double click)
ydotool click 1 1

# Click at position (move and click in one operation)
ydotool mousemove --absolute 500 300 && ydotool click 1

# Drag operation (move mouse while holding button)
ydotool mousemove --absolute 100 100
ydotool mousedown 1
ydotool mousemove --absolute 200 200
ydotool mouseup 1
```

## X11: xdotool

### Keyboard Input

```bash
# Type text (simple text input to focused window)
xdotool type "hello world"

# Press Return (send Return key)
xdotool key Return

# Press Escape (send Escape key)
xdotool key Escape

# Press Ctrl+C (send Ctrl+C combination)
xdotool key ctrl+c

# Press Ctrl+Shift+S (send Ctrl+Shift+S combination)
xdotool key ctrl+shift+s

# Press Alt+Tab (send Alt+Tab combination)
xdotool key alt+Tab

# Press Super+D (send Super+D combination)
xdotool key super+d

# Type with delay (type text with millisecond delay between keys)
xdotool type --delay 50 "slow typing"

# Hold key down (press and hold Ctrl)
xdotool keydown ctrl

# Press C (send C key)
xdotool key c

# Release key (release Ctrl)
xdotool keyup ctrl
```

### Mouse Input

```bash
# Move mouse absolute (move cursor to screen coordinates)
xdotool mousemove 100 200

# Move mouse relative (move cursor by relative offset)
xdotool mousemove --relative 50 30

# Click left button (send left mouse click)
xdotool click 1

# Click middle button (send middle mouse click)
xdotool click 2

# Click right button (send right mouse click)
xdotool click 3

# Double click (send double click)
xdotool click --repeat 2 1

# Click at position (move and click in one operation)
xdotool mousemove 500 300 click 1

# Drag operation (move mouse while holding button)
xdotool mousemove 100 100 mousedown 1 mousemove 200 200 mouseup 1
```

### Window Control (X11)

```bash
# Get active window ID (get numeric window identifier)
xdotool getactivewindow

# Focus window by name (find and focus window matching name)
xdotool search --name "Firefox" windowactivate

# Focus window by class (find and focus window matching class)
xdotool search --class "firefox" windowactivate

# Get window title (get title of active window)
xdotool getactivewindow getwindowname

# Move window (move active window to coordinates)
xdotool getactivewindow windowmove 100 100

# Resize window (resize active window to dimensions)
xdotool getactivewindow windowsize 800 600

# Minimize window (minimize active window)
xdotool getactivewindow windowminimize

# Focus window and wait (find, focus, and synchronize with window)
xdotool search --name "Firefox" windowactivate --sync
```

## Screenshots

<EXTREMELY-IMPORTANT>
### The Iron Law of Visual Verificatio