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

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

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

3 जून 2026 को मैंने Vitest के आधिकारिक दस्तावेज देखे: Getting Started, Mocking, Timers, Dates, Test Environment, Coverage, Snapshot और CLI। Vitest 4 के दस्तावेज निगरानी मोड और vitest run में अंतर बताते हैं। सीआई में यही अंतर काम को अटकने से बचाता है।

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 कुछ वातावरणों में निगरानी मोड में जा सकता है। पूरी पाइपलाइन के लिए Claude Code CI/CD सेटअप पढ़ें।

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

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

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

सामान्य विफलताएं

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

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

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

अंतिम रूप में तीन कॉपी करने योग्य Vitest उपयोग मामले बने: API सीमा परीक्षण, स्थिर समय परीक्षण, और jsdom रेंडरिंग परीक्षण छोटे स्नैपशॉट के साथ। प्रकाशित करने से पहले आधिकारिक Vitest दस्तावेज, अंदरूनी लिंक, बाहरी लिंक, कोड फेंस, updatedDate, कवरेज सेटिंग और सीआई में vitest run का उपयोग फिर से जांचा गया।