# Fix Linter Test

> Debug and fix a failing MegaLinter linter test. Use when a linter test fails in CI or locally.

- Skill: `oxsecurity/fix-linter-test` (Agent Skill)
- Install (CLI): `npx skillmds@latest add oxsecurity/fix-linter-test`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oxsecurity/fix-linter-test/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: oxsecurity (https://skillmd.com/u/oxsecurity)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/oxsecurity/fix-linter-test

---


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):
   ```bash
   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):
   ```bash
   # 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:
   ```text
   - 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).