Connection backends

Testinfra comes with several connections backends for remote command execution, they are controlled with the --connection parameter.

For all backends, command can be run as superuser with the --sudo option or as specific user by adding a --sudo-user option.


This is the default backend when not 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 SSHv2 protocol. Testinfra will not ask you for a password, so you must be able to connect without password (using password less keys or using ssh-agent).

You can provide an alternate ssh-config and use sudo on the remote host:

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


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

$ py.test --connection=docker --hosts=[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 --connection=ssh --hosts=server

The ssh backend also accept --ssh-config and --sudo parameters.


The salt backend use the salt python client API and can be used from the salt-master server:

$ py.test --connection=salt # equivalent to --hosts='*'
$ py.test --connection=salt --hosts=minion1,minion2
$ py.test --connection=salt --hosts='web*'
$ py.test --connection=salt --hosts=G@os:Debian

Testinfra will use the salt connection channel to run commands.

Host can be seleted using glob or compound matchers.


The ansible backend use the ansible python API:

$ py.test --connection=ansible # tests all inventory hosts
$ py.test --connection=ansible --hosts=host1,host2
$ py.test --connection=ansible --hosts='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 use the kubectl exec command:

$ py.test --connection=kubectl --hosts=pod_id-123456789-9fng/container_name


The winrm backend uses pywinrm:

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