diff --git a/docs/source/RemoteMachinePlugin.rst b/docs/source/RemoteMachinePlugin.rst new file mode 100644 index 0000000000000000000000000000000000000000..daed68048e17ea508a46c9de30c09437a2c44cba --- /dev/null +++ b/docs/source/RemoteMachinePlugin.rst @@ -0,0 +1,76 @@ +.. _Remote Machine Plugin: + +===================== +Remote Machine Plugin +===================== + +Avocado implements a feature that lets +you run tests directly in a remote machine with SSH connection, +provided that you properly set it up by installing Avocado in it. + +Remote Plugin Basics +==================== + +The remote plugin is one of the basic plugins provided by Avocado. +You can check for its presence by listing your plugins:: + + $ scripts/avocado plugins + Plugins loaded: + ... + run_remote - Run tests on a remote machine (Enabled) + ... + +This plugin adds a number of options to the avocado test runner:: + + --remote-hostname REMOTE_HOSTNAME + Specify the hostname to login on remote machine + --remote-port REMOTE_PORT + Specify the port number to login on remote machine. + Default: 22 + --remote-username REMOTE_USERNAME + Specify the username to login on remote machine + --remote-password REMOTE_PASSWORD + Specify the password to login on remote machine + +From these options, you are normally going to use `--remote-hostname` and +`--remote-username` in case you did set up your VM with password-less +SSH connection (through SSH keys). + +Remote Setup +============ + +Make sure you have: + + 1) Avocado RPM installed. You can see more info on + how to do that in the Getting Started Guide. + 2) The domain IP address or fully qualified hostname and the port number. + 3) All pre-requesites for your test to run installed inside the remote machine + (gcc, make and others if you want to compile a 3rd party test suite written + in C, for example). + 4) Optionally, you may have password less SSH login on your remote machine enabled. + + +Running your test +================= + +Once everything is verified and covered, you may run your test. Example:: + + $ scripts/avocado run --remote-hostname 192.168.122.30 --remote-username fedora examples/tests/sleeptest.py examples/tests/failtest.py + REMOTE LOGIN : fedora@192.168.122.30:22 + JOB ID : 60ddd718e7d7bb679f258920ce3c39ce73cb9779 + JOB LOG : /home/rmoura/avocado/job-results/job-2014-10-23T11.45-a329461/job.log + TESTS : 2 + (1/2) examples/tests/sleeptest.py: PASS (1.00 s) + (2/2) examples/tests/failtest.py: FAIL (0.00 s) + PASS : 1 + ERROR : 0 + NOT FOUND : 0 + FAIL : 1 + SKIP : 0 + WARN : 0 + TIME : 1.01 s + +As you can see, avocado will copy the tests you have to your remote machine and +execute them. A bit of extra logging information is added to your job summary, +mainly to distinguish the regular execution from the remote one. Note here that +we did not need `--remote-password` because the SSH key is already setup. diff --git a/docs/source/index.rst b/docs/source/index.rst index 93066329e48abe9f6302eadd3078456f4e229bd9..35c8a20384873b09c090178619dcd41ec36ccdfa 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -21,6 +21,7 @@ Contents: Plugins OutputPlugins VirtualMachinePlugin + RemoteMachinePlugin DebuggingWithGDB ContributionGuide api/modules diff --git a/man/avocado.rst b/man/avocado.rst index 7ee39768aeae6f1aa4e05d7828f71e8959d321bf..075a5c104912db5d12b0a337330f72a3a739ef44 100644 --- a/man/avocado.rst +++ b/man/avocado.rst @@ -378,6 +378,42 @@ Let's look what's in each of them:: Now, every time this test runs, it'll take into account the expected files that were recorded, no need to do anything else but run the test. +RUNNING REMOTE TESTS +==================== + +Avocado allows you to execute tests on a remote machine by means of a SSH +network connection. The remote machine must be configured to accept remote +connections and the Avocado framework have to be installed in both origin +and remote machines. + +When running tests on remote machine, the test sources and its data (if any present) +are transfered to the remote target, just before the test execution. +After the test execution, all test results are transfered back to the origin machine. + +Here is how to run the sleeptest example test in a remote machine with IP +address 192.168.0.123 (standard port 22), remote user name `fedora` and +remote user password `123456`:: + + $ avocado run --remote-hostname 192.168.0.123 --remote-username fedora --remote-password 123456 + +The output should look like:: + + REMOTE LOGIN : fedora@192.168.0.123:22 + JOB ID : + JOB LOG : /home//avocado/job-results/job--/job.log + TESTS : 1 + (1/1) sleeptest.py: PASS (1.01 s) + PASS : 1 + ERROR : 0 + NOT FOUND : 0 + FAIL : 0 + SKIP : 0 + WARN : 0 + TIME : 1.01 s + +For more information, please consult the topic Remote Machine Plugin +on Avocado's online documentation. + FILES =====