Advanced Usage

Using Secure AltTester® Server (WSS)

AltTester® Desktop can run 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 a Secure AltTester® Server from AltTester® Desktop

The AltTester® Server that AltTester® Desktop starts for you (see Get the AltTester® Server) can run in secure or non-secure mode, depending on how you configure the Start Server tab.

1. Turn on secure mode

On the Start Server tab, expand the server settings with the chevron and enable the Secure Connection toggle. The certificate fields are only used - and only validated - while the toggle is on, so a non-secure server never fails to start over a certificate you are not using.

2. Configure the TLS/SSL Certificate

Two fields sit under the toggle:

  • Certificate file - path to a .pfx certificate file. Browse opens a file picker.

  • Certificate password (optional) - password for password-protected certificates

AltTester® Desktop loads the certificate when you start the server. Validation problems (missing file, incorrect password, unsupported HMAC, missing private key, expired certificate, etc.) are shown inline, under the field they belong to.

Note

These fields used to live on the Settings page. They are part of the server’s own settings now, on the Start Server tab, next to the port and the license key.

3. Check which mode the server is running in

While the server is running, the status next to the server’s name reads Running and the address underneath shows which mode it uses:

  • wss://<host>:<port> – secure mode (WSS)

  • ws://<host>:<port> – non-secure mode (WS)

Use this address, including the wss:// scheme, when you connect your instrumented app and your tests to a secure server.

4. Apply changes to a running server

The Secure Connection toggle and both certificate fields can be changed while the server is running, but the change only takes effect after a restart. Until then, the status line names what is waiting, for example “Restart required to use secure server and the selected certificate (2 connections will be dropped)”, and the action button reads Restart Server. Press it to restart the server with the new settings. Everything connected to the server is dropped and reconnects.

Note

To switch back to non-secure mode, turn the Secure Connection toggle off and press Restart Server.

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 on the Connect to Server tab.

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

Note

Starting AltTester® Desktop in batchmode (-batchmode -nographics) is no longer supported. AltTester® Server runs as a separate process, so start the server itself when you need it in a terminal, on a CI machine or on a build server, instead of starting AltTester® Desktop without a UI. AltTester® Desktop will exit with an error if it is started in batchmode.