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. Example:

$ py.test --hosts='ssh://server'
$ py.test --ssh-config=/path/to/ssh_config --hosts='ssh://server'
$ py.test --ssh-identity-file=/path/to/key --hosts='ssh://server'
$ py.test --hosts='ssh://server?timeout=60&controlpersist=120'

By default timeout is set to 10 seconds and ControlPersist is set to 60 seconds. You can disable persistent connection by passing controlpersist=0 to the options.


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 is able to parse ansible inventories to get host connection details. For local, ssh, paramiko or docker connections it will use the equivalent testinfra connection backend, unless force_ansible=True (or --force-ansible) is set.

For other connections types or when force_ansible=True, testinfra will run all commands through ansible, which is substantially slower than using native connections backends.


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


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'
# you can specify kubeconfig either from KUBECONFIG environment variable
# or when working with multiple configuration with the "kubeconfig" option
$ py.test --hosts='kubectl://somepod-123?kubeconfig=/path/kubeconfig,kubectl://otherpod-123?kubeconfig=/other/kubeconfig'


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 or LXD containers. It uses the lxc exec command:

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