rules-maintenance

Maintain rule test suites, especially when @markuplint/html-spec changes.

Input

$ARGUMENTS specifies the task:

Task: add-spec-tests

Which test file?

Test Pattern

import { mlRuleTest } from 'markuplint';
import rule from './index.js';

// Valid case — no violations
const { violations } = await mlRuleTest(rule, '<img src="x.png" alt="desc" role="math">');
expect(violations).toStrictEqual([]);

// Invalid case — exact violation object
const { violations } = await mlRuleTest(rule, '<img src="x.png" alt="desc" role="navigation">');
expect(violations).toStrictEqual([
  {
    severity: 'error',
    line: 1,
    col: 38,
    message: 'Cannot overwrite the "navigation" role to the "img" element according to ARIA in HTML specification',
    raw: 'navigation',
  },
]);

// ARIA version test
const { violations } = await mlRuleTest(rule, '<button role="separator" ...>', {
  rule: { options: { version: '1.1' } },
});

Conventions

• •toStrictEqual with exact { severity, line, col, message, raw } — never loose assertions
• •Always include both valid and invalid cases
• •Some roles need ARIA attributes in HTML: separator → aria-valuenow, meter → aria-valuenow

Task: update-test-expectations

When html-spec data changes break existing tests:

1. •Run yarn test to find failures
2. •Verify the new behavior is correct (not a regression)
3. •Update expected violation objects (message strings, etc.)
4. •Common cause: adding enum values changes error message strings

Rules

1. •Always run yarn test (full suite), not just the rules package
2. •Use toStrictEqual with exact objects — no loose assertions
3. •Check ml-spec algorithm tests when changing ARIA mappings — ml-spec/src/algorithm/aria/get-permitted-roles-spec.spec.ts has hardcoded role arrays