Claude Code के साथ Vitest उन्नत परीक्षण गाइड

यह Vitest प्रवाह किस समस्या को हल करता है

Claude Code से केवल “Vitest परीक्षण जोड़ो” कहना पर्याप्त नहीं है। ऐसे परीक्षण स्थानीय मशीन पर पास हो सकते हैं, लेकिन समय, DOM, बाहरी API या सीआई में टूट सकते हैं। इस गाइड में हम जोखिम वाले हिस्सों को एक व्यावहारिक प्रवाह में रखते हैं: निर्भरता के बदले मॉक, समय नियंत्रित करने के लिए फेक टाइमर, अनपरीक्षित शाखाएं खोजने के लिए कवरेज, DOM संरचना के लिए jsdom, छोटे रेंडरिंग अनुबंध के लिए स्नैपशॉट, और सीआई में साफ समाप्त होने वाली कमांड।

22 जुलाई 2026 को इस लेख को आधिकारिक Vitest CLI गाइड, watch configuration और Vitest 4 migration guide से मिलाया गया। Vitest 4 के लिए Vite 6 या नया और Node 20 या नया चाहिए। सीआई या non-interactive terminal में vitest अपने आप एक बार चलने वाले मोड में जाता है; फिर भी vitest run script का उद्देश्य स्पष्ट रखता है।

Claude Code को केवल लक्ष्य न दें। यह भी बताएं कि कौन सी सीमा नकली बनेगी, घड़ी स्थिर रहेगी या नहीं, jsdom पर्याप्त है या नहीं, और कौन सी कमांड प्रमाण देगी। आगे पढ़ने के लिए Claude Code परीक्षण रणनीति, MSW API मॉक गाइड और Playwright E2E परीक्षण उपयोगी हैं।

flowchart TD
  A["विनिर्देश: सफलता और विफलता"] --> B["Vitest config: node/jsdom/coverage"]
  B --> C["यूनिट: शुद्ध लॉजिक और API सीमा"]
  B --> D["समय: फेक टाइमर और स्थिर Date"]
  B --> E["DOM: jsdom और स्नैपशॉट"]
  C --> F["CI: vitest run --coverage"]
  D --> F
  E --> F

पहले स्थिर कॉन्फिगरेशन बनाएं

Vitest, V8 कवरेज प्रदाता, jsdom और TypeScript स्थापित करें। Vite ऐप में कॉन्फिग साझा हो सकता है, लेकिन अलग vitest.config.ts रखने से Claude Code और समीक्षक दोनों को इरादा साफ दिखता है।

npm install -D vitest @vitest/coverage-v8 jsdom typescript

{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run",
    "coverage": "vitest run --coverage"
  }
}

// vitest.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    environment: "node",
    globals: false,
    restoreMocks: true,
    coverage: {
      provider: "v8",
      reporter: ["text", "html"],
      include: ["src/**/*.{ts,tsx}"],
      exclude: ["src/**/*.d.ts", "src/**/*.test.{ts,tsx}", "src/test/**"],
      thresholds: {
        lines: 80,
        functions: 80,
        branches: 75,
        statements: 80,
      },
    },
  },
});

globals: false रखने से describe और expect के स्रोत स्पष्ट रहते हैं। restoreMocks: true मॉक रिसाव घटाता है, पर फेक टाइमर और DOM सफाई फिर भी अलग से करनी होती है।

उपयोग मामला 1: API सीमा को मॉक करना

यूनिट परीक्षण को असली ऑर्डर, भुगतान या उपयोगकर्ता API नहीं बुलानी चाहिए। अपने नियंत्रण वाले अनुबंध की जांच करें: पथ, अनुरोध शरीर, इनपुट मान्यता और त्रुटि रूपांतरण।

// src/orders.ts
export type ApiClient = {
  post<T>(path: string, body: unknown): Promise<T>;
};

export class OrderError extends Error {
  constructor(message = "Order request failed") {
    super(message);
    this.name = "OrderError";
  }
}

type OrderInput = {
  sku: string;
  quantity: number;
};

