Advanced Usage

Using Secure AltTester® Server (WSS)

AltTester® Desktop provides built-in support for running the AltTester® Server using secure WebSocket connections (WSS). Secure mode enables encrypted communication between AltTester® Desktop, your instrumented application, and automated test drivers.

Note

Secure server support is available only for licenses that include secure-mode features.

Why use Secure WebSocket (WSS)?

Enabling secure mode provides several advantages:

• Encrypted Communication – all exchanged messages are encrypted, preventing interception.

• TLS/SSL Security Layer – communication is protected through the TLS protocol.

• TLS 1.2 Support – the server enforces modern, secure standards.

Secure mode is recommended for:

• Running tests over Wi-Fi or public networks.

• Using AltTester® Desktop in shared environments.

• CI pipelines that involve multiple machines.

• Any situation requiring enhanced privacy or data protection.

Starting the Built-in Secure Server in AltTester® Desktop

AltTester® Desktop includes a built-in AltTester® Server that can run in secure or non-secure mode depending on your configuration.

1. Configure the TLS/SSL Certificate

Navigate to: Settings → AltTester® Server Certificate

Two fields are available:

• Certificate Path – path to a .pfx certificate file

• Password (optional) – password for password-protected certificates

After entering the certificate path, AltTester® Desktop automatically attempts to load the certificate. Any validation issues (missing file, incorrect password, unsupported HMAC, missing private key, expired certificate, etc.) are shown as a tooltip.

If the certificate loads successfully the built-in AltTester® Server automatically starts in secure mode.

2. Server Status Indicator

The AltTester® Server Status section displays whether the server is running and whether the current mode is secure or non-secure.

• 🔒 Locked icon – Secure WSS mode

• ⚠️ Exclamation mark – Non-secure WS mode

Click the icon to view additional status information.

Note

To switch the built-in AltTester® Server back to non-secure mode, simply clear both the Certificate Path and Password fields. Once both fields are empty, the server will restart in standard non-secure (WS) mode.

Supported Certificates

AltTester® Server supports certificates that meet the following requirements:

Supported Format

