Testing

Mayros में तीन Vitest suites (unit/integration, e2e, live) और Docker runners का एक छोटा सेट है।

यह doc एक "हम कैसे test करते हैं" guide है:

  • प्रत्येक suite क्या cover करता है (और जानबूझकर क्या नहीं करता)
  • सामान्य workflows (local, pre-push, debugging) के लिए कौन से commands चलाएं
  • Live tests credentials कैसे discover करते हैं और models/providers कैसे select करते हैं
  • Real-world model/provider issues के लिए regressions कैसे जोड़ें

Quick start

अधिकांश दिन:

  • Full gate (push से पहले अपेक्षित): pnpm build && pnpm check && pnpm test

जब आप tests को छूते हैं या अतिरिक्त confidence चाहते हैं:

  • Coverage gate: pnpm test:coverage
  • E2E suite: pnpm test:e2e

जब real providers/models को debug करना हो (real creds की आवश्यकता है):

  • Live suite (models + gateway tool/image probes): pnpm test:live

सुझाव: जब आपको केवल एक failing case की आवश्यकता हो, तो नीचे described allowlist env vars के माध्यम से live tests को narrow करना prefer करें।

Test suites (क्या कहां चलता है)

Suites को "बढ़ती realism" (और बढ़ती flakiness/cost) के रूप में सोचें:

Unit / integration (डिफ़ॉल्ट)

  • Command: pnpm test
  • Config: scripts/test-parallel.mjs (vitest.unit.config.ts, vitest.extensions.config.ts, vitest.gateway.config.ts चलाता है)
  • Files: src/**/*.test.ts, extensions/**/*.test.ts
  • Scope:
    • Pure unit tests
    • In-process integration tests (gateway auth, routing, tooling, parsing, config)
    • ज्ञात bugs के लिए deterministic regressions
  • Expectations:
    • CI में चलता है
    • कोई real keys आवश्यक नहीं
    • तेज़ और stable होना चाहिए
  • Pool नोट:
    • Mayros Node 22/23 पर तेज़ unit shards के लिए Vitest vmForks का उपयोग करता है।
    • Node 24+ पर, Mayros Node VM linking errors (ERR_VM_MODULE_LINK_FAILURE / module is already linked) से बचने के लिए स्वचालित रूप से regular forks पर fall back करता है।
    • MAYROS_TEST_VM_FORKS=0 (force forks) या MAYROS_TEST_VM_FORKS=1 (force vmForks) के साथ manually override करें।

E2E (gateway smoke)

  • Command: pnpm test:e2e
  • Config: vitest.e2e.config.ts
  • Files: src/**/*.e2e.test.ts
  • Runtime defaults:
    • तेज़ file startup के लिए Vitest vmForks का उपयोग करता है।
    • Adaptive workers का उपयोग करता है (CI: 2-4, local: 4-8)।
    • Console I/O overhead कम करने के लिए डिफ़ॉल्ट रूप से silent mode में चलता है।
  • उपयोगी overrides:
    • MAYROS_E2E_WORKERS=<n> worker count force करने के लिए (16 पर capped)।
    • MAYROS_E2E_VERBOSE=1 verbose console output पुनः सक्षम करने के लिए।
  • Scope:
    • Multi-instance gateway end-to-end व्यवहार
    • WebSocket/HTTP surfaces, node pairing और heavier networking
  • Expectations:
    • CI में चलता है (जब pipeline में enabled हो)
    • कोई real keys आवश्यक नहीं
    • Unit tests से अधिक moving parts (धीमा हो सकता है)

Live (real providers + real models)

  • Command: pnpm test:live
  • Config: vitest.live.config.ts
  • Files: src/**/*.live.test.ts
  • Default: pnpm test:live द्वारा enabled (MAYROS_LIVE_TEST=1 set करता है)
  • Scope:
    • "क्या यह provider/model वास्तव में आज real creds के साथ काम करता है?"
    • Provider format परिवर्तन, tool-calling quirks, auth issues और rate limit व्यवहार catch करना
  • Expectations:
    • Design द्वारा CI-stable नहीं (real networks, real provider policies, quotas, outages)
    • पैसे खर्च होते हैं / rate limits का उपयोग होता है
    • "सब कुछ" के बजाय narrowed subsets चलाना prefer करें
    • Live runs missing API keys pick करने के लिए ~/.profile source करेंगे
  • API key rotation (provider-विशिष्ट): comma/semicolon format या *_API_KEY_1, *_API_KEY_2 के साथ *_API_KEYS set करें (उदाहरण OPENAI_API_KEYS, ANTHROPIC_API_KEYS, GEMINI_API_KEYS) या MAYROS_LIVE_*_KEY के माध्यम से per-live override; tests rate limit responses पर retry करते हैं।

कौन सा suite चलाना चाहिए?

इस decision table का उपयोग करें:

  • Logic/tests संपादित करना: pnpm test चलाएं (और यदि आपने बहुत कुछ बदला है तो pnpm test:coverage)
  • Gateway networking / WS protocol / pairing छूना: pnpm test:e2e जोड़ें
  • "मेरा bot down है" / provider-विशिष्ट failures / tool calling debug करना: एक narrowed pnpm test:live चलाएं

Live: model smoke (profile keys)

Live tests दो layers में split हैं ताकि हम failures को isolate कर सकें:

  • "Direct model" हमें बताता है कि provider/model दी गई key के साथ बिल्कुल जवाब दे सकता है।
  • "Gateway smoke" हमें बताता है कि उस model के लिए पूर्ण gateway+agent pipeline काम करता है (sessions, history, tools, sandbox policy, आदि)।

Layer 1: Direct model completion (कोई gateway नहीं)

  • Test: src/agents/models.profiles.live.test.ts
  • लक्ष्य:
    • Discovered models enumerate करें
    • Models select करने के लिए getApiKeyForModel का उपयोग करें जिनके लिए आपके पास creds हैं
    • प्रति model एक छोटी completion चलाएं (और जहां आवश्यक हो targeted regressions)
  • सक्षम करने का तरीका:
    • pnpm test:live (या Vitest directly invoke करते समय MAYROS_LIVE_TEST=1)
  • यह suite वास्तव में चलाने के लिए MAYROS_LIVE_MODELS=modern (या all, modern के लिए alias) set करें; अन्यथा यह pnpm test:live को gateway smoke पर focused रखने के लिए skip करता है
  • Models select करने का तरीका:
    • MAYROS_LIVE_MODELS=modern modern allowlist चलाने के लिए
    • MAYROS_LIVE_MODELS=all modern allowlist के लिए alias है
    • या MAYROS_LIVE_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-6,..." (comma allowlist)
  • Providers select करने का तरीका:
    • MAYROS_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli" (comma allowlist)

Layer 2: Gateway + dev agent smoke (जो "@mayros" वास्तव में करता है)

  • Test: src/gateway/gateway-models.profiles.live.test.ts
  • लक्ष्य:
    • एक in-process gateway spin up करें
    • agent:dev:* session बनाएं/patch करें (प्रति run model override)
    • Models-with-keys iterate करें और assert करें:
      • "meaningful" response (कोई tools नहीं)
      • एक real tool invocation काम करता है (read probe)
      • वैकल्पिक अतिरिक्त tool probes (exec+read probe)
      • OpenAI regression paths (tool-call-only → follow-up) काम करते रहें
  • Probe विवरण:
    • read probe: test workspace में एक nonce file लिखता है और agent से इसे read करने और nonce echo करने को कहता है।
    • exec+read probe: test agent से exec-write nonce को temp file में करने, फिर इसे read back करने को कहता है।
    • image probe: test एक generated PNG (cat + randomized code) attach करता है और model से cat <CODE> return करने की expect करता है।
  • सक्षम करने का तरीका:
    • pnpm test:live (या Vitest directly invoke करते समय MAYROS_LIVE_TEST=1)
  • Models select करने का तरीका:
    • Default: modern allowlist
    • MAYROS_LIVE_GATEWAY_MODELS=all modern allowlist के लिए alias है
    • या narrow करने के लिए MAYROS_LIVE_GATEWAY_MODELS="provider/model" (या comma list) set करें

सुझाव: अपनी मशीन पर क्या test कर सकते हैं (और exact provider/model ids) देखने के लिए, चलाएं:

bash
mayros models list
mayros models list --json

Live: Anthropic setup-token smoke

  • Test: src/agents/anthropic.setup-token.live.test.ts
  • लक्ष्य: verify करें कि Claude Code CLI setup-token (या pasted setup-token profile) Anthropic prompt complete कर सकता है।
  • सक्षम करें:
    • pnpm test:live (या MAYROS_LIVE_TEST=1)
    • MAYROS_LIVE_SETUP_TOKEN=1

Live: CLI backend smoke

  • Test: src/gateway/gateway-cli-backend.live.test.ts
  • लक्ष्य: local CLI backend का उपयोग करके Gateway + agent pipeline validate करें।
  • सक्षम करें:
    • pnpm test:live (या MAYROS_LIVE_TEST=1)
    • MAYROS_LIVE_CLI_BACKEND=1

अनुशंसित live recipes

Narrow, explicit allowlists सबसे तेज़ और कम flaky हैं:

  • Single model, direct (कोई gateway नहीं):

    • MAYROS_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts

  • Single model, gateway smoke:

    • MAYROS_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

  • कई providers में tool calling:

    • MAYROS_LIVE_GATEWAY_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

  • Google focus (Gemini API key + Antigravity):

    • Gemini (API key): MAYROS_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
    • Antigravity (OAuth): MAYROS_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

नोट्स:

  • google/... Gemini API (API key) का उपयोग करता है।
  • google-antigravity/... Antigravity OAuth bridge का उपयोग करता है।
  • google-gemini-cli/... आपकी मशीन पर local Gemini CLI का उपयोग करता है (अलग auth + tooling quirks)।

Live: model matrix (हम क्या cover करते हैं)

कोई fixed "CI model list" नहीं है (live opt-in है), लेकिन ये अनुशंसित models हैं जिन्हें keys वाली dev machine पर नियमित रूप से cover करना चाहिए।

Modern smoke set (tool calling + image)

  • OpenAI (non-Codex): openai/gpt-5.2
  • OpenAI Codex: openai-codex/gpt-5.3-codex
  • Anthropic: anthropic/claude-opus-4-6
  • Google (Gemini API): google/gemini-3-pro-preview और google/gemini-3-flash-preview
  • Google (Antigravity): google-antigravity/claude-opus-4-6-thinking
  • Z.AI (GLM): zai/glm-4.7
  • MiniMax: minimax/minimax-m2.1

Credentials (कभी commit न करें)

Live tests उसी तरह credentials discover करते हैं जैसे CLI करता है। व्यावहारिक निहितार्थ:

  • यदि CLI काम करता है, तो live tests को वही keys मिलनी चाहिए।

  • यदि live test "no creds" कहता है, तो उसी तरह debug करें जैसे आप mayros models list / model selection debug करेंगे।

  • Profile store: ~/.mayros/credentials/ (preferred; tests में "profile keys" का मतलब यही है)

  • Config: ~/.mayros/mayros.json (या MAYROS_CONFIG_PATH)

यदि आप env keys पर निर्भर रहना चाहते हैं (जैसे आपके ~/.profile में exported), तो source ~/.profile के बाद local tests चलाएं, या नीचे Docker runners का उपयोग करें (वे container में ~/.profile mount कर सकते हैं)।

Deepgram live (audio transcription)

  • Test: src/media-understanding/providers/deepgram/audio.live.test.ts
  • सक्षम करें: DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts

Docker runners (वैकल्पिक "Linux में काम करता है" checks)

ये repo Docker image के अंदर pnpm test:live चलाते हैं, आपकी local config dir और workspace mount करते हैं (और mount होने पर ~/.profile source करते हैं):

  • Direct models: pnpm test:docker:live-models
  • Gateway + dev agent: pnpm test:docker:live-gateway
  • Onboarding wizard (TTY, full scaffolding): pnpm test:docker:onboard
  • Gateway networking (दो containers, WS auth + health): pnpm test:docker:gateway-network
  • Plugins (custom extension load + registry smoke): pnpm test:docker:plugins

उपयोगी env vars:

  • MAYROS_CONFIG_DIR=... (default: ~/.mayros)
  • MAYROS_WORKSPACE_DIR=... (default: ~/.mayros/workspace)
  • MAYROS_PROFILE_FILE=... (default: ~/.profile)
  • MAYROS_LIVE_GATEWAY_MODELS=... / MAYROS_LIVE_MODELS=... run narrow करने के लिए

Docs sanity

Doc edits के बाद docs checks चलाएं: pnpm docs:list।

Offline regression (CI-safe)

ये real providers के बिना "real pipeline" regressions हैं:

  • Gateway tool calling (mock OpenAI, real gateway + agent loop): src/gateway/gateway.tool-calling.mock-openai.test.ts
  • Gateway wizard (WS wizard.start/wizard.next, config लिखता है + auth enforced): src/gateway/gateway.wizard.e2e.test.ts

Agent reliability evals (skills)

हमारे पास पहले से कुछ CI-safe tests हैं जो "agent reliability evals" की तरह व्यवहार करते हैं:

  • Real gateway + agent loop के माध्यम से mock tool-calling।
  • End-to-end wizard flows जो session wiring और config effects validate करते हैं।

Skills के लिए अभी भी missing है (Skills देखें):

  • Decisioning: जब skills prompt में listed हैं, क्या agent सही skill चुनता है?
  • Compliance: क्या agent उपयोग से पहले SKILL.md पढ़ता है और required steps/args follow करता है?
  • Workflow contracts: multi-turn scenarios जो tool order, session history carryover और sandbox boundaries assert करते हैं।

Regressions जोड़ना (guidance)

जब आप live में discovered एक provider/model issue को fix करते हैं:

  • यदि संभव हो तो CI-safe regression जोड़ें (mock/stub provider, या exact request-shape transformation capture करें)
  • यदि यह inherently live-only है (rate limits, auth policies), तो live test को narrow रखें और env vars के माध्यम से opt-in करें
  • Bug को catch करने वाली smallest layer को target करना prefer करें:
    • provider request conversion/replay bug → direct models test
    • gateway session/history/tool pipeline bug → gateway live smoke या CI-safe gateway mock test