fix-linter-test

name	fix-linter-test
description	Debug and fix a failing MegaLinter linter test. Use when a linter test fails in CI or locally.
allowed-tools	Read Grep Glob Bash Edit
argument-hint	[linter-name-or-test-output]
model	sonnet
metadata	{"internal":true}

Debug the failing test for $ARGUMENTS.

Steps:

1. Find the test file in megalinter/tests/test_megalinter/linters/
2. Check if it's auto-generated (has @generated by .automation/build.py header) — if so, fix the descriptor YAML or fixtures, NOT the test file itself
3. Read the descriptor YAML in megalinter/descriptors/ to understand expected behavior (cli_lint_mode, supported_cli_lint_modes, config_file_name, cli_lint_errors_regex, file_extensions)
4. Check test fixtures in .automation/test/<test_folder>/:
   • Good files must pass the linter cleanly
   • Bad files must trigger errors matching cli_lint_errors_regex
   • File extensions must match file_extensions or file_names_regex in the descriptor
5. If a custom linter class exists in megalinter/linters/, review it for issues
6. Common failure causes:
   • Fixture file extensions don't match descriptor's file_extensions
   • cli_lint_errors_regex doesn't match actual linter output format
   • Missing config file referenced in config_file_name
   • cli_lint_mode mismatch (file vs list_of_files vs project)
   • supported_cli_lint_modes lists a mode the tool can't run — the per-mode tests (test_success_<mode>_lint_mode / test_failure_<mode>_lint_mode) run for every declared mode; if a failure is confined to one mode, remove it from supported_cli_lint_modes (unsupported modes are auto-skipped)
   • Version pin broken or tool not installable in Dockerfile
   • Linter behavior differs between host OS and Docker container (Linux)
   • test_success_project_lint_mode fails on a file under .wireit/: that is a poison fixture guarding excluded-directories forwarding (see .claude/rules/testing.md). The forwarding is broken, not the fixture — check the command in the log for the forwarded exclusion arguments and the [Excluded directories] trace line, then review the descriptor's cli_lint_mode_project_exclude_* properties or the class manage_excluded_directories_config() / build_lint_command override (a custom build_lint_command that does not call super() bypasses forwarding). Do NOT delete the poison fixture to make the test pass
7. Reproduce in Docker (required — linters are not installed locally):

   LINTER="<descriptor_id_lowercase>_<linter_name>"
   docker buildx build --platform linux/amd64 --file linters/$LINTER/Dockerfile --tag $LINTER .
   docker run --rm --env TEST_CASE_RUN=true --env OUTPUT_DETAIL=detailed \
     --env TEST_KEYWORDS="${LINTER}_test" --env MEGALINTER_VOLUME_ROOT="." \
     --volume "$(pwd):/tmp/lint" $LINTER
   

   To run only specific test methods, use a -k-style substring (matches all modes):

   # all failure-mode tests (test_failure_file_lint_mode, _list_of_files_, _project_)
   --env TEST_KEYWORDS="${LINTER}_test and test_failure"
   # narrow to a single mode
   --env TEST_KEYWORDS="${LINTER}_test and test_failure_project_lint_mode"
   

8. In CI, filter tests via commit message body: TEST_KEYWORDS=<linter>_test
9. Update CHANGELOG.md only if the fix changes user-visible linter behavior (wrong error count, missed files, broken output). Add one line under Fixes in the beta section:

   - Fix <linter-name>: <what was wrong and what users now get>
   

   Do NOT add an entry for test-infrastructure-only fixes (fixture paths, test class regeneration, etc.). Style: .claude/rules/changelog.md (written for end users, no internal details).