unit-test-quality-checks

name	unit-test-quality-checks
description	Unit test validation rules for Scopy plugin IIOWidget tests. Auto-loads when reviewing or writing `*_Unit_test.js` files.

JS Unit Test Quality Check Rules

Apply these 7 validation categories when reviewing or generating JS unit test scripts for Scopy plugins.

---

CRITICAL

[U1] Widget Coverage

• Extract all widget keys from the plugin's widget factory source (IIOWidgetBuilder calls) or getWidgetKeys() return
• Extract all Q_INVOKABLE getter/setter pairs from the plugin's *_api.h
• Compare against widget keys and API methods exercised in the JS unit test files (from readWidget(), writeWidget(), testRange(), testCombo(), testCheckbox(), testReadOnly(), testConversion(), and runDataDrivenTests() calls)
• Flag any widget key that has no corresponding test
• Flag any Q_INVOKABLE getter/setter pair with no test exercising it
• Flag any test that references a widget key not in the discoverable set

[U2] Helper Function Usage

• Tests for standard widget types MUST use canonical helper functions:
  • Range/spinbox widgets: testRange()
  • Combo/dropdown widgets: testCombo()
  • Checkbox/toggle widgets: testCheckbox()
  • Read-only widgets: testReadOnly()
  • API conversion tests: testConversion()
  • Bad value boundary tests: testBadValueRange(), testBadValueCombo()
• Data-driven sections with 3+ widgets of the same type MUST use runDataDrivenTests()
• Flag any test that manually writes/reads/compares widget values when a standard helper exists for that widget type
• Exception: complex tests (in the Complex section) are allowed custom logic

[U3] Sleep After Setters

• Every writeWidget(), set*(), or any state-mutating API call (e.g., calibrate(), dpdReset(), refresh(), loadProfile()) must be followed immediately by msleep(500) on the next non-empty line
• msleep(1000) or longer is acceptable (minimum is msleep(500))
• This applies both inside helper function definitions and in individual test bodies
• No state-mutating call may be left without a subsequent sleep

[U4] State Restoration

• Every test that modifies device state must save the original value before changing it
• The original value must be restored in all exit paths: normal completion, early return, and catch block
• For tests that modify multiple values (e.g., ENSM mode + gain control mode), all modified values must be restored
• Complex tests modifying multiple widgets must restore every widget they changed

---

WARNING

[U5] Bad Value Tests

• Every range widget with a testRange() call SHOULD also have a testBadValueRange() call
• Every combo widget with a testCombo() call SHOULD also have a testBadValueCombo() call
• Report the coverage ratio (e.g., "12/15 range widgets have bad value tests, 80%")
• Warn if bad value test coverage drops below 80%

[U6] Complex Test Isolation

• Complex multi-step tests must be in a clearly marked section (e.g., // SECTION: Complex Functionality Tests)
• Each complex test must have a comment documenting what it tests (e.g., // C1: Full Calibration Flow)
• Complex test UIDs must follow UNIT.<SECTION>.<DESCRIPTIVE_NAME> format
• Flag any undocumented complex test mixed into attribute test sections

---

INFO

[U7] File Structure

• File naming must follow the convention:
  • <plugin>_Basic_Unit_test.js — basic/main tool widget tests
  • <plugin>_Advanced_Unit_test.js — advanced tab widget tests
  • <plugin>_Complex_Unit_test.js — multi-step functionality tests
  • <plugin>_Unit_test.js — combined runner (or single file if only one)
• Each standalone file must end with the termination sequence in order:
  1. TestFramework.disconnectFromDevice()
  2. TestFramework.printSummary()
  3. scopy.exit()
• The combined runner file uses evaluateFile() to include sub-files and must NOT duplicate helper functions or test cases
• The GPL license header must be present at the top of every file