karma-testing

name	karma-testing
description	Use when running, selecting, or debugging unit tests with Karma and QUnit in the Inputmask repository. Front-load when investigating bugs, running single or multiple select test suites, or configuring local Chrome and BrowserStack targets.

Karma & QUnit Testing in Inputmask

This skill guides testing workflows in the Inputmask repository using Karma and QUnit.

Critical Rules & Pitfalls

1. ALWAYS Use ChromeHeadless for Automated Runs: karma.conf.js adds a GUI Chrome launcher when CI is not set. Running npx karma start or grunt karma via a CLI tool (Bash, PowerShell, etc.) without --browsers ChromeHeadless opens a visible Chrome window that never exits cleanly, causing the command to hang indefinitely.

2. ALWAYS Redirect Output to a File — Do Not Pipe Inline: Karma emits progress lines with ANSI escape codes that cause PowerShell Select-String and similar pipe commands to buffer indefinitely. Redirect stdout/stderr to a temp file, then read the file separately:

   npx karma start karma.conf.js --browsers ChromeHeadless --single-run --reporters progress > $env:TEMP\karma_results.log 2>&1
   

   Then read the file with the Read or Select-String tool in a separate step.

3. ALWAYS Rebuild the Test Bundle After Any Changes: Tests run from qunit/qunit.js, which is compiled by webpack from qunit/index.js and lib/. Any edit in lib/, qunit/tests_*.js, or qunit/index.js requires rebuilding the test bundle (npx webpack --config-name test) before running Karma, or running webpack in watch mode.

---

Workflows

1. Running Tests (Recommended Pattern)

Always use this exact pattern for reliable, non-hanging test runs:

# 1. Rebuild test bundle (if source changed)
npx webpack --config-name test

# 2. Run karma with ChromeHeadless, output to file
npx karma start karma.conf.js --browsers ChromeHeadless --single-run --reporters progress > $env:TEMP\karma_results.log 2>&1

# 3. Read results (separate step)
Select-String -Path $env:TEMP\karma_results.log -Pattern "TOTAL|FAILED" | Select-Object -Last 5

2. Running a Single Test Suite or Selected Test Suites

To isolate specific test files (e.g., only qunit/tests_numeric.js or qunit/tests_date.js):

1. Edit qunit/index.js to import and register only the desired test module(s):

   import testsNumeric from "./tests_numeric";
   import testsDate from "./tests_date";
   
   // ...
   if (qunit) {
     testsNumeric(qunit, Inputmask);
     testsDate(qunit, Inputmask);
   
     qunit.load();
   }
   

2. Rebuild the test bundle:

   npx webpack --config-name test
   

3. Run Karma:

   npx karma start karma.conf.js --browsers ChromeHeadless --single-run --reporters progress > $env:TEMP\karma_results.log 2>&1
   

4. Check results:

   Select-String -Path $env:TEMP\karma_results.log -Pattern "TOTAL" | ForEach-Object { $_.Line }
   

3. Fast Interactive & Live Debugging

To keep the browser open and re-run tests instantly on changes:

1. In one terminal, run the webpack test bundle watcher:

   npm run qunit
   

2. In another terminal, run Karma in watch mode:

   npx karma start --browsers Chrome --no-single-run --auto-watch
   

3. In the opened Chrome window, click the DEBUG button in the top right to open the standalone test page, then press F12 to open Chrome DevTools for breakpoints and console logs.

4. Alternative: Direct Browser HTML Runner (No Karma)

You can run and debug QUnit tests directly in any browser without Karma:

1. Rebuild the test bundle: npx webpack --config-name test (or keep npm run qunit running).
2. Open qunit/qunit.html in your browser.
3. Use the QUnit web interface dropdown to filter by module or re-run individual tests.

5. Running Specific Tests via CLI Filter

You can filter tests by name or module via Karma client arguments without modifying qunit/index.js:

# Filter by test name
npx karma start karma.conf.js --browsers ChromeHeadless --single-run -- --filter="masked" > $env:TEMP\karma_results.log 2>&1

# Filter by module name
npx karma start karma.conf.js --browsers ChromeHeadless --single-run -- --module="Simple masking" > $env:TEMP\karma_results.log 2>&1

6. Cross-Platform / Cross-Browser Testing (BrowserStack)

Use BrowserStack ONLY when reproducing or verifying browser-specific or OS-specific issues (e.g., Safari/iOS or Android mobile events):

1. Ensure credentials are set:

   $env:BROWSERSTACK_USERNAME="<username>"
   $env:BROWSERSTACK_ACCESS_KEY="<access_key>"
   

2. Run Karma specifying the target custom launcher from karma.conf.js:

   npx karma start karma.conf.js --browsers bs_safari_mac_Sonoma --single-run > $env:TEMP\karma_results.log 2>&1
   # Or for mobile:
   npx karma start karma.conf.js --browsers bs_iPhone14 --single-run > $env:TEMP\karma_results.log 2>&1
   

---

Quick Reference Commands

Task	Command
Build test bundle once	npx webpack --config-name test
Watch test bundle	npm run qunit
Run all tests (headless, non-hanging)	npx karma start karma.conf.js --browsers ChromeHeadless --single-run --reporters progress > $env:TEMP\karma_results.log 2>&1
Run tests with live auto-watch	npx karma start --browsers Chrome --no-single-run --auto-watch
Full validation pipeline	npm test (runs grunt validate)

---

Known Pre-existing Failures

The following numeric tests are known to fail deterministically in certain test bundle configurations (e.g., numeric-only bundles or specific run orders) but pass in the full suite. They are NOT regressions:

• Currency digits and delete #1351 — Delete key handling with Inputmask({...}) object form
• negationSymbol parentheses + clearIncomplete — Radix vs groupSeparator after .val() + blur
• currency type 1234.56 + backspace x4 — Backspace not affecting masked value in async setTimeout
• Highlighting Values with Negative Numbers #2714 — Type-replace over negative number selection

These are pre-existing issues in the test suite and unrelated to other changes.