type OrderResponse = {
  id: string;
  status: "accepted" | "queued";
};

export async function createOrder(api: ApiClient, input: OrderInput) {
  if (input.quantity < 1) {
    throw new OrderError("Quantity must be at least 1");
  }

  try {
    return await api.post<OrderResponse>("/orders", input);
  } catch {
    throw new OrderError("Order API failed");
  }
}

// src/orders.test.ts
import { describe, expect, it, vi } from "vitest";
import { createOrder, type ApiClient, OrderError } from "./orders";

describe("createOrder", () => {
  it("posts the order payload to the API", async () => {
    const api: ApiClient = {
      post: vi.fn().mockResolvedValue({ id: "ord_1", status: "accepted" }),
    };

    await expect(createOrder(api, { sku: "book-1", quantity: 2 })).resolves.toEqual({
      id: "ord_1",
      status: "accepted",
    });
    expect(api.post).toHaveBeenCalledWith("/orders", { sku: "book-1", quantity: 2 });
  });

  it("rejects invalid quantity before calling the API", async () => {
    const api: ApiClient = { post: vi.fn() };

    await expect(createOrder(api, { sku: "book-1", quantity: 0 })).rejects.toBeInstanceOf(
      OrderError,
    );
    expect(api.post).not.toHaveBeenCalled();
  });

  it("wraps transport errors in a domain error", async () => {
    const api: ApiClient = {
      post: vi.fn().mockRejectedValue(new Error("ECONNRESET")),
    };

    await expect(createOrder(api, { sku: "book-1", quantity: 1 })).rejects.toThrow(
      "Order API failed",
    );
  });
});

यह निर्भरता-प्रवेश शैली पूरे मॉड्यूल को बदलने से सरल होती है। vi.mock() उपयोगी है, लेकिन Vitest उसे import से पहले ऊपर ले जाता है। इसलिए गलत आरंभिक क्रम शुरुआती लोगों और AI से बने परीक्षणों को भ्रमित कर सकता है।

उपयोग मामला 2: फेक टाइमर से अवधि स्थिर करना

ट्रायल अवधि, पुनः प्रयास, सूचना और डिबाउंस परीक्षण असली समय पर निर्भर हों तो धीमे और अस्थिर हो जाते हैं। Vitest setTimeout, setInterval और सिस्टम तारीख को नियंत्रित कर सकता है।

// src/trial.ts
const DAY_MS = 24 * 60 * 60 * 1000;

export function getTrialEndsAt(days = 7) {
  return new Date(Date.now() + days * DAY_MS).toISOString();
}

export function scheduleTrialReminder(send: () => void, days = 7) {
  return setTimeout(send, days * DAY_MS);
}

// src/trial.test.ts
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { getTrialEndsAt, scheduleTrialReminder } from "./trial";

describe("trial reminder", () => {
  beforeEach(() => {
    vi.useFakeTimers();
    vi.setSystemTime(new Date("2026-06-03T00:00:00.000Z"));
  });

  afterEach(() => {
    vi.useRealTimers();
  });

  it("calculates the trial end date from the fixed clock", () => {
    expect(getTrialEndsAt()).toBe("2026-06-10T00:00:00.000Z");
  });

  it("runs the reminder after the configured number of days", () => {
    const send = vi.fn();
    const timer = scheduleTrialReminder(send, 3);

    vi.advanceTimersByTime(3 * 24 * 60 * 60 * 1000 - 1);
    expect(send).not.toHaveBeenCalled();

    vi.advanceTimersByTime(1);
    expect(send).toHaveBeenCalledTimes(1);
    clearTimeout(timer);
  });
});

सबसे आम गलती vi.useRealTimers() भूलना है। एक फाइल की नकली घड़ी दूसरी फाइल को अनियमित रूप से गिरा सकती है। Promise होने पर await भी जरूरी है। तारीख और समय क्षेत्र की सीमाओं के लिए Claude Code तारीख और समय गाइड देखें।

उपयोग मामला 3: jsdom और स्नैपशॉट से DOM अनुबंध बचाना

