Run tests in Jenkins with a specific user account

Use the LaunchAsUser tool to run OpenText Functional Testing for Developers tests in Jenkins under a specific Windows user account within an interactive desktop session.

In this topic:

Overview

The LaunchAsUser tool enables you to launch and manage OpenText Functional Testing for Developers processes under a specific Windows user account from your Jenkins CI job. This is particularly helpful for automated testing scenarios where:

• You need to run tests under a dedicated service account.
• The test environment requires specific user permissions or configurations.
• You want to isolate test execution across different user contexts.

Back to top

Prerequisites

Before using the LaunchAsUser tool with Jenkins, ensure the following requirements are met:

Logged-in Windows Session

Before initiating the Jenkins job that uses the LaunchAsUser tool, you must log in to the machine where the tests will run using Remote Desktop Protocol (RDP). This ensures an interactive desktop session is available for the test execution.

Tool Availability

Ensure the LaunchAsUser.exe tool is accessible on the Jenkins agent. The tool is typically located in:

• <FT_install_folder>\bin\LaunchAsUser.exe
• Or a custom path such as C:\LaunchAsUser.exe

Prerequisites on the Agent

1. Install the OpenText Functional Testing for Developers runtime engine on the Jenkins agent.
2. Deploy your compiled test files (DLLs/JARs) to the agent computer.
3. Install the AUT (Application Under Test) on the agent computer.
4. Configure the Jenkins agent to maintain an active Windows session.

Back to top

Configure your Jenkins job

To run tests with a specific user account, configure your Jenkins job with the following steps:

Step 1: Set environment variables

Within your Jenkins job (using an Execute Windows batch command build step), set the following environment variables:

Replace the following:

• <specific_username> - The Windows user account under which OpenText Functional Testing for Developers should run. Use domain\username or username@domain format (for example: DOMAIN\swinfra_ft_auto, devUser@company.com, testdomain\qa)
• <encoded_password> - The securely encoded password for the specified username

Step 2: Start the LeanFT process

Use the LaunchAsUser tool to start the OpenText Functional Testing for Developers process under the specified user account:

LaunchAsUser.exe leanft start

If the tool is not in the system PATH, provide the full path:

"C:\Program Files (x86)\OpenText\Functional Testing for Developers\bin\LaunchAsUser.exe" leanft start

Step 3: Run your tests

After successfully starting the OpenText Functional Testing for Developers process, execute your test as you normally would. You can run both Web and Desktop UI tests. For example:

<NUnit Path>\bin\nunit-console-x86.exe "%PATH_TO_TEST_PROJECT_DLL%\DLLFileName.dll"

Or, if using Maven for Java tests:

mvn test –P leanft-tests

Step 4: Stop the LeanFT process (Optional)

After test execution completes, optionally stop the OpenText Functional Testing for Developers process:

LaunchAsUser.exe leanft stop

Back to top

General LaunchAsUser tool usage

The general syntax for running any executable with the LaunchAsUser tool is:

LaunchAsUser.exe <Executable To Run> <Arguments>

This allows you to run any Windows executable under the context of the user account and interactive session specified in the FTD_RUNAS_USERNAME and FTD_RUNAS_ENCODED_PASSWORD environment variables.

Back to top

Important considerations

• Logged-in session requirement: You must log in to the machine (via RDP) before the Jenkins job starts. The Windows session must remain logged in throughout test execution.

• Session persistence: After the OpenText Functional Testing for Developers process has started, you can disconnect the RDP connection (without logging out). The UI tests will continue to execute correctly in the user session.

• Password security: Store and reference encoded passwords securely using Jenkins credentials management rather than hardcoding them.

• Test configuration across agents: Test your LaunchAsUser configuration across various Jenkins agent setups, such as:

  • AWS service agents
  • Built-in Windows service agents
  • Interactive slave agents (such as node02)

• Platform compatibility: While primarily tested on Windows Server 2019, test your configuration on Windows Workstation editions (Windows 10/11 Pro or Enterprise) to ensure broad compatibility with your target environments.

Back to top

Known limitations

Jenkins agent service with specific user account

Issue: When running the Jenkins agent as a Windows service with a specific user account (not LocalSystem), you may encounter the following error:

Win32=1314 (ERROR_PRIVILEGE_NOT_HELD) from WTSQueryUserToken

Cause: The LaunchAsUser tool only works when the Jenkins agent service is run as LocalSystem. Running the agent service under a different user account is restricting the service to use the interactive session, even if additional privileges are granted to that account.

Resolution options:

• Option 1 (Recommended): Run the Jenkins agent service as LocalSystem.
• Option 2: Run the Jenkins agent interactively (not as a service). This allows your launcher to execute directly inside the user's session.

Back to top

See also:

• Run tests using a CI system
• Run tests remotely