VPN Integration

Mechasm supports secure VPN integration to allow your tests to access internal staging environments, private APIs, and resources behind corporate firewalls.

This feature runs each test execution in an isolated network namespace, ensuring security and preventing IP conflicts between concurrent runs.

Supported VPN Types

We currently support the following VPN protocols:

OpenVPN (.ovpn)
WireGuard (.conf)

Enabling VPN Integration

To use VPN features, you must first enable the integration in your project settings:

Navigate to your Project Settings.
Select the VPN Integration tab.
Toggle the "Enable VPN" switch.
Select your VPN Type (OpenVPN or WireGuard).

docs.mechasm.ai/vpn-integration.png

Configuration

Once enabled, you need to provide the necessary connection details via Environment Variables. The settings page will verify if these variables are configured correctly.

OpenVPN Configuration

For OpenVPN, you need to provide the configuration file and optionally authentication credentials.

Variable	Required	Description
`VPN_CONFIG`	Yes	The base64-encoded content of your `.ovpn` configuration file.
`VPN_USERNAME`	No	Your VPN username (if auth is required).
`VPN_PASSWORD`	No	Your VPN password (if auth is required).
`VPN_DNS`	No	Custom DNS server for internal name resolution (defaults to `1.1.1.1`).

How to encode your config:

# Linux / macOS
base64 -w 0 client.ovpn

# Windows PowerShell
[Convert]::ToBase64String([IO.File]::ReadAllBytes("client.ovpn"))

WireGuard Configuration

For WireGuard, you need the interface configuration and private key.

Variable	Required	Description
`VPN_CONFIG`	Yes	The base64-encoded content of your `wg0.conf` file (excluding `PrivateKey`).
`VPN_PRIVATE_KEY`	Yes*	The WireGuard private key. (Can be omitted if already included in `VPN_CONFIG`).
`VPN_DNS`	No	Custom DNS server for internal name resolution.

How to encode your config:

# Linux / macOS
base64 -w 0 wg0.conf

Usage in Tests

Once configured, VPN usage is automatic.

When a test runs for a project with VPN enabled:

The test runner creates an isolated network namespace.
It establishes the VPN connection inside that namespace.
It sets up a secure SOCKS5 proxy to tunnel traffic.
The browser is automatically configured to use this proxy.

You do not need to add any special commands to your tests. Simply navigate to your internal URLs as normal:

// This works automatically if VPN is configured
await page.goto('http://internal-staging.company.local');

Security & Isolation

Isolation: Each test run gets its own dedicated VPN connection. Traffic from one test cannot leak into another.
Cleanup: Connections are automatically terminated and network namespaces destroyed immediately after the test finishes.
Timeouts: There is a 90-second timeout for establishing the VPN connection to prevent hanging tests.

Troubleshooting

If your tests are failing to connect:

Check Env Vars: Ensure VPN_CONFIG is a valid base64 string without newlines.
Verify DNS: If you use internal hostnames, make sure VPN_DNS is set to your internal DNS server IP.
Authentication Failed: If using VPN Gate, try a different server or use a TCP configuration (UDP often fails or is blocked).
Check Logs: The test runner logs will show "VPN setup failed" and include the tail of the OpenVPN log.
- AUTH_FAILED: The server rejected your credentials.
- TLS Error: The server is unreachable or the handshake failed.
- Cannot resolve host: DNS resolution for the VPN server failed.