TESTING.md

Testing

Start with nested development testing:

cargo check
cargo check --workspace
cargo test --workspace
scripts/smoke-macos.sh
scripts/smoke-shell-dbus.sh
scripts/smoke-session-linux.sh
scripts/smoke-linux-vm.sh
scripts/smoke-windowed-shell.sh
scripts/validate-display-manager-session.sh --self-test
cargo run -p seatshell-shell
cargo run -p seatshell-session -- --dry-run
cargo run -p seatshell-session -- --dev-dry-run
cargo run -p seatshell-user-agent -- --dry-run
cargo run -p seatshell-admin-daemon -- --dry-run
scripts/run-seatshell.sh --dry-run
scripts/run-seatshell.sh --windowed --dry-run
scripts/smoke-dbus.sh
scripts/install-seatshell.sh --debug --prefix /tmp/seatshell-install
PREFIX=/tmp/seatshell-install scripts/validate-seathell-install.sh
PREFIX=/tmp/seatshell-install scripts/validate-display-manager-session.sh --skip-host

seatshell-shell uses a Slint build script, so macOS checks and tests link a host build binary. If Cargo reports that the Xcode license has not been accepted, run sudo xcodebuild -license in Terminal before running full workspace checks.

For a macOS-first repository smoke pass, prefer:

scripts/smoke-macos.sh

That script runs formatting, workspace checks/tests, admin and session dry runs, a temporary install, installed-layout validation, display-manager session validation, validator self-tests, shell D-Bus smoke coverage, and a windowed screenshot smoke that can be exercised without a Linux login manager.

For direct D-Bus smoke coverage of the running shell services:

scripts/smoke-shell-dbus.sh

That script starts seatshell-shell on a temporary session bus, waits for org.seatshell.Shell and org.freedesktop.Notifications, and verifies representative view-toggle and notification methods respond cleanly. When dbus-daemon is available it uses a private bus directly; otherwise it falls back to dbus-run-session.

For direct screenshot-based UI regression smoke coverage on macOS:

scripts/smoke-windowed-shell.sh

That script captures windowed screenshots for desktop, launcher, and system-center surfaces and fails if expected PNG artifacts are not produced.

For a macOS-first UI pass, use the windowed shell before moving to Linux-specific session validation:

cargo run -p seatshell-shell -- --windowed

Use that run to verify:

• the desktop, panel, launcher, overview, command surface, and notifications all render cleanly
• system center, settings, and power-menu scaffolds render cleanly
• resizing the window does not produce clipped text, broken spacing, or collapsed action rows
• launcher search, app selection, pinned-app toggles, and overview keyboard movement still work
• empty states are readable when no apps or sessions are available
• under labwc, Super+Space, Super+Tab, Super+D, and Super+N open apps, sessions, desktop, and notifications

The local release gate is:

cargo fmt --all --check
cargo check --workspace
cargo test --workspace
scripts/validate-display-manager-session.sh --self-test
scripts/smoke-shell-dbus.sh
scripts/smoke-windowed-shell.sh
cargo run -p seatshell-session -- --dry-run
cargo run -p seatshell-session -- --dev-dry-run
cargo run -p seatshell-user-agent -- --dry-run
cargo run -p seatshell-admin-daemon -- --dry-run
scripts/run-seatshell.sh --dry-run
scripts/run-seatshell.sh --windowed --dry-run
scripts/install-seatshell.sh --debug --prefix /tmp/seatshell-install
PREFIX=/tmp/seatshell-install scripts/validate-seathell-install.sh
PREFIX=/tmp/seatshell-install scripts/validate-display-manager-session.sh --skip-host

For the service-pair D-Bus smoke that targets the admin daemon and user agent directly:

scripts/smoke-dbus.sh

That script starts seatshell-admin-daemon and seatshell-user-agent inside dbus-run-session and verifies that their registered methods respond. It skips when dbus-run-session or gdbus is unavailable.

For a Linux session smoke that does not require a display manager:

scripts/smoke-session-linux.sh

That script starts seatshell-session --windowed on a private session bus, waits for org.seatshell.Admin, org.seatshell.UserAgent.u<uid>, and org.seatshell.Shell, and then shuts the session down cleanly. It is the fastest host-safe Linux gate for the session supervisor path.

For the broader Linux VM regression gate:

scripts/smoke-linux-vm.sh

That script builds the workspace, runs scripts/smoke-dbus.sh, scripts/smoke-session-linux.sh, and scripts/smoke-labwc.sh, installs into a temporary prefix, validates the install tree, and validates the generated display-manager session metadata. Add --strict-host when the VM or host also has a real system-visible SeatShell session installed under /usr/local or /usr/share.

Then move to a Linux VM with labwc:

cargo build --workspace
scripts/smoke-session-linux.sh
scripts/smoke-linux-vm.sh
scripts/smoke-labwc.sh

The labwc smoke test starts seatshell-session inside dbus-run-session with the checked-in labwc config directory and treats timeout as success, because a healthy desktop session should keep running until the harness stops it.

Before tagging a desktop release, verify in that Linux/labwc session that:

• seatshell-shell starts without compositor or Slint backend errors.
• the panel can toggle desktop, launcher, and overview.
• the labwc shortcuts open apps, sessions, desktop, and notifications.
• the desktop shows quick-launch entries and recent launches after opening apps.
• launcher search filters application rows and Enter launches the first match.
• launcher entries from resources/applications appear and launch expected commands available in the VM.
• seatshell-user-agent owns org.seatshell.UserAgent.u<uid> on the session bus.
• seatshell-admin-daemon owns org.seatshell.Admin and returns users/sessions over D-Bus.
• logs are written under ~/.local/state/seatshell/logs and capture session child output.

On a host that actually runs a display manager, also validate the system-visible session entry:

PREFIX=/usr/local scripts/validate-display-manager-session.sh --strict-host

That check should confirm the generated seatshell.desktop is installed into a Wayland session directory visible to the greeter and that its Exec and TryExec launcher still run with --dry-run.

Launcher development app discovery can be tested with:

mkdir -p resources/applications
cargo run -p seatshell-shell -- --launcher

Individual shell surfaces can be opened directly for windowed UI checks:

cargo run -p seatshell-shell -- --windowed --system-center
cargo run -p seatshell-shell -- --windowed --settings
cargo run -p seatshell-shell -- --windowed --power-menu

Use --window-size=<width>x<height> with --windowed to exercise responsive breakpoints without manually resizing the host window:

cargo run -p seatshell-shell -- --windowed --window-size=280x480 --settings
cargo run -p seatshell-shell -- --windowed --window-size=390x720 --launcher
cargo run -p seatshell-shell -- --windowed --window-size=768x560 --settings
cargo run -p seatshell-shell -- --windowed --window-size=1440x500 --system-center