Private database testing

Introduction

In data-driven testing, you might need to connect to private resources (e.g., databases, SSH services, internal APIs) and run tests in TestCloud. However, due to network restrictions, TestCloud environments cannot access these resources.

Port forwarding allows you to securely forward network traffic from a local port to a remote private service. When enabled, TestCloud Tunnel automatically opens specified local ports and redirects traffic to the designated private resources within your network. You can then access private resources through these local ports in your test scripts.

How it works

• The Tunnel Client opens local ports on the TestCloud test node.
• Traffic sent to these local ports is automatically forwarded through the tunnel to the defined private destination addresses.
• This enables TestCloud test nodes to securely access internal resources via forwarded connections.

This guide walks you through setting up Port Forwarding Rules with TestCloud Tunnel to securely access your private resources from your local machine.

Forwarding Rule Requirements

To ensure secure and valid forwarding, each port forwarding rule must meet the following requirements:

• Each rule must follow the format: local_port:destination_host:destination_port.

  • local_port: The port opened by the Tunnel Client on the Test Node. Any traffic sent to this port is securely forwarded to the destination inside your private network.
  • destination_host: The private host within your secure network (e.g., localhost, 10.x.x.x).
  • destination_port: The port of the target service inside your network (e.g., 5432 for PostgreSQL).

• Local port must be in the range: 50000 to 60000.
• The rules must not have duplicate source ports (the local port is unique within the rules collection).
• The maximum number of rules allowed per configuration is 5.

Configure port forwarding rules

There are two options to configure forwarding rules: via the tunnelconfig file, or directly via the CLI (Command-line Interface).

Use the tunnelconfig file

1. Open your existing tunnelconfig file.
2. Add or update the forwarding_mode settings to static. This will only traffic matching the pre-defined forwarding rules will be allowed. Other requests are rejected.
   • For example:

   forwarding_mode = "static"
3. In the [tcp] section, add the forwarding rules. For example:

   [tcp]
   MY_DB_1 = "50000:private-db:5432"
   MY_SSH_2 = "50001:private-sh:22"
   • MY_DB_1 and MY_SSH_2 are rule names. These names will later be used inside your test scripts to retrieve forwarded addresses.
4. Start the tunnel as usual. The Tunnel Client will automatically open and forward the specified ports.

Use the command-line interface

You can configure forwarding rules directly via the CLI, using the following format:

./kt config --forwarding-mode static \
  --tcp MY_DB_1=50000:private-db:5432 \
  --tcp MY_SSH_2=50001:private-sh:22

This will automatically update your tunnelconfig file with the forwarding rules.

tip

• You can run ./kt config -help to view instructions for using the config command.

Use forwarded ports in test scripts

For convenience, TestCloud Tunnel exposes each forwarded local port as an environment variable.

The environment variable for each rule is named as TUN_<RULE_NAME>, in which RULE_NAME must contain only alphabetic characters, and cannot contain numbers or special characters.

You can use this environment variable in your test scripts to connect to the private service without hardcoding any connection details. For example, for MY_DB_1 = "50000:private-db:5432", The TestCloud Tunnel will automatically set an environment variable named TUN_MY_DB_1 on the Test Node.

• 50000 is the local port opened on the Test Node.
• It securely forwards traffic to the private destination private-db:5432.

Example test script with a forwarded port

import com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords as WebUI
import com.kms.katalon.core.util.KeywordUtil
import com.kms.katalon.util.CryptoUtil
import internal.GlobalVariable

// Retrieve the local port from environment variable
String tcDbEnv = System.getenv("TUN_MY_DB_1")
// tcDbEnv: 'localhost:50000'
if (tcDbEnv == null || !tcDbEnv.contains(":")) {
    KeywordUtil.markFailed("❌ TUN_TC_DB environment variable is not set or invalid format (expected 'host:port')")
}

String[] dbParts = tcDbEnv.split(":")
String host = dbParts[0].trim() // localhost
String port = dbParts[1].trim() // 50000

try {
    CustomKeywords.'katalon.cloudian.utilities.DatabaseUtility.connect'(
        host,
        GlobalVariable.G_DB_NAME,
        port,
        GlobalVariable.G_DB_USERNAME,
        CryptoUtil.decode(CryptoUtil.getDefault(GlobalVariable.G_DB_PASSWORD))
    )

    List<String> queries = [
        "SELECT COUNT(*) AS total FROM execution_env_service_objs.execution_session",
        "SELECT NOW() AS current_time",
        "SELECT version() AS db_version"
    ]

    int totalLoops = 10

    for (int i = 1; i <= totalLoops; i++) {
        WebUI.comment("🔄 Test loop ${i}")

        for (String query : queries) {
            List<Map<String, Object>> result = CustomKeywords.'katalon.cloudian.utilities.DatabaseUtility.execute'(query)
            WebUI.comment("➡️ Query: ${query}")
            WebUI.comment("⬇️ Result: ${result}")
        }
    }

    WebUI.comment("✅ DB multiple query test completed successfully")
}
catch (Exception e) {
    KeywordUtil.markFailed("❌ Database connection or query failed: " + e.getMessage())
}

@com.kms.katalon.core.annotation.TearDown
def tearDown() {
    CustomKeywords.'katalon.cloudian.utilities.DatabaseUtility.close'()
}