• .pfx (PKCS#12)
  Must contain both the certificate and the private key.

Required Properties

• Includes a private key

• Uses an RSA private key

• The certificate is valid (not expired, not “not yet valid”)

• Uses supported cryptographic algorithms:

  • RSA

  • SHA256 (recommended)

Note

Certificates using ECDSA, Ed25519, or other non-RSA key types are not supported and will fail to load with an Unknown private key format error.

Password-Protected Certificates

If the certificate requires a password, you must provide one.

PKCS#12 (PFX) Compatibility

When exporting certificates using OpenSSL, it is recommended to use legacy PKCS#12 encryption.

Certificates exported without legacy mode may fail to load with errors such as:

• Unsupported HMAC

• Failed to load certificate

Unsupported Certificates

Certificates will fail validation if they:

• Use unsupported HMAC algorithms

• Do not contain a private key

• Are expired or not yet valid

• Use unsupported algorithms or cipher suites

• Have an incorrect or missing password (if protected)

• Certificates using ECDSA, Ed25519, or Ed448 private keys

• Certificates exported using non-legacy PKCS#12 encryption

• Certificates signed with deprecated or weak algorithms

CA-Signed Certificates

AltTester® Server supports CA-signed certificates, including certificates issued by trusted certificate authorities such as Let’s Encrypt.

When using CA-signed certificates:

• The private key must be RSA

• The full certificate chain should be included in the .pfx file

• Certificates issued with ECDSA keys are not supported

Note

Some certificate authorities (including Let’s Encrypt) may issue ECDSA certificates by default. When generating certificates, ensure that an RSA key is explicitly requested.

Common Certificate Validation Errors

The following issues are commonly encountered when configuring secure mode:

• Access denied

  • The certificate file is not readable by the current user

  • Often caused by files created using sudo

• Unknown private key format

  • The certificate uses an unsupported key type (for example ECDSA)

• Unsupported HMAC

  • The certificate was exported using non-legacy PKCS#12 encryption

• Missing private key

  • The .pfx file does not contain a private key

• Expired or not yet valid certificate

  • The certificate validity period does not include the current system time

Using Secure Connection with a Remote AltTester® Server

AltTester® Desktop can connect to an AltTester® Server running on another machine. Remote server settings are available under: Remote AltTester® Server

A Secure Connection toggle is available.

• Enable it when connecting to a secure wss:// server.

• Disable it when connecting to a non-secure ws:// server.

If the toggle is disabled and the remote server uses WSS, the connection will fail.

Running AltTester® Server in terminal

You can run AltTester® Server in a terminal with the following command:

WindowsMacLinux

Bash: ./AltTesterDesktop.exe -batchmode -port 13000 -license YOUR_LICENSE -nographics -logfile LOGFILE.txt

CMD: AltTesterDesktop.exe -batchmode -port 13000 -license YOUR_LICENSE -nographics -logfile LOGFILE.txt

This is useful when you want to run tests but don’t want to waste resources for the Desktop part.

Note

In case of Windows, we recommend using Git Bash instead of CMD. If you choose to use CMD, the server won’t stop when the terminal is killed. To kill the AltTester® Desktop process if the CMD is still opened, please open the Task Manager and search for a process called Windows Command Processor (a process that, when expanded, displays the AltTester® Desktop process). If CMD was closed, the steps are similar, except that you should look exactly for the AltTester® Desktop process and kill it.

Command line arguments

Argument	Required	Information
-batchmode	Yes	Unity related argument. Please check PlayerCommandLineArguments for more details.
-nographics	Yes	Unity related argument. Please check PlayerCommandLineArguments for more details.
-port INTEGER	Yes	Sets the port on which AltTester® Server will start, this value must be between 1 and 65535. This is a mandatory argument for running AltTester® Server.
-license TEXT	No	Yes when you never activated a license on the device and you try to run AltTester® Server add this argument with a valid licenseKey. This argument is not necessary if you already activated the license on the device.
-removeActivation	No	Deactivates the active license key if there is one. If you add this argument AltTester® Server will not start (the -port argument is not needed in this situation). AltTester® Desktop will just try to deactivate the license key and quit after.
-termsAndConditionsAccepted	No	Means that you have read our Terms and Conditions and you accept them. You only need to specify this argument the first time using AltTester® Server or any time our Terms and Conditions are updated. Please take a look at the example below.
-logfile FILE	No	This argument is needed in case of saving the logs in a specific file. -logfile - will output logs in the bash terminal
-version	No	Displays the AltTester® Desktop version. You should use this argument together with -batchmode and -nographics.
-certificatePath FILE	No	Path to a .pfx certificate used to start AltTester® Server in secure mode. If this argument is provided with a valid certificate, the server will automatically start in secure (WSS) mode.
-certificatePassword TEXT	No	Password for the certificate, if needed. Leave empty for certificates without password protection.

WindowsMacLinux

Bash: ./AltTesterDesktop.exe -batchmode -port 13000 -license YOUR_LICENSE -nographics -logfile LOGFILE.txt -termsAndConditionsAccepted

CMD: AltTesterDesktop.exe -batchmode -port 13000 -license YOUR_LICENSE -nographics -logfile LOGFILE.txt -termsAndConditionsAccepted

Note

The run of the command may be stuck if the value for -port contains certain special characters. In this case is recommended to rerun the process using a valid port number.

Starting AltTester® Server in Secure Mode (Batchmode)

To run the AltTester® Server in secure mode when starting AltTester® Desktop in batchmode, provide the -certificatePath argument, and optionally the -certificatePassword argument.

If the certificate is valid, the server will automatically start in secure (WSS) mode.

WindowsMacLinux

Bash: ./AltTesterDesktop.exe -batchmode -port 13000 -nographics -certificatePath C:/certs/server.pfx -certificatePassword mypass

CMD: AltTesterDesktop.exe -batchmode -port 13000 -nographics -certificatePath C:/certs/server.pfx -certificatePassword mypass

Note

Secure server support is available only for licenses that include secure-mode features.

Code examples for setting up AltTester® Server from terminal

This section is for users who want to set up the AltTester® Server from terminal (eg: for servers or pipelines).

MacLinux

1. Export your license which is stored in a file:

export LICENSE_KEY=$(cat license.txt)

* storing the license in a file is not a must, but it’s a safe practice

2. Download the AltTester® archive from alttester.com using the following command:

wget https://alttester.com/app/uploads/AltTester/desktop/AltTesterDesktopPackageMac__v2.2.7.zip

3. Unzip the AltTester® Desktop folder and move to it:

unzip AltTesterDesktopPackageMac__v2.2.7.zip
cd AltTesterDesktopPackageMac__v2.2.7

4. Attach the AltTester® Desktop as disk:

hdiutil attach AltTesterDesktop__v2.2.7.dmg

5. Copy the .app file to the Application folder and move to it:

cp -R /Volumes/AltTesterDesktop/AltTesterDesktop.app /Applications
cd /Applications

6. Start the AltTester® Desktop in batchmode:

AltTesterDesktop.app/Contents/MacOS/AltTesterDesktop -batchmode -port 13000 -license $LICENSE_KEY -nographics -logfile LOGFILE.txt

7. Run your tests:

• depending on your set up, you might go out from this folder and run your tests

8. Remove the AltTester® Desktop from Applications:

rm -r /Applications/AltTesterDesktop.app

9. Detach the AltTester® Desktop disk:

hdiutil detach /Volumes/AltTesterDesktop