jsdom Node में ब्राउज़र DOM API की नकल करता है। यह संरचना, पाठ और पहुंच-योग्यता गुणों के लिए अच्छा है। लेआउट, वास्तविक फोकस, Canvas और दृश्य अंतर के लिए यह असली ब्राउज़र का विकल्प नहीं है।

// src/notice.ts
export function renderNotice(target: HTMLElement, message: string) {
  target.innerHTML = "";

  const notice = document.createElement("p");
  notice.setAttribute("role", "status");
  notice.dataset.testid = "notice";
  notice.textContent = message;

  target.append(notice);
  return notice;
}

// src/notice.test.ts
// @vitest-environment jsdom
import { afterEach, describe, expect, it } from "vitest";
import { renderNotice } from "./notice";

afterEach(() => {
  document.body.innerHTML = "";
});

describe("renderNotice", () => {
  it("renders an accessible status message", () => {
    document.body.innerHTML = '<div id="app"></div>';
    const target = document.querySelector<HTMLDivElement>("#app");
    if (!target) throw new Error("missing #app");

    const notice = renderNotice(target, "सहेजा गया");

    expect(notice.getAttribute("role")).toBe("status");
    expect(notice.textContent).toBe("सहेजा गया");
    expect({
      html: document.body.innerHTML,
      text: notice.textContent,
    }).toMatchInlineSnapshot(`
      {
        "html": "<div id=\\"app\\"><p role=\\"status\\" data-testid=\\"notice\\">सहेजा गया</p></div>",
        "text": "सहेजा गया",
      }
    `);
  });
});

स्नैपशॉट छोटा होना चाहिए। महत्वपूर्ण गुणों को सीधे expect से जांचें, और केवल छोटी संरचना को स्नैपशॉट में रखें। वास्तविक ब्राउज़र व्यवहार के लिए Playwright बेहतर है।

कवरेज और सीआई को गुणवत्ता द्वार बनाना

कवरेज का उद्देश्य प्रतिशत बढ़ाना नहीं, बल्कि अनपरीक्षित शाखाएं दिखाना है। Vitest V8 और Istanbul कवरेज प्रदाता बताता है, और V8 डिफ़ॉल्ट है। coverage.include स्पष्ट रखें, नहीं तो ऐसे नए फाइल छूट सकते हैं जिन्हें कोई परीक्षण import नहीं करता।

# .github/workflows/vitest.yml
name: vitest

on:
  pull_request:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run test:run
      - run: npm run coverage

सीआई में vitest run साफ तौर पर लिखें। vitest केवल तब watch करता है जब सीआई false हो और terminal interactive हो; अन्यथा यह एक बार चलता है। lint-staged जैसे interactive tool में बदली dependencies के लिए vitest related --run उपयोग करें। पूरी पाइपलाइन के लिए Claude Code CI/CD सेटअप पढ़ें।

Claude Code के लिए उपयोगी प्रॉम्प्ट

src/orders.ts के लिए Vitest परीक्षण जोड़ें।
सिर्फ createOrder को परीक्षण में लें।
बाहरी API को vi.fn() से मॉक करें; वास्तविक HTTP कॉल न करें।
सफलता, अमान्य इनपुट और परिवहन विफलता के तीन मामले शामिल करें।
जब तक कोड मांग न करे, फेक टाइमर या jsdom का उपयोग न करें।
संपादन के बाद अपेक्षित npm run test:run कमांड और बचे जोखिम बताएं।

यह प्रॉम्प्ट दायरा, नकली सीमा, आवश्यक विफलताएं और प्रमाण कमांड साथ देता है। ऐसी ही नीति CLAUDE.md सर्वोत्तम अभ्यास में रखी जा सकती है।

तीन उपयोग के मामले

उपयोग मामला 1: ऑर्डर या साइनअप फॉर्म। गलत पथ या अनुरोध शरीर खरीद को रोक सकता है। Claude Code vi.fn() के साथ सफलता, अमान्य इनपुट और परिवहन विफलता के API सीमा परीक्षण लिख सकता है; भुगतान, बिलिंग, स्टॉक और ग्राहक डेटा नियम मनुष्य को मंजूर करने चाहिए।

उपयोग मामला 2: ट्रायल, अपॉइंटमेंट या नवीनीकरण रिमाइंडर। Claude Code Date स्थिर कर सकता है, फेक टाइमर आगे बढ़ा सकता है और callback एक बार चलता है यह साबित कर सकता है। समय क्षेत्र, कार्य दिवस, वास्तविक email या SMS भेजना और बिलिंग प्रभाव मनुष्य जांचता है।

उपयोग मामला 3: सेव सूचना, मान्यता संदेश या admin banner जैसे छोटे DOM अनुबंध। Claude Code jsdom से text, role और छोटा snapshot जांच सकता है। असली browser व्यवहार, focus, visual regression और ग्राहक को दिखने वाला copy मनुष्य मंजूर करता है।

Claude Code को क्या दें और मनुष्य क्या मंजूर करे

क्षेत्र	Claude Code को दिया जा सकता है	मनुष्य की मंजूरी जरूरी
परीक्षण कोड	मॉक, फेक टाइमर, jsdom assertion और कवरेज कमांड	जांचें कि assertion उत्पाद व्यवहार कमजोर नहीं कर रहे
सीआई	vitest run और vitest run --coverage gate सुझाना	अनिवार्य checks, महंगे runner या production deploy
डेटा	ord_1 और book-1 जैसे synthetic ID	ग्राहक डेटा, secrets, API keys और payment ID
ब्राउज़र	DOM अनुबंध Vitest में रखना	Playwright या manual review से असली flow जांचना

सामान्य गलतियाँ और सुधार

विफलता	लक्षण	सुधार
मॉक वापस नहीं किए	कॉल संख्या या नकली कार्यान्वयन अगले परीक्षण में चला गया	जरूरत के अनुसार restoreMocks, vi.clearAllMocks() या vi.restoreAllMocks()
फेक टाइमर वापस नहीं किए	दूसरी फाइल के समय परीक्षण अनियमित रूप से गिरते हैं	afterEach में vi.useRealTimers()
jsdom को असली ब्राउज़र मानना	CSS, लेआउट, चित्र या Canvas अलग दिखते हैं	DOM अनुबंध Vitest में, ब्राउज़र व्यवहार Playwright में
स्नैपशॉट बहुत बड़ा	समीक्षा में अनावश्यक अंतर भर जाते हैं	केवल छोटी संरचना सहेजें
coverage.include नहीं	अनपरीक्षित फाइलें अदृश्य रहती हैं	src/**/*.{ts,tsx} स्पष्ट करें
असिंक्रोनस को नहीं रोका	झूठी सफलता मिलती है	await expect(promise).resolves या rejects
interactive runner watch mode में गया	process बदलाव की प्रतीक्षा करता है	vitest run; बदली files के लिए vitest related --run

सुधार का मतलब किसी भी तरह हरा करना नहीं है। परीक्षण गिरने पर पूरा error चिपकाएं, Claude Code से कहें कि assertion न हटाए, और पहले implementation या mock setup सुधारे। सुरक्षा, production, billing और ग्राहक डेटा वाले बदलाव तब तक लागू न करें जब तक मनुष्य diff न देख ले।

अपने repository में यही review नियम लगाने के लिए ClaudeCodeLab के व्यावहारिक टेम्पलेट परीक्षण मानक, समीक्षा प्रॉम्प्ट और सीआई द्वार देते हैं।

वास्तविक जांच का परिणाम

22 जुलाई 2026 को TypeScript उदाहरणों को अस्थायी project में निकाला गया और Node v24.14.1 तथा Vitest 4.1.10 से चलाया गया। vitest run और vitest run --coverage में API सीमा, module mock, स्थिर घड़ी, timer सीमा, DOM attributes और inline snapshot वाले 4 files और 7 tests सफल रहे। Coverage statements 94.73%, branches 100%, functions 85.71% और lines 94.73% रही। Mailer mock था, इसलिए कोई असली ईमेल या production API call नहीं हुई।