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.

Create a test session

Run Tests

Execute tests locally

Submit

Report results to API

Certify

Get your certificate

API Endpoints

POST/api/v1/testing/register

Request

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

{
  "api_key": "tork_live_xxx",  // optional, for tracking
  "client_id": "my-app-v1",
  "sdk_type": "python",        // python|javascript|go|rust|ruby|java|mcp|docker
  "sdk_version": "0.26.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": "0.26.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://tork.network",
  "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": {          // null until POST /api/v1/testing/certify has run
    "id": "cert_xyz789",
    "grade": "B",
    "score": 85,
    "badge_url": "/api/v1/badges/ver_123456?type=grade-badge",
    "report_url": "/verify/ver_123456",
    "valid_until": "2026-02-25T10:00:00Z"
  }
}

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.network/api/v1/badges/ver_123456?type=grade-badge)](https://tork.network/verify/ver_123456)",
    "html": "<a href=\"https://tork.network/verify/ver_123456\"><img src=\"https://tork.network/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. Which tests are required and which are optional is returned per SDK by GET /api/v1/testing/config?sdk_type=…. Scoring is unweighted (see below).

Category	Tests	Description
download	package_available, image_available	Package or image availability on the registry
install	pip_install, npm_install, go_get, cargo_add, gem_install, maven_add, docker_pull	Installation verification (one per SDK)
connectivity	api_reachable, mcp_server_reachable, container_starts	API connectivity checks
authentication	api_key_valid	API key validation
pii_detection	email, phone, ssn, credit_card, address	PII detection tests (credit_card and address are optional)
policy	load_policies, evaluate_request	Policy engine tests
rate_limiting	retry_logic	Rate limit handling (optional)
webhook	delivery	Webhook tests (optional)
mcp	tool_registration, tool_invocation, resource_access, prompt_handling, policy_check, audit_logging	MCP protocol tests (mcp SDK type)
framework	langchain, openai, express, nextjs, rails, spring	Framework integrations (optional, per SDK)

Scoring & Grades

Certification grades are based on the test score:

A+

97+

90+

80+

70+

60+

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_governance 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
    })