Connection backends

Testinfra comes with several connections backends for remote command execution.

For all backends, commands can be run as superuser with the --sudo option or as specific user with the --sudo-user option.


This is the default backend when no hosts are provided (either via --hosts or in modules). Commands are run locally in a subprocess under the current user:

$ py.test --sudo


This is the default backend when a hosts list is provided. Paramiko is a Python implementation of the SSHv2 protocol. Testinfra will not ask you for a password, so you must be able to connect without password (using passwordless keys or using ssh-agent).

You can provide an alternate ssh-config:

$ py.test --ssh-config=/path/to/ssh_config --hosts=server


The Docker backend can be used to test running containers. It uses the docker exec command:

$ py.test --hosts='docker://[user@]docker_id_or_name'

See also the Test Docker images example.


This is a pure SSH backend using the ssh command available in $PATH. Example:

$ py.test --hosts='ssh://server'

The ssh backend also accepts the --ssh-config option.


The salt backend uses the salt Python client API and can be used from the salt-master server:

$ py.test --hosts='salt://*'
$ py.test --hosts='salt://minion1,salt://minion2'
$ py.test --hosts='salt://web*'
$ py.test --hosts='salt://G@os:Debian'

Testinfra will use the salt connection channel to run commands.

Hosts can be seleted by using the glob and compound matchers.


The ansible backend uses the ansible Python API:

$ py.test --hosts=all # tests all inventory hosts
$ py.test --hosts='ansible://host1,ansible://host2'
$ py.test --hosts='ansible://web*'

You can use an alternative inventory with the --ansible-inventory option.

Note: Ansible settings such as remote_user, etc., may be configured by using Ansible’s environment variables.


The kubectl backend can be used to test containers running in Kubernetes. It uses the kubectl exec command and support connecting to a given container name within a pod and using a given namespace:

# will use the default namespace and default container
$ py.test --hosts='kubectl://mypod-a1b2c3'
# specify container name and namespace
$ py.test --hosts='kubectl://somepod-2536ab?container=nginx&namespace=web'


The winrm backend uses pywinrm:

$ py.test --hosts='winrm://Administrator:Password@'
$ py.test --hosts='winrm://vagrant@'

pywinrm’s default read and operation timeout can be overridden using query arguments read_timeout_sec and operation_timeout_sec:

$ py.test --hosts='winrm://vagrant@'


The LXC backend can be used to test running LXC containers. It uses the lxc exec command:

$ py.test --hosts='lxc://container_name'