Cursor Rules for
Vitest Testing

The Vitest Testing rule provides guidance for writing effective Vitest tests in Next.js applications. It outlines the testing framework setup, common mocking patterns, and best practices to ensure your tests are robust and maintainable.

What this rule does

This rule serves as a reference guide for developers working with Vitest in a Next.js environment. It explains the testing structure, provides code snippets for common mocking scenarios, and offers best practices to follow when writing tests.

Key testing concepts

Testing structure

The rule establishes that Vitest is the chosen testing framework for the project and enforces a specific file organization pattern. Test files should be colocated with the files they're testing. For example, if you have a utility function in dir/format.ts, its corresponding test file should be named dir/format.test.ts.

Common mocking patterns

The rule provides ready-to-use code snippets for frequently needed mocks:

1. Server-Only Mock - A simple mock for the "server-only" package:

vi.mock("server-only", () => ({}));

2. Prisma Mock - A more complex example for mocking database interactions:

import { beforeEach } from "vitest";
import prisma from "@/utils/__mocks__/prisma";

vi.mock("@/utils/prisma");

describe("example", () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it("test", async () => {
    prisma.group.findMany.mockResolvedValue([]);
  });
});

Testing best practices

The rule emphasizes several important testing principles:

• Test independence: Each test should run in isolation without depending on other tests
• Descriptive names: Test names should clearly describe what they're verifying
• External dependency mocking: Avoid hitting real services in unit tests
• Mock cleanup: Reset mocks between tests to prevent test pollution
• Focus on behavior: Test what the code does, not how it does it

Using Vitest Testing in Cursor

This rule is stored in the file vitest-testing.mdc within your project's .cursor/rules directory. Since the rule has a glob pattern of *, it will be automatically attached when working with any file in your project. This means the AI will have access to these testing guidelines whenever you're interacting with it in Cursor.

You can also manually invoke this rule by typing @vitest-testing in the Cmd-K prompt or chat interface if you specifically want to reference these testing guidelines during a conversation with the AI.

This rule is particularly useful when:

• Setting up new test files
• Troubleshooting test-related issues
• Ensuring consistent testing patterns across the team
• Onboarding new developers to the project's testing approach

Usage tips

• Reference this rule when creating new test files to ensure they follow the project's testing conventions
• Use the provided mock examples as templates when setting up tests that require those dependencies
• When reviewing test code, check it against the best practices outlined in this rule
• Share this rule with new team members to quickly bring them up to speed on the project's testing approach

Remember that well-structured tests not only verify your code works as expected but also serve as documentation and facilitate refactoring with confidence.