Skip to content
awesomewm testing tool
Branch: master
Clone or download
serialoverflow Merge pull request #9 from qbit/master
Move from using /proc to uname for hostname information.
Latest commit 92ababc Feb 14, 2017
Type Name Latest commit message Commit time
Failed to load latest commit information.
LICENSE added MIT license Mar 4, 2014 Update Jan 11, 2015 Move from using /proc to uname for hostname information. Feb 14, 2017
example.jpg reimplemented multisession support, added a couple of fail-safes, Nov 20, 2013


awmtt (AwesomeWM Testing Tool) is a bash script that helps you test your Awesome configuration files.
It requires Xephyr, an Xorg-Application which can spawn a nested instance of xorg-server, allowing you to open multiple instances of Desktop Environments or Window Mangers like AwesomeWM.


ArchLinux users can find awmtt in the AUR.

Example Debian/Ubuntu manual installation:

sudo apt-get install xserver-xephyr
sudo wget -O /usr/bin/awmtt
sudo chmod a+x /usr/bin/awmtt


Here's an example of what it looks like:


awmtt start [-B <path>] [-C <path>] [-D <int>] [-S <size>] [-a <opt>]... [-x <opts>]
awmtt (stop [all] | restart)
awmtt run [-D <int>] <command>
awmtt theme (get | set <theme> | list | random) [-N]

  start           Spawn nested Awesome via Xephyr
  stop            Stops the last Xephyr process
    all           Stop all instances of Xephyr 
  restart         Restart all instances of Xephyr
  run <cmd>       Run a command inside a Xephyr instance (specify which one with -D)
  theme           Some basic theming control via:
    get           Get current theme name
    set <theme>   Set theme to <theme>
    list          List available themes
    random        Set a random theme
  -B|--binary <path>  Specify path to awesome binary (for testing custom awesome builds)
  -C|--config <path>  Specify configuration file
  -D|--display <int>  Specify the display to use (e.g. 1)
  -N|--notest         Don't use a testfile but your actual rc.lua (i.e. $HOME/.config/awesome/rc.lua)
                      This happens by default if there is no rc.lua.test file.
  -S|--size <size>    Specify the window size
  -a|--aopt <opt>     Pass option to awesome binary (e.g. --no-argb or --check). Can be repeated.
  -x|--xopts <opts>   Pass options to xephyr binary (e.g. -keybd ephyr,,,xkblayout=de). Needs to be last.
  -h|--help           Show this help text and exit
  awmtt start (uses defaults: -C $HOME/.config/awesome/rc.lua.test -D 1 -S 1024x640)
  awmtt start -C /etc/xdg/awesome/rc.lua -D 3 -S 1280x800 -x -keybd ephyr,,,xkbmodel=pc105,xkblayout=de,xkbrules=evdev,xkboption=grp:alts_toogle
  awmtt theme set zenburn -N


Have a look at and its documentation to learn more about how to use it. For instance, you can press Control-Mod3-Shift to have Xephyr grab focus while inside the window so that you can't accidentally leave it. To let go, press Control-(Right-)Shift.

You can’t perform that action at this time.