run-tests

name	run_tests
description	Explains how to write and run tests in the jj-view repository, detailing the test suites, their purposes, and how to filter test runs down to single test cases. You must read this before editing or debuggins tests.

Testing in JJ View

This document defines the process for writing, running, and debugging tests in the jj-view repository.

The Test Suites

The repository uses three different test runners for different layers of testing.

1. Unit Tests (Vitest)

Purpose: Fast feedback tests for individual classes and functions in isolation without starting the VS Code Extension Host. Command: pnpm test:unit Location Pattern: src/test/**/*.test.ts (excluding *.integration.test.ts) Key Rules:

• Mock external dependencies, especially vscode (using the createVscodeMock helper) and file system operations.
• CRITICAL: Do NOT mock JjService methods. Always use TestRepo to create a real temporary repository on disk, and interact with it using a real JjService instance. Use TestRepo methods to verify outcomes (e.g., file content, log history) rather than spying on JjService calls.

Filtering: You MUST run individual test cases when writing a new test or debugging a broken test.

• Run a single test case (Recommended): Use the -t flag with the test name (you may also include the filename to narrow it down further).

  pnpm test:unit <filename> -t "<test name>"
  # Example: pnpm test:unit merge-editor.test.ts -t "should open merge editor"
  

• Run a specific test file: Pass part of the filename.

  pnpm test:unit <filename>
  # Example: pnpm test:unit merge-editor
  

2. Integration Tests (VS Code Test Electron)

Purpose: Tests that require the VS Code Extension Host to verify extension activation, command registration, and real VS Code API interactions. Command: pnpm test:integration Location Pattern: src/test/**/*.integration.test.ts Key Rules:

• Must import vscode.
• Uses a temporary workspace on disk.
• Handle async operations carefully as they run in a real environment.
• Use sinon for spying/stubbing internal VS Code commands if necessary (e.g., spying on setContext).

Filtering: You MUST run individual test cases when writing a new test or debugging a broken test.

• Run a specific test file (Recommended for focus): Use the --run flag followed by the path to the compiled test file in the out/ directory.

  pnpm test:integration --run out/test/filename.integration.test.js
  # Example: pnpm test:integration --run out/test/quick-diff.integration.test.js
  

• Run a single test case: Use the --grep flag with the specific test case name or a pattern that uniquely identifies it.

  pnpm test:integration --grep "<test case name>"
  # Example: pnpm test:integration --grep "should register commands"
  

  (Note: vscode-test passes arguments to Mocha under the hood. For pnpm, you can pass these flags directly if they are not picked up by pnpm itself, or use -- to be safe: pnpm test:integration --grep "pattern")

3. End-to-End (E2E) Tests (Playwright)

Purpose: End-to-end testing of the extension's behavior in VS Code, interacting with the real UI to ensure the user perspective functions correctly. Command: pnpm test:e2e (also pnpm test:screenshots for visual regression) Location Pattern: src/test/e2e/**/*.spec.ts Key Rules:

• Use the hoverAndClick helper function to consistently handle inline action buttons.
• Replace manual setTimeout calls with Playwright's native waitForTimeout function.

Filtering: You MUST run individual test cases when writing a new test or debugging a broken test.

• Run a single test case (Required): Use the -g flag for grep. You can also provide the filename to narrow it down further, but just using -g with a unique pattern is often more convenient.

  [!IMPORTANT] Playwright's -g / --grep uses Regular Expressions, not literal strings! If a test name contains special regex characters like parentheses (), brackets [], dots ., or asterisks *, a raw literal match will fail or behave unexpectedly (e.g. (foo) is interpreted as a regex capture group, not literal parentheses).

  To match these correctly:

  1. Use the .* wildcard to bypass the special characters entirely.
  2. Or, escape the special characters with backslashes (e.g. \( and \)).

  When debugging a flaky test, append --repeat-each 5 --max-failures 1 to run it multiple times and fail fast.

  pnpm test:e2e [-g "<test-name-regex>"] [<filename>] [--repeat-each 5 --max-failures 1]
  # Examples using wildcards (Recommended):
  # pnpm test:e2e -g "Compare All Files with Revision.*Arbitrary"
  # pnpm test:e2e -g "Compare File with Revision.*Ancestor"
  #
  # Examples with literal escaping:
  # pnpm test:e2e -g "Compare File with Revision\.\.\. \(Arbitrary\)"
  #
  # Basic examples:
  # pnpm test:e2e -g "Additional Actions"
  # pnpm test:e2e scm.spec.ts -g "squash"
  

• Run a specific test file: Pass the filename.

  pnpm test:e2e <filename>
  # Example: pnpm test:e2e scm.spec.ts
  

• Verbose Logging (Opt-in): If you need to see console.log output from the extension's webview or any page errors in your terminal, prefix the command with VERBOSE=1.

  VERBOSE=1 pnpm test:e2e context-menu.spec.ts -g "New Merge Change"
  

• Configurable Artifacts Output Directory (Direct Image Debugging): By default, Playwright outputs failure screenshots/videos to test-results/ inside the workspace. To view these images directly without copying them to the artifact directory, you can set the PLAYWRIGHT_OUTPUT_DIR environment variable to the agent's current conversation artifact directory:

  PLAYWRIGHT_OUTPUT_DIR=<artifact-directory-path>/test-results pnpm test:e2e <test-arguments>
  

  (Note: You can find the <artifact-directory-path> in the conversation details/metadata, e.g., <appDataDir>/brain/<conversation-id>) This will place failure screenshots directly into your artifact folder, making them instantly available for the view_file tool.

4. Debugging E2E Tests (Automatic Failure Diagnostics)

Purpose: When locators fail in E2E tests, it's often due to the complex, nested structure of VS Code. Playwright is configured to automatically dump the visual and DOM state on failure.

Diagnostic Outputs: Whenever an E2E test fails, the test runner automatically saves two diagnostic files in the output directory:

1. Screenshot: test-failure.png showing the visual editor/workspace state.
2. DOM HTML: test-failure.html containing the complete DOM structure (including shadow roots and iframes).

You can directly read the automatically generated test-failure.html using the view_file tool to inspect selectors and find elements at the time of the failure.

Mandatory Debugging Practice

When writing a new test or investigating a failure:

1. Never run the full test suite over and over.
2. Always apply the filtering commands listed above to restrict execution to the single test case or file you are working on. This drastically speeds up the feedback loop and simplifies debugging output.