.. _remote: Checkbox Remote ^^^^^^^^^^^^^^^ It is possible to run Checkbox tests on a device that you don't or cannot have traditional control over (mouse/keyboard). By using Checkbox Remote facilities you can use Checkbox on one device (the :term:`controller`) to control Checkbox running on a different device (the :term:`agent`). This is especially useful on headless devices. Comparison with SSH =================== Although it is possible to connect to a device using SSH and run Checkbox locally on it, if the device doesn't offer screen-like functionality then the Checkbox session might have to be started over if the connection to the device is lost. When a UI is drawn a lot of data is transmitted through the network. Checkbox Remote sends lean data only. Nomenclature ============ Checkbox Agent See :term:`Checkbox Agent` in the glossary. Checkbox Controller See :term:`Checkbox Controller` in the glossary. Invocation ========== Agent ``checkbox-cli run-agent`` Controller ``checkbox-cli control HOST [/PATH/TO/LAUNCHER]`` ``HOST`` can be an IP or a hostname that the controller can resolve. ``LAUNCHER`` (optional) a launcher file to use that exists somewhere on the machine you are using as the controller. Example: ``checkbox-cli control dut8.local /home/ubuntu/testplans/sutton-client`` Custom port =========== By default, the Agent listens on port 18871. To change that ``--port`` option can be used. The same option used on the Controller specifies which port to connect to. Examples: ``checkbox-cli run-agent --port 10101`` ``checkbox-cli control dut8.local --port 10101`` .. _remote_session_control: Session control =============== While Controller is connected, sending ``SIGINT`` (pressing ``Ctrl-C``) to the application invokes the interrupt screen which provides the following choices: Nothing, continue testing (ESC) As the name implies, it returns to the session. You can press the ``Esc`` key to get the same result. Stop the test case in progress and move on to the next Skip current test case and move to the next. Pause the test session and disconnect from the agent (CTRL+C) Leave the session on the Agent running but let the Controller exit. Pressing ``Ctrl-C`` a second time will have the same effect. It is possible to reconnect to the Agent later on and resume the testing session. Exit and stop the Checkbox service on the agent at 127.0.0.1 Stop the current test session and terminate the Checkbox Agent. In addition, stop the Controller. End this test session preserving its data and launch a new one Stop the current session on the Agent and mark it so it is not possible to resume it, then immediately start a new one. The Controller will be greeted with the test plan selection screen unless a launcher was used to bypass the selection screens, in which case a similar test session is immediately started. Automatic session resume ======================== When the agent starts, it checks if there is a previous session that was not abandoned. If there is, and the session was a non-interactive one it resumes it. Otherwise, it waits for a Controller to connect and chose what to do. The outcome of the job that was last running before the session was interrupted is decided on the type of job it was running. The jobs marked with a ``noreturn`` flag are marked as passing, while other jobs are considered to have crashed (due to the interruption of the session like a reboot or a system stall). .. mermaid:: graph TD; process("agent process starts") load("load previous session") resume("resume the previous session") resume_crashed("resume the previous session") interactive{"last session interactive?"} mark_pass("mark last running job as passing") mark_crash("mark last running job as crashing") idle("go into idle state") listen("listen for a controller") process --> load last_job{"last job ``noreturn``?"} load -->last_job last_job-->|yes| resume resume --> mark_pass last_job-->|no| interactive interactive-->|yes| idle idle --> listen mark_pass --> listen interactive-->|no| resume_crashed resume_crashed --> mark_crash mark_crash --> listen Remote session characteristics ============================== Differences between a remote session and a local one are: * Unless the session is explicitly abandoned, Checkbox Agent always resumes the last session. * After testing is done, Checkbox Agent starts a new session * Submission is done from the Controller by default (use ``local_submission = No`` in launcher or config to change this). * When the Controller reconnects mid interactive test, the test is restarted. * Hitting ``Ctrl+C`` on the Controller does not interrupt the running test.