Skip to main content
Version: 2.2 (dev)

Test mode somewm-only

somewm-client test runs another SomeWM process in a window or with a headless backend. It gives that process separate runtime and IPC sockets so you can test a configuration without replacing your desktop session.

What it actually is​

The test instance runs as your user with access to the same files, libraries and services. It is not a VM or a filesystem sandbox. Configuration and spawned applications can still change your real files.

The orchestrator sets:

VariablePurpose
XDG_RUNTIME_DIRPer-instance runtime directory under $XDG_RUNTIME_DIR/somewm-test/<name>/
WLR_BACKENDSWayland, X11 or headless backend
SOMEWM_SOCKETPer-instance IPC socket
SOMEWM_TEST_NAMEInstance identity used by test-specific behaviour

When to reach for it​

TaskTool
Check syntax and known compatibility patterns without loading the configsomewm --check path/to/rc.lua
Exercise widgets, layouts, signals and shortcutsA nested test instance
Run Lua assertions without a graphical display--host headless
Isolate configuration from personal filesA VM or separate user account
Check physical display modes, input hardware or direct-session behaviourA session on the relevant hardware

See Testing with a nested compositor for commands, or Try SomeWM for a walkthrough.

How the nesting works​

The Wayland backend creates a surface on the host compositor. The X11 backend creates an X window and requires --host x11. Host input is forwarded into the nested compositor, which runs its own clients, layouts and widget rendering.

The headless backend creates virtual outputs without host windows. It still runs the compositor and Lua environment, but does not exercise physical display hardware.

Lifecycle​

test start creates the state directory and starts the compositor. It polls for the IPC socket every 50 milliseconds, for up to 30 seconds. A successful connection and ping confirm that IPC is available. They do not prove that the requested configuration loaded, since SomeWM may have fallen back to another config. Read the log for load errors. If the child exits, reports a fatal error or misses the deadline, the log is retained.

test stop sends SIGTERM and waits up to five seconds before using SIGKILL. It then removes the instance state directory, including the log.

test list probes instance sockets and marks unreachable entries as stale. test stop --name <name> also removes stale state. Named instances have separate sockets, so several can run at once.

The keybind problem​

The host sees keyboard input first and may consume shortcuts such as Mod4 + Return.

If the host supports shortcut inhibition, the focused test window requests that shortcuts be forwarded. Otherwise, the test shim remaps Mod4 bindings to Mod1, so the nested shortcut becomes Alt + Return. The config file is not rewritten.

The startup status reports which mode is active. Availability depends on the host and its policy, so use that status rather than assuming a particular desktop forwards shortcuts.

Credit​

The workflow was inspired by AWMTT, which uses Xephyr for AwesomeWM. SomeWM uses wlroots backends and adds named instances, headless operation and IPC evaluation. See attribution and the test command reference.