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
  • Files: src/**/*.test.ts, extensions/**/*.test.ts
  • Scope:
    • Pure unit tests
    • In-process integration tests
    • ज्ञात bugs के लिए deterministic regressions
  • Expectations:
    • CI में चलता है
    • कोई real keys आवश्यक नहीं
    • तेज़ और stable होना चाहिए

E2E (gateway smoke)

  • Command: pnpm test:e2e
  • Config: vitest.e2e.config.ts
  • Files: src/**/*.e2e.test.ts
  • 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
  • Scope:
    • "क्या यह provider/model वास्तव में आज real creds के साथ काम करता है?"
    • Provider format परिवर्तन, tool-calling quirks, auth issues और rate limit व्यवहार catch करना
  • Expectations:
    • Design द्वारा CI-stable नहीं
    • पैसे खर्च होते हैं / rate limits का उपयोग होता है
    • "सब कुछ" के बजाय narrowed subsets चलाना prefer करें

कौन सा 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 काम करता है।

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

  • Test: src/agents/models.profiles.live.test.ts
  • सक्षम करने का तरीका: pnpm test:live
  • Models select करना: MAYROS_LIVE_MODELS=modern या MAYROS_LIVE_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-6,..."

Layer 2: Gateway + dev agent smoke

  • Test: src/gateway/gateway-models.profiles.live.test.ts
  • सक्षम करने का तरीका: pnpm test:live
  • Models select करना: MAYROS_LIVE_GATEWAY_MODELS=all या specific model list

अनुशंसित live recipes

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

  • Single model, direct:

    • 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

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

Live tests उसी तरह credentials discover करते हैं जैसे CLI करता है:

  • Profile store: ~/.mayros/credentials/ (preferred)
  • Config: ~/.mayros/mayros.json

Regressions जोड़ना (guidance)

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

  • यदि संभव हो तो CI-safe regression जोड़ें (mock/stub provider)
  • यदि यह inherently live-only है, तो live test को narrow रखें और env vars के माध्यम से opt-in करें
  • Bug को catch करने वाली smallest layer को target करना prefer करें