strict-development-rules

Gemini CLI Strict Development Rules

These rules apply strictly to all code modifications and additions within the Gemini CLI project.

Testing Guidelines

• Async/Await: Always use waitFor from packages/cli/src/test-utils/async.ts instead of vi.waitFor for all waitFor calls within packages/cli. NEVER use fixed waits (e.g., await delay(100)). Always use waitFor with a predicate to ensure tests are stable and fast. Using the wrong waitFor can result in flaky tests and act warnings.
• React Testing: Use act to wrap all blocks in tests that change component state. Use render or renderWithProviders from packages/cli/src/test-utils/render.tsx instead of render from ink-testing-library directly. This prevents spurious act warnings. If test cases specify providers directly, consider whether the existing renderWithProviders should be modified.
• Snapshots: Use toMatchSnapshot to verify that rendering works as expected rather than matching against the raw content of the output. When modifying snapshots, verify the changes are intentional and do not hide underlying bugs.
• Parameterized Tests: Use parameterized tests where it reduces duplicated lines. Give the parameters explicit types to ensure the tests are type-safe.
• Mocks Management:
  • Mock critical dependencies (fs, os, child_process) ONLY at the top of the file. Ideally, avoid mocking these dependencies altogether.
  • Reuse existing mocks and fakes rather than creating new ones.
  • Avoid mocking the file system whenever possible. If using the real file system is too difficult, consider writing an integration test instead.
  • Always call vi.restoreAllMocks() in afterEach to prevent test pollution.
  • Use vi.useFakeTimers() for tests involving time-based logic to avoid flakiness.
• Typing in Tests: Avoid using any in tests; prefer proper types or unknown with narrowing.

React Guidelines (packages/cli)