tests: add external starter mode realtikv harness

tests/realtikvtest/scripts/next-gen/README.md

@@ -61,6 +61,52 @@ Example:
 ./run-tests.sh bazel_addindextest
 ```
 
+### run-starter-tests-with-server.sh
+
+This script runs external starter-mode tests against a real `tidb-server`
+process. It first reuses `bootstrap-test-with-cluster.sh` to start PD, TiKV,
+TiKV-Worker, and MinIO. Then it starts `bin/tidb-server` with
+`deploy-mode = "starter"` and runs Go tests through the MySQL protocol.
+
+The `tidb-server` binary must be built as a next-gen binary before running the
+script:
+
+```bash
+NEXT_GEN=1 make server
+```
+
+Because the script reuses `bootstrap-test-with-cluster.sh`, `bin/pd-server`,
+`bin/tikv-server`, and `bin/tikv-worker` must also be available.
+
+Usage:
+
+```bash
+tests/realtikvtest/scripts/next-gen/run-starter-tests-with-server.sh [<test_suite>] [<timeout>] [<go test args>...]
+```
+
+Arguments:
+- `<test_suite>`: The test suite directory under `./tests/realtikvtest/`
+  (default: `startertest`)
+- `<timeout>`: Optional timeout for the test suite (default: `40m`)
+- `<go test args>`: Optional extra arguments passed to `go test`
+
+Example:
+
+```bash
+tests/realtikvtest/scripts/next-gen/run-starter-tests-with-server.sh startertest 40m -run TestExternalStarterSysVarContracts
+```
+
+Useful environment variables:
+- `TIDB_SERVER_BIN`: Path to the next-gen `tidb-server` binary
+  (default: `bin/tidb-server`)
+- `STARTER_MAX_ALLOWED_PACKET`: Starter `max-allowed-packet` config used by
+  the external server (default: `8192`)
+- `STARTER_TIKV_WORKER_URL`: Starter `tikv-worker-url` config used by the
+  external server (default: `localhost:19000`)
+- `STARTER_TIDB_PORT` / `STARTER_TIDB_STATUS_PORT`: Preferred starting ports
+  for the SQL and status listeners (defaults: `4000` / `10080`; the script
+  advances to the next available port if needed)
+
 ## Configuration Files
 
 The test cluster uses configuration files from `tests/realtikvtest/configs/next-gen/`:

tests/realtikvtest/scripts/next-gen/run-starter-tests-with-server.sh

@@ -0,0 +1,158 @@
+#! /usr/bin/env bash
+#
+# Copyright 2026 PingCAP, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -euo pipefail
+
+starter_data_dir=""
+starter_tidb_pid=""
+
+function find_available_port() {
+    local port="$1"
+    while [[ "${port}" -lt 65536 ]]; do
+        if ! lsof -nP -iTCP:"${port}" -sTCP:LISTEN >/dev/null 2>&1; then
+            echo "${port}"
+            return 0
+        fi
+        port=$((port + 1))
+    done
+    echo "no available port found from $1" >&2
+    return 1
+}
+
+function cleanup_tidb_server() {
+    if [[ -n "${starter_tidb_pid:-}" ]]; then
+        if kill -0 "${starter_tidb_pid}" >/dev/null 2>&1; then
+            kill -TERM "${starter_tidb_pid}" >/dev/null 2>&1 || true
+        fi
+        wait "${starter_tidb_pid}" >/dev/null 2>&1 || true
+        starter_tidb_pid=""
+    fi
+    if [[ -n "${starter_data_dir:-}" && -d "${starter_data_dir}" ]]; then
+        rm -rf -- "${starter_data_dir}"
+        starter_data_dir=""
+    fi
+}
+
+function wait_for_tidb_server() {
+    local status_url="$1"
+    local tidb_pid="$2"
+    local log_file="$3"
+    local stdout_log_file="$4"
+
+    for _ in {1..60}; do
+        if curl -sf "${status_url}/status" >/dev/null 2>&1; then
+            return 0
+        fi
+        if ! kill -0 "${tidb_pid}" >/dev/null 2>&1; then
+            echo "tidb-server exited before becoming ready. Log tail:" >&2
+            tail -200 "${log_file}" >&2 || true
+            tail -200 "${stdout_log_file}" >&2 || true
+            return 1
+        fi
+        sleep 1
+    done
+
+    echo "timed out waiting for tidb-server. Log tail:" >&2
+    tail -200 "${log_file}" >&2 || true
+    tail -200 "${stdout_log_file}" >&2 || true
+    return 1
+}
+
+function run_under_cluster() {
+    local test_suite="${1:-startertest}"
+    local suite_timeout="${2:-40m}"
+    shift || true
+    shift || true
+    local extra_go_test_args=("$@")
+
+    local self_dir
+    self_dir="$(realpath "$(dirname "${BASH_SOURCE[0]}")")"
+    local repo_root
+    repo_root="$(realpath "${self_dir}/../../../..")"
+    cd "${repo_root}"
+
+    local tidb_server_bin="${TIDB_SERVER_BIN:-bin/tidb-server}"
+    if [[ ! -x "${tidb_server_bin}" ]]; then
+        echo "tidb-server binary '${tidb_server_bin}' does not exist or is not executable." >&2
+        echo "Build a next-gen TiDB server first, for example: NEXT_GEN=1 make server" >&2
+        return 1
+    fi
+
+    local max_allowed_packet="${STARTER_MAX_ALLOWED_PACKET:-8192}"
+    starter_data_dir="$(mktemp -d)"
+    local config_file="${starter_data_dir}/starter.toml"
+    local log_file="${starter_data_dir}/tidb.log"
+    local stdout_log_file="${starter_data_dir}/tidb-stdout.log"
+    local tidb_port
+    tidb_port="$(find_available_port "${STARTER_TIDB_PORT:-4000}")"
+    local status_port
+    status_port="$(find_available_port "${STARTER_TIDB_STATUS_PORT:-10080}")"
+    if [[ "${status_port}" == "${tidb_port}" ]]; then
+        status_port="$(find_available_port "$((status_port + 1))")"
+    fi
+    local pd_endpoints="${STARTER_PD_ENDPOINTS:-127.0.0.1:2379,127.0.0.1:2382,127.0.0.1:2384}"
+    local tikv_worker_url="${STARTER_TIKV_WORKER_URL:-localhost:19000}"
+
+    cat > "${config_file}" <<EOF
+deploy-mode = "starter"
+max-allowed-packet = ${max_allowed_packet}
+tikv-worker-url = "${tikv_worker_url}"
+EOF
+
+    echo "Starting external starter tidb-server on port ${tidb_port}, status port ${status_port}, log file ${log_file}"
+    "${tidb_server_bin}" \
+        -P "${tidb_port}" \
+        -status "${status_port}" \
+        -host "127.0.0.1" \
+        -advertise-address "127.0.0.1" \
+        -status-host "127.0.0.1" \
+        -store tikv \
+        -path "${pd_endpoints}" \
+        -config "${config_file}" \
+        -keyspace-name SYSTEM \
+        -tidb-service-scope dxf_service \
+        -log-file "${log_file}" > "${stdout_log_file}" 2>&1 &
+    starter_tidb_pid="$!"
+    trap cleanup_tidb_server EXIT
+
+    local status_url="http://127.0.0.1:${status_port}"
+    wait_for_tidb_server "${status_url}" "${starter_tidb_pid}" "${log_file}" "${stdout_log_file}"
+
+    export TIDB_STARTER_TEST_DSN="root@tcp(127.0.0.1:${tidb_port})/?timeout=5s&readTimeout=30s&writeTimeout=30s&multiStatements=true"
+    export TIDB_STARTER_STATUS_URL="${status_url}"
+    export TIDB_STARTER_MAX_ALLOWED_PACKET="${max_allowed_packet}"
+    export TIDB_STARTER_TIKV_WORKER_URL="${tikv_worker_url}"
+
+    echo "Running external starter tests: ./tests/realtikvtest/${test_suite}"
+    NEXT_GEN=1 go test "./tests/realtikvtest/${test_suite}" -v --tags=intest,nextgen -timeout "${suite_timeout}" "${extra_go_test_args[@]}"
+}
+
+function main() {
+    local self_dir
+    self_dir="$(realpath "$(dirname "${BASH_SOURCE[0]}")")"
+    local repo_root
+    repo_root="$(realpath "${self_dir}/../../../..")"
+    cd "${repo_root}"
+
+    "${self_dir}/bootstrap-test-with-cluster.sh" "${self_dir}/run-starter-tests-with-server.sh" --under-cluster "$@"
+}
+
+if [[ "${1:-}" == "--under-cluster" ]]; then
+    shift
+    run_under_cluster "$@"
+else
+    main "$@"
+fi

tests/realtikvtest/startertest/BUILD.bazel

@@ -0,0 +1,13 @@
+load("@io_bazel_rules_go//go:def.bzl", "go_test")
+
+go_test(
+    name = "startertest_test",
+    timeout = "moderate",
+    srcs = ["starter_external_test.go"],
+    flaky = True,
+    shard_count = 4,
+    deps = [
+        "@com_github_go_sql_driver_mysql//:mysql",
+        "@com_github_stretchr_testify//require",
+    ],
+)