How to Automate Tencent CAPTCHA

Tencent CAPTCHA can block an automated scenario during registration, login, or form submission. This often happens in Selenium, Playwright, and other E2E tests.

If you control the application configuration, use Tencent CAPTCHA test mode. If the test works with a real CAPTCHA or you cannot change the configuration, get the result through Captcha Solver and pass it to the page callback.

The integration of Tencent CAPTCHA with the official Captcha Solver Python SDK is shown below.

Tencent CAPTCHA Data#

You need the following data to create a task:

• websiteURL — the URL of the page with the CAPTCHA;
• appId — the Tencent CAPTCHA identifier;
• clientKey — the access key for the Captcha Solver API.

Tencent CAPTCHA uses appId, not websiteKey. Find the appId in the widget configuration on the page.

For example:

new TencentCaptcha("YOUR_APP_ID", onSolved);

Replace YOUR_APP_ID with the value from the target page configuration.

In the Python SDK, pass the key as the first argument to CaptchaClient. In the examples below, the key is stored in the CAPTCHA_API_KEY environment variable.

Choosing the Task Type#

Captcha Solver supports two Tencent task types:

• TencentTaskProxyless — solve without a client proxy;
• TencentTask — solve through a client proxy.

Use TencentTaskProxyless if the solution does not require a specific proxy.

Use TencentTask if the solve request must be executed through your proxy.

Installing the Python SDK#

The SDK is available in the Captcha Solver Python SDK repository.

Install it directly from GitHub:

pip install git+https://github.com/captcha-solver-api/python-sdk.git

Store your clientKey in the CAPTCHA_API_KEY environment variable.

Linux and macOS:

export CAPTCHA_API_KEY=your_client_key

Windows PowerShell:

$env:CAPTCHA_API_KEY="your_client_key"

Solving Tencent CAPTCHA Without a Proxy#

Use TencentTaskProxyless if a client proxy is not required:

import os
from captcha_sdk import CaptchaClient
from captcha_sdk.tasks import TencentTaskProxyless

client = CaptchaClient(os.environ["CAPTCHA_API_KEY"])

solution = client.solve(
    TencentTaskProxyless(
        websiteURL="https://example.com/register",
        appId="YOUR_APP_ID",
    )
)

print(solution)

Replace:

• https://example.com/register with the URL of the page containing the CAPTCHA;
• YOUR_APP_ID with the appId from the Tencent CAPTCHA configuration.

The solve() method creates a task, checks its status, and returns the result after the solve is complete:

{
    "appid": "...",
    "ret": 0,
    "ticket": "...",
    "randstr": "..."
}

Pass the entire result object to the page callback.

Solving Through a Client Proxy#

If the solve request must use your proxy, create a TencentTask:

import os
from captcha_sdk import CaptchaClient
from captcha_sdk.tasks import TencentTask

client = CaptchaClient(os.environ["CAPTCHA_API_KEY"])

solution = client.solve(
    TencentTask(
        websiteURL="https://example.com/register",
        appId="YOUR_APP_ID",
        proxyType="http",
        proxyAddress="1.2.3.4",
        proxyPort=8080,
        proxyLogin="proxy_user",
        proxyPassword="proxy_password",
    )
)

print(solution)

The following proxy types are supported:

• http;
• socks4;
• socks5.

If the proxy does not require authentication, you can omit proxyLogin and proxyPassword.

Custom Tencent CAPTCHA Script URL#

If the page loads the Tencent CAPTCHA script from a custom URL, specify it in captchaScript:

import os
from captcha_sdk import CaptchaClient
from captcha_sdk.tasks import TencentTaskProxyless

client = CaptchaClient(os.environ["CAPTCHA_API_KEY"])

solution = client.solve(
    TencentTaskProxyless(
        websiteURL="https://example.com/register",
        appId="YOUR_APP_ID",
        captchaScript="https://example.com/custom/TCaptcha.js",
    )
)

print(solution)

Use captchaScript only for pages that actually load Tencent CAPTCHA from a custom URL.

Passing the Result to the Callback#

Captcha Solver returns a Tencent-compatible result object:

const solution = {
  appid: "...",
  ret: 0,
  ticket: "...",
  randstr: "..."
};

Pass this object to the callback specified when initializing the CAPTCHA:

onSolved(solution);

The onSolved callback is only an example. Call the actual callback registered by the page when creating TencentCaptcha.

The input parameter is appId, but the returned object uses the field name appid. This difference is expected.

Captcha Solver returns the result but does not control form submission. The E2E test must pass the object from the Python process to the browser and call the page callback.

The method for passing the result depends on your test infrastructure. For example, Selenium or Playwright can execute JavaScript in the browser and call the callback with the received result.

Integrating with an E2E Test#

For Tencent CAPTCHA, the workflow looks like this:

1. Open the page containing the CAPTCHA.
2. Get the appId from the page configuration.
3. Create TencentTaskProxyless or TencentTask.
4. Call client.solve().
5. Pass the returned object to the page callback.
6. Submit the form.
7. Continue with the test assertions.

Get the solution immediately before submitting the form and pass it to the same page where the CAPTCHA was created.

Asynchronous Solving#

For asynchronous test infrastructure, use AsyncCaptchaClient:

import asyncio
import os
from captcha_sdk import AsyncCaptchaClient
from captcha_sdk.tasks import TencentTaskProxyless

async def solve_tencent():
    client = AsyncCaptchaClient(os.environ["CAPTCHA_API_KEY"])

    try:
        return await client.solve(
            TencentTaskProxyless(
                websiteURL="https://example.com/register",
                appId="YOUR_APP_ID",
            )
        )
    finally:
        await client.aclose()

solution = asyncio.run(solve_tencent())
print(solution)

solve() creates a task, checks its status, and returns the result after the solve is complete.

Checking the Integration#

Before running the test, check the following:

• websiteURL points to the page containing Tencent CAPTCHA;
• appId matches the widget configuration;
• CAPTCHA_API_KEY contains a valid clientKey;
• captchaScript is used only for a custom script URL;
• TencentTask contains proxyType, proxyAddress, and proxyPort;
• the callback receives the entire result object;
• the test passes the result to the same page where the CAPTCHA was created.

Resources#

• Captcha Solver Python SDK
• Synchronous Tencent example
• Asynchronous Tencent example
• Tencent CAPTCHA Documentation
• The repository for Tencent CAPTCHA automation

Summary#

To automate Tencent CAPTCHA, use one of two task types:

• TencentTaskProxyless — if a client proxy is not required;
• TencentTask — if the solve must be performed through your proxy.

Pass websiteURL and appId to the task, call client.solve(), and pass the returned object to the page callback.

For asynchronous scenarios, use AsyncCaptchaClient.

If the page uses a custom Tencent CAPTCHA script URL, specify it with captchaScript.