TorkTORK
Tork
All Documentation
CLI Testing Guide

Tork Testing Suite

A comprehensive CLI-driven testing framework for verifying SDK integrations with session-based workflows and automated certifications.

How It Works

The Testing Suite uses a session-based workflow that allows your CLI tools to run tests locally while reporting results to the Tork API for certification.

1
Register
Create a test session
2
Run Tests
Execute tests locally
3
Submit
Report results to API
4
Certify
Get your certificate

API Endpoints

POST/api/v1/testing/register

Register a new test session. Returns a session ID and test token for authentication.

Request
POST /api/v1/testing/register
Content-Type: application/json

{
  "api_key": "tork_prod_xxx",  // optional, for tracking
  "client_id": "my-app-v1",
  "sdk_type": "python",        // python|javascript|go|rust|ruby|java|mcp|docker
  "sdk_version": "2.4.1",
  "platform": {
    "os": "darwin",
    "arch": "arm64",
    "runtime_version": "3.11.5"
  }
}
Response
{
  "session_id": "sess_abc123xyz",
  "test_token": "tok_secret_token_here",
  "status": "active",
  "sdk_type": "python",
  "sdk_version": "2.4.1",
  "test_config": {
    "required_tests": [
      "download.package_available",
      "install.pip_install",
      "connectivity.api_reachable",
      "authentication.api_key_valid",
      "pii_detection.email",
      "pii_detection.phone",
      "pii_detection.ssn",
      "policy.load_policies",
      "policy.evaluate_request"
    ],
    "optional_tests": [...],
    "test_endpoints": { ... },
    "timeout_ms": 30000,
    "retry_count": 3
  },
  "api_base_url": "https://api.tork.ai",
  "started_at": "2026-01-26T10:00:00Z",
  "expires_at": "2026-01-27T10:00:00Z"
}

POST/api/v1/testing/submit

Submit test results from your CLI. Can be called multiple times during a session.

Request
POST /api/v1/testing/submit
Content-Type: application/json

{
  "session_id": "sess_abc123xyz",
  "test_token": "tok_secret_token_here",
  "results": [
    {
      "category": "connectivity",
      "test_name": "api_reachable",
      "status": "pass",          // pass|fail|skip|error
      "duration_ms": 85,
      "details": { "latency": 42 }
    },
    {
      "category": "pii_detection",
      "test_name": "email",
      "status": "pass",
      "duration_ms": 45,
      "details": { "detected": true, "confidence": 0.99 }
    },
    {
      "category": "authentication",
      "test_name": "api_key_valid",
      "status": "fail",
      "duration_ms": 150,
      "error_message": "Invalid API key format"
    }
  ],
  "complete": false  // Set true when all tests are done
}

GET/api/v1/testing/session/:id

Get current session status and results summary.

Response
{
  "session": {
    "id": "sess_abc123xyz",
    "client_id": "my-app-v1",
    "sdk_type": "python",
    "status": "completed",
    "started_at": "2026-01-26T10:00:00Z",
    "completed_at": "2026-01-26T10:01:30Z"
  },
  "summary": {
    "total_tests": 10,
    "passed": 8,
    "failed": 1,
    "skipped": 1,
    "errors": 0,
    "duration_ms": 45000,
    "pass_rate": 80
  },
  "results_by_category": {
    "connectivity": [...],
    "authentication": [...],
    "pii_detection": [...]
  },
  "certification": {
    "id": "cert_xyz789",
    "grade": "B",
    "score": 85,
    "badge_url": "/api/v1/badges/cert_xyz789"
  }
}

POST/api/v1/testing/certify

Request a certification after completing all tests.

Request
POST /api/v1/testing/certify
Content-Type: application/json

{
  "session_id": "sess_abc123xyz",
  "test_token": "tok_secret_token_here"
}
Response
{
  "certification": {
    "id": "cert_xyz789abc",
    "session_id": "sess_abc123xyz",
    "verification_id": "ver_123456",
    "grade": "A",
    "score": 92,
    "total_tests": 10,
    "passed_tests": 9,
    "failed_tests": 1,
    "skipped_tests": 0,
    "badge_url": "/api/v1/badges/ver_123456?type=grade-badge",
    "report_url": "/verify/ver_123456",
    "valid_until": "2026-02-25T10:00:00Z",
    "created_at": "2026-01-26T10:01:30Z"
  },
  "embed_code": {
    "markdown": "[![Tork Verified](https://tork.ai/api/v1/badges/ver_123456?type=grade-badge)](https://tork.ai/verify/ver_123456)",
    "html": "<a href=\"https://tork.ai/verify/ver_123456\"><img src=\"https://tork.ai/api/v1/badges/ver_123456?type=grade-badge\" alt=\"Tork Verified A\"></a>"
  }
}

GET/api/v1/testing/config

Get test configuration for a specific SDK type.

Request
GET /api/v1/testing/config?sdk_type=python

Test Categories

Each SDK is tested across multiple categories. Required tests must pass for certification.

CategoryTestsWeightDescription
downloadpackage_available5%Package availability on registry
installpip_install, import_module15%Installation verification
connectivityapi_reachable, ssl_valid20%API connectivity checks
authenticationapi_key_valid, permissions20%API key validation
pii_detectionemail, phone, ssn, credit_card20%PII detection tests
policyload_policies, evaluate_request15%Policy engine tests
rate_limitingretry_logic, backoff5%Rate limit handling (optional)
webhookdelivery, signature5%Webhook tests (optional)
mcptool_registration, invocation20%MCP protocol tests
frameworklangchain, openai, express5%Framework integrations

Scoring & Grades

Certification grades are based on weighted test scores:

A+
97+
A
90+
B
80+
C
70+
D
60+
F
0+
Scoring Formula
Score = (passed + skipped × 0.5) / total × 100
Skipped tests count as 50% to allow optional tests to be skipped without major penalty.

CLI Implementation Example

Here's how to implement the testing flow in your SDK's CLI tool:

Python Example
import httpx
import platform
from tork import __version__

API_BASE = "https://tork.network"

def run_verification(api_key: str = None):
    # 1. Register session
    session = httpx.post(f"{API_BASE}/api/v1/testing/register", json={
        "api_key": api_key,
        "client_id": f"tork-cli-{platform.node()}",
        "sdk_type": "python",
        "sdk_version": __version__,
        "platform": {
            "os": platform.system().lower(),
            "arch": platform.machine(),
            "runtime_version": platform.python_version()
        }
    }).json()

    session_id = session["session_id"]
    test_token = session["test_token"]
    test_config = session["test_config"]

    print(f"Started test session: {session_id}")

    # 2. Run tests locally
    results = []
    for test in test_config["required_tests"]:
        category, test_name = test.split(".")
        result = run_test(category, test_name)
        results.append(result)

        # Submit results in batches
        if len(results) >= 5:
            submit_results(session_id, test_token, results)
            results = []

    # 3. Submit final results with complete=True
    submit_results(session_id, test_token, results, complete=True)

    # 4. Request certification
    cert = httpx.post(f"{API_BASE}/api/v1/testing/certify", json={
        "session_id": session_id,
        "test_token": test_token
    }).json()

    print(f"\nCertification: Grade {cert['certification']['grade']}")
    print(f"Score: {cert['certification']['score']}/100")
    print(f"Badge: {cert['embed_code']['markdown']}")

    return cert

def submit_results(session_id, test_token, results, complete=False):
    httpx.post(f"{API_BASE}/api/v1/testing/submit", json={
        "session_id": session_id,
        "test_token": test_token,
        "results": results,
        "complete": complete
    })

Session Lifecycle

active
Tests in progress
completed
All tests passed
failed
Some tests failed
expired
Session timed out (24h)

Related

SDK Verification
Quick verification commands for each SDK
CI/CD Integration
Automate testing in your pipelines
Leaderboard
See top verified integrations
Sample Certificate
View a demo verification certificate

Ready to Test?

Install the Tork SDK and run the verification command to get started.

Get Started View API Config