Configure your agent for unattended test runs

If you shut down the machine that runs your team agent, this also shuts down the agent. Also, if you log out from the machine, the agent won't be able to run UI tests. Alternatively, you can configure your team agent to auto-restart when your machine does. This also helps restore your testing activities after an unexpected shutdown.

Configure your agent

To configure your agent for unattended test runs, follow these steps:

1. Install Microsoft Autologon (opens in new tab) and configure credentials for an account that will be used to run the agent. Every time the system starts, it uses these credentials to log on and create a Windows console session on system boot.

   Before you start using Microsoft Autologon, keep these things in mind:

   • Disable any interactive logon messages. On-screen messages prevent the Autologon process from accessing the machine.

   • Always use the argument --keepdisplayon while configuring Launcher to avoid machine lockouts. Without this argument, settings that lock a machine or put the machine into a sleep state after a configured timeout threshold may block any test runs sent to the team agents.

   We recommend that you use either a local or domain-based dedicated user or a Windows Service Account to set up and run the team agent. This prevents conflicts between users and the team agent configuration files. It also reduces the likelihood of problems when a user’s credentials expire, a user is locked out, or the user who installed the team agent isn't available.

   Avoid logging into the machine again as the same user. This will interrupt the console session that was created by the Autologon process and will block your test run. If you need to log into the machine to perform troubleshooting or system maintenance, use a different local or domain-based user.

   If you don't have the option to log in as a different user, you must have admin permissions to reconnect to the console session.

   Please see the examples below and refer to the Microsoft documentation (opens in new tab) for more details about this process.

   Manual session swap from RDP to Console

   Copy

   1
   2
   3
   4
   5
   6
   7
   ## This requires administrator permission and will switch an RDP session to a console session if the original console session is interrupted
   
   ## Find your session ID
   query session
   
   ## Use your session ID to change the rdp-tcp session to a console session. NOTE: This will close your RDP session immediately
   tscon <SESSION_ID> /dest:console

   Batch script for session swap from RDP to Console

   Copy

   1
   2
   @echo off
   powershell -Command "$xses = (query session | findstr $env:username) -split '\s+' | Select-Object -Index 2; tscon $xses /dest:console"

2. During the first setup and run of Launcher and team agent, provide the client secret from your tenant to authenticate the team agent.

   After initial setup, the client secret value is stored locally in the user profile and will be used on subsequent Launcher and team agent startups.

3. Create a Batch script to execute the team agent. Here's an example:

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   REM launch-team-agent.bat 
   @echo off
   
   REM EXAMPLE USAGE
   REM Powershell -Command "Set-DisplayResolution -Width 1920 -Height 1080 -Force"
   
   Powershell -Command "Set-DisplayResolution -Width <WIDTH> -Height <HEIGHT> -Force"
   
   REM EXAMPLE USAGE 
   REM launcher agent --shared --keepdisplayon --liveview --tenant mytoscacloud --agentId TeamAgent1 --characteristics Platform:Win32NT Team:MyTeam1 
   
   launcher agent --shared --keepdisplayon --liveview --tenant <your tenant name> --agentId <name of this agent> --characteristics <name1>:<value1> <name2>:<value2>

   • Edit the resolution values in the script to set your desired height and width. Without this command, the Autologon console session will start in 1024x768 resolution with a 4:3 aspect ratio.

   • Replace arguments in the launcher command to define your values for --tenant, --agentId, and --characteristics.

   • The argument --shared is required to start Launcher as a team agent.

   • We recommend using the argument --keepdisplayon to ensure that the console session doesn't lock or timeout. Please note that local GPO or security settings may override this argument, and you may need to adjust the environment.

   • Use the argument --liveview to allow your users to turn on LiveView and view the activity on the team agent in near-real time while running tests.

   • Optionally, define the --characteristics argument to change default characteristics.

   • Manually run this script to authenticate the agent and confirm that you have the proper permissions to run commands using Batch/PowerShell.

     When you run the Batch script for the first time, Launcher asks you for the client secret. You can get the client secret when you set up your agent.

   • We recommend saving this script in a location where other users can view and run it if needed. Avoid saving this script in a location where only the Windows Service account or administrator user can access it.

4. Add this Batch script to run as a startup application for the user you configured in Autologon.

   When the machine boots and this user logs in, the Batch script automatically starts the team agent.