Grove: Run and Debug Tests

Begin your first response with: [grove-run-647f2a26]

Run code example tests and provide actionable diagnosis of any failures.

Do NOT use when:

• The user wants to create a new example or test → use /grove-create or /grove-test
• The user wants to convert untested code into Grove → use /grove-migrate
• The user needs to set up their environment first (no .env file, deps not installed) → use /grove-setup
• The user wants to audit test coverage or upgrade dependencies → use /grove-maintain

Step 0: Check for Extension Handoff

Before Step 1, check whether the Grove VS Code extension has dropped a handoff file at .claude/grove-handoff.json in the workspace root. If the file exists and skill equals grove-run:

1. Delete the handoff file immediately after reading it. The file is single-use; leaving it in place causes the next invocation to re-trigger on stale context.

2. Check the payload before using it. If a check fails, surface what's wrong to the writer, recommend they file an issue for the Grove VS Code extension, and ask whether to proceed without the handoff. If they confirm, fall through to Step 1.

   • Version check: version must equal 1. A higher number means the extension is ahead of this skill. Example message:

     Found a Grove extension handoff with version: {n}, but this skill only understands version 1. The extension is likely newer than the skill. Proceed without the handoff?

   • Shape check: the file must be valid JSON and contain the top-level fields version, skill, trigger, context. The context object must contain the fields listed in the schema for the matching trigger below. Example message:

     The Grove extension handoff at .claude/grove-handoff.json is malformed: {brief reason, e.g. "missing context.testFile"}. This is likely an extension bug — please file an issue. Proceed without the handoff?

   The JSON block below is the expected payload schema, not just an illustrative sample. Use it as the reference for what fields must be present:

   {
     "version": 1,
     "skill": "grove-run",
     "trigger": "test-failure",
     "timestamp": "ISO-8601",
     "workspaceRoot": "/absolute/path",
     "context": {
       "testFile": "relative/path/to/file.test.ts",
       "testName": "describe > it text",
       "testNamePattern": "describe it text",
       "line": 42,
       "errorMessage": "captured failure output (may be truncated)",
       "duration": 1234,
       "projectPath": "code-example-tests/javascript/driver"
     }
   }

3. Treat the context fields as pre-filled answers — skip Step 1 (scope/language) and Step 2 (suite lookup). projectPath is the driver directory; testFile and testNamePattern are the inputs for Step 3.

4. Guard against stale handoffs: verify context.testFile still exists on disk (the writer may have renamed it or switched branches between the CodeLens click and skill invocation). If it doesn't exist, report what was expected, fall through to Step 1, and let the writer disambiguate.

5. Echo one line confirming what was received, e.g.: Got handoff from extension: re-running "{testName}" in {projectPath}.

6. Proceed to Step 3 to re-run the single failing test (fresh output is more reliable than the captured errorMessage), then Step 4 to diagnose. If the re-run now passes, report that and stop.

If the handoff file is absent or skill doesn't match, proceed normally from Step 1.

Step 1: Determine Scope and Language

Parse the user's request to identify:

1. What to run: A specific test file, a topic directory, or all tests
2. Language: Infer from the file path, or ask if ambiguous

If the user provides a path, use it directly. If they say "run the tests" with no qualifier, ask which language/suite or default to running all tests in the language directory they're currently working in.

Step 2: Locate the Test Suite

Map the language to its driver directory under code-example-tests/:

Out of scope for these skills: java/driver-reactive/ (comparison-library tests only), go/atlas-sdk/, and openapi/ (OpenAPI validation) — use each project's README.

Read the language's CLAUDE.md for formatting, snip, and env setup details.

Step 3: Run the Tests

This is the canonical source for test commands. Other grove skills reference these patterns — keep them up to date here.

Full pipeline (format → test → snip)

Each main suite provides run-tests.js, which runs preflight connectivity checks, formats code, runs tests, and extracts snippets. Prefer this when the writer wants the full local CI workflow:

cd code-example-tests/{driver-dir} && node run-tests.js

Pass --no-snip to skip snippet extraction. Repo-wide: node code-example-tests/run-all-tests.js.

JavaScript (Jest)

From code-example-tests/javascript/driver/:

npm test                                    # All tests
npm test -- -t '{describe or it text}'      # Single test by name
npx jest tests/path/file.test.js            # Single file (after .env is loaded)

npm test loads .env and sets Jest flags via package.json. Do not call npx jest for ad-hoc runs without loading CONNECTION_STRING — use npm test -- to pass arguments through.

Python (unittest)

From code-example-tests/python/pymongo/:

./venv/bin/python -m unittest discover tests_package
./venv/bin/python -m unittest tests_package/topic/test_file.py
./venv/bin/python -m unittest tests_package/topic/test_file.py -k test_name

The suite uses unittest, not pytest.

Go

From code-example-tests/go/driver/tests/:

go test -v -p 1 -count=1 ./...                              # All tests
go test -v -p 1 -count=1 ./aggregation/pipelines             # One package
go test -v -count=1 ./... -run TestExampleOperations/YourName # One subtest

-p 1 avoids concurrent DB writes across packages. -count=1 is required because CONNECTION_STRING is loaded from .env at runtime (Go's cache keys on shell env, not dotenv). Consider GOFLAGS=-count=1 in your shell profile.

Java

From code-example-tests/java/driver-sync/:

mvn test
mvn -Dtest=example.ExampleStubTest test
mvn test -Dtest="topic.subtopic.YourTests#testYourExample"

CONNECTION_STRING must be in the shell environment before mvn test (export CONNECTION_STRING="...") or loaded via node run-tests.js (which reads .env from driver-sync/ or java/ via preflight). A .env under src/ is not read by Maven directly.

First-time setup: mvn clean install -DskipTests from code-example-tests/java/.

C# (Driver and EF Core)

From code-example-tests/csharp/driver/:

dotnet test Tests/Tests.csproj
dotnet test --filter "FullyQualifiedName~Tests.ExampleStubTest"
dotnet test --filter "FullyQualifiedName=Tests.Topic.TestClass.TestMethod"

EF Core tests live in Tests/EfCore/ in the same solution — dotnet test runs them with the driver tests unless filtered.

Mongosh (Jest)

From code-example-tests/command-line/mongosh/:

npm test
npm test -- -t '{test name}'

Same npm test / .env loading rules as JavaScript. Tests use test() and outputFromExampleFiles() rather than driver-style it() / that().

Capture the full output including any error messages, stack traces, and test result summary.

Step 4: Parse Results

If all tests pass, report the summary and stop.

If any tests fail, for each failure:

1. Extract the failure details: test name, error message, stack trace, expected vs. actual values
2. Classify the failure as a writer issue (actionable by the writer) or a tooling issue (should be escalated to the Grove team). Writer issues include environment setup, syntax errors, incorrect imports, bad output files, and test logic bugs. Tooling issues include comparison utility crashes, parser errors in output matching utilities, missing data type support in comparison libraries, comparison-kernel binary mismatches (see code-example-tests/tools/comparison-kernel/README.md — native per-OS binaries under bin/), and infrastructure/CI pipeline failures. If the writer's code and output appear correct but the comparison utility can't match them, that's a tooling issue — tell the writer to report it with enough detail to reproduce.
3. For writer issues, classify into one of these categories:

Connection Error

• Symptoms: MongoServerSelectionError, ECONNREFUSED, timeout on connect
• Diagnosis: Check if .env exists with CONNECTION_STRING. Verify the connection string format. Suggest creating/updating the .env file.

Output Mismatch

• Symptoms: ComparisonResult failure, "expected X but received Y", diff output
• Diagnosis: Read both the expected output file and the actual output from the test. Show a clear diff. Suggest one of these fixes:
  • Chain withIgnoredFields(...) for dynamic field values (e.g., _id, timestamps)
  • Chain withUnorderedSort() if order differs but content is correct
  • Update the output file if the actual output is correct
  • Switch to shouldResemble().withSchema(...) for highly variable output See the "Comparison API" section in the target language's conventions file for the full Expect API method signatures and ellipsis pattern reference.

Missing Sample Data

• Symptoms: Test skipped with "Missing: sample_mflix" or similar, or empty results from queries against sample databases
• Diagnosis: Explain which sample database is needed. Suggest wrapping in describeWithSampleData() or itWithSampleData() if not already.

Timeout

• Symptoms: Exceeded timeout of 120000 ms, test hangs
• Diagnosis: Check for missing client.close() in the example's finally block. Check for unclosed cursors or change streams. For JavaScript/Node.js, also check for missing await on async operations — a missing await can cause the test to hang without an obvious error. If the operation is expected to be slow (full-collection scan, multi-stage aggregation, or processing more than 10,000 documents), increase the specific test's timeout to 240000 ms via it('...', async () => {...}, 240000). Do not increase the global timeout in jest.config.cjs.

Import / Module Error

• Symptoms: Cannot find module, SyntaxError: Cannot use import, does not provide an export named
• Diagnosis: Verify the import path matches the actual file location. Check that the example file exports the expected function name. Verify ES module syntax is used consistently.

Runtime Error

• Symptoms: TypeError, ReferenceError, MongoDB operation errors
• Diagnosis: Read the example code at the line referenced in the stack trace. Identify the root cause (wrong collection name, bad query syntax, missing await, etc.).

Step 5: Suggest or Apply Fixes

For each diagnosed failure:

1. Present the diagnosis clearly: what failed, why, and what to change

2. Propose a specific fix with the exact code change

3. Ask for approval before making changes, unless the fix is adding an Expect chain modifier for dynamic fields or sort order (e.g., withIgnoredFields, withUnorderedSort) — these can be applied directly, then re-run to confirm. See the "Comparison API" section in the target language's conventions file.

   Do not auto-update expected output files without asking. An output mismatch may indicate an idempotency issue (stale state between runs) or a logic bug, not just a stale output file. Investigate the cause first.

After applying fixes, re-run the failing test to confirm the fix works.

Step 6: Report

Provide a summary headed with Skill: grove-run:

• Total tests: X passed, Y failed, Z skipped
• For each failure: what was wrong and what was done to fix it
• Any remaining issues that need manual attention

Edge Cases

• Multiple failure types in one run: Diagnose each failure independently. Don't assume all failures have the same root cause — a connection error and an output mismatch in the same run are unrelated issues.
• Test hangs with no output: Likely a missing client.close(), an unclosed change stream/cursor, or (in Node.js) a missing await. Check the example's finally/defer block first, then check for unawaited async calls.
• All tests skipped: Sample data is not loaded on the deployment. Explain this and suggest /grove-setup to check sample data availability.
• Test passes locally but fails in CI: Investigate discrepancies between the local and CI environments. Common causes include: missing sample data, timing/timeout differences, datetime or timezone handling (CI may use a different timezone), and OS-level differences (e.g., locale, line endings). Do not increase the global timeout — increase only the specific test's timeout if the operation is genuinely slow.
• Failure in teardown, not in the test itself: Investigate the cause — teardown failures can be blocking. Common causes include permissions issues (the test user lacks dropDatabase privileges) and incomplete state cleanup between tests (e.g., test A's teardown doesn't clean up what test B expects). Teardown errors with ns not found or similar "doesn't exist" messages are generally safe to ignore, but other teardown failures (permissions, timeouts, connection errors) should be diagnosed and fixed.