8.1 KiB

Raw Blame History Unescape Escape

src/tests/modules — Source Module Test Suites

Purpose

Unit tests for editable source modules under src/modules/, src/modules_tcl8/, and src/modules_tcl9/. These tests use tcltest and run against the uninstalled source tree through src/tests/runtests.tcl.

Ownership

Agents should add or update tests here when changing module behavior in src/modules/ or Tcl-version-specific module trees.
Installed-module test packages under src/modules/test/ are packaging artifacts and are not the default place for source-tree behavior tests.
Do not delete, skip, or weaken existing tests without explicit user direction.

Local Contracts

The directory hierarchy mirrors module namespace paths, such as src/tests/modules/punk/args/ for punk::args.
Test files use .test extension and must package require any extra packages explicitly.
Test files must end with tcltest::cleanupTests so src/tests/runtests.tcl can produce trusted aggregate counts.
Test files may commonly use line-continuation backslashes, and existing Tcl expand-syntax structures in tests should not be refactored into line continuations.
Tests must exercise source modules as loaded by src/tests/runtests.tcl, not installed or built output modules.
testsuites/dev/ may hold known-bug or expected-fail tests; guard them with disabled tcltest constraints so standard source-tree runs skip them by default.

Work Guidance

Put new module tests under src/tests/modules/<namespacepath>/testsuites/<suite>/ following nearby layout.
For efficient agent runs, use -report compact -show-passes 0 and include the narrowest namespace path plus file tail when known.
Prefer try { ... } on error {result options} { ... } for structured error capture in test bodies.
Focused verification should mirror production pipelines inside tests using Punk pipeline syntax when that parity matters.
Capture enough stderr or failure context to identify the failing command or assertion.

Verification

Run targeted module tests with <tcl_interpreter> src/tests/runtests.tcl -report compact -show-passes 0 -include-paths modules/<namespacepath>/**.
Run a single test by name with <tcl_interpreter> src/tests/runtests.tcl -report compact -show-passes 0 -tcltestoptions {-match <test_name>} -include-paths modules/<namespacepath>/**.
Run a specific test file by adding its file tail, such as <tcl_interpreter> src/tests/runtests.tcl -report compact -show-passes 0 -include-paths modules/punk/args/** parsekey.test.
Use -report markdown+json when both detailed human-readable failure sections and a structured summary are useful.
If a compact result shows reason=missing-cleanupTests, add the missing tcltest::cleanupTests before trusting observed pass events.

Child DOX Index

opunk/console/ — ::opunk::Console backend subclass tests (testsuites/console/backends.test, G-001): virtual dispatch of subclass overrides through base-class calls and punk::console::console_spec_resolve (both unchanged), TestConsole determinism + probe-free at_eof, SshConsole capability/eof + the flagship size-via-ANSI-query-over-socket case (a scripted remote terminal answers CSI 6n), TkConsole widget size/eof (gated behind env PUNK_TEST_TK=1 - Tk in the shared testinterp has side effects; also verifiable standalone under a tk-capable kit e.g punk91 src <script>)
punkcheck/ — punkcheck module tests (install, summarize_install_resultdict, installtrack)
punk/ansi/ — punk::ansi tests (testsuites/ansi/): ansistrip/ansimerge, plus characterization of the ANSI-at-position mechanisms (ansistring.test: INDEX/INDEXCODE/INDEXCHAR/RANGE/INSERT grapheme indexing with SGR-prefix merging, INDEXCOLUMNS/COLUMNINDEX double-wide column mapping, trim/VIEW), code splitting invariants (ta.test: detect/detectcode distinction, split_codes/split_codes_single/split_at_codes shapes and round-trip) and single-code/effective-state semantics (codetype.test: is_sgr_reset/has_sgr_leadingreset, has_any/all_effective, sgr_merge, sequence_type classify). ANSI codes in these tests are literal escape strings so results are colour-state independent
punk/args/ — punk::args tests (testsuites/args/): parsing, choices/choicegroups, forms, rendering/indentation characterization, usage-marking characterization (usagemarking.test: -parsedargs/-badarg/-parsestatus/-scheme marking primitives plus goodchoice highlighting of selected/default-in-effect choice words, asserted by SGR-parameter subset against the live colour arrays; the G-049 nocolour/colour-leak GAP pins flipped 2026-07-10 to scheme-statelessness assertions), the G-049 parse-status structure (parsestatus.test: punk::args::parse_status overall/per-argument statuses, badarg for type/allocation failures, -caller attribution, errorcode -argspecs stripping), and tclcore doc/interpreter behavioural parity (tclcoreparity.test, G-054, gated on have_tclcoredocs: 'string is' class choices equal the live-harvested set, per-class docids exist, error-vs-ok agreement across the probe matrix, version-note labels conditional on class presence - expectations derived from the running interpreter, green on 8.6/8.7/9.0; under 8.6 run the file directly via a plain tclkit + tcltest driver since runtests' harness needs newer infrastructure)
punk/ns/ — punk::ns tests (testsuites/ns/): cmdwhich/cmdinfo/cmd_traverse doc-lookup flow (cmdflow.test, G-040 parity) and cmdhelp usage-rendering integration (cmdhelp.test: scheme selection, goodarg/badarg marking incl type/allocation failures, goodchoice highlighting of supplied/default choice words, alias path, cmdinfo result shape, queried-command failure attribution, and -return dict parse-status returns (G-049 - its GAP pins flipped 2026-07-10); remaining GAP pins for pseudo-command cmdtype + space-form docid prefixes (G-051, real string is pins behind the have_tclcoredocs constraint), TclOO undocumented-method fallback (G-052), and synopsis marking absence (G-050))
punk/mix/ — punk::mix::cli tests (prune helpers, punkcheck virtual sources), punk::mix::commandset::repo fossil move/rename characterization tests (testsuites/repo/, FOSSIL_HOME-isolated; GAP-marked tests pin behaviour G-022 will change), and the MULTISHELL polyglot build machinery (testsuites/scriptwrap/multishell.test: scriptset wrap via the punk.multishell.cmd template - structure/LF-only/determinism, checkfile 512-byte label validation of fresh wraps AND the committed bin/runtime.cmd, the runtime scriptset round-trip byte-identity pin, and platform-gated execution smoke: cmd.exe→powershell payload on windows, sh payload on unix or via the wsllinux capability constraint from src/tests/testsupport/wslprobe.tcl - staged to the WSL distro's native filesystem, G-059)
punk/lib/ — punk::lib tests (testsuites/lib/): range/index/parse/compat/interp_sync utilities, G-058 static-baseline seeding (staticseed.test: interp_sync_package_paths/snapshot_package_paths propagate a simulated ::punkboot static baseline and seed load {} <prefix> ifneeded mappings; no-op without a baseline), and the repl command-completeness engine (commandcomplete.test: punk::lib::system::incomplete pending-opener stacks - the info-complete quoting quirk progression (set x "{*}{" standalone vs in-proc-body), single openers, tabs, escapes, incomplete<->info-complete parity property; pre-repl-refactor characterization, see goals/G-044 detail preserve-list)
punk/packagepreference/ — punk::packagepreference tests (testsuites/packagepreference/): G-058 static-vs-bundled policy (staticpolicy.test: require of a baseline package triggers the index scan before resolution so a newer bundled copy wins, static beats older bundled, exact requires of bundled versions stay reachable, missing static mappings get seeded)
punk/libunknown/ — .tm same-version shadowing pin-tests (testsuites/shadowing/): tcl:™️:add prepend rule, head-of-tm-list wins exact-version ties, version beats order, punk::libunknown parity — shipped behaviour depends on these (runtests tm ordering, punk_main package-mode precedence, G-033); mixed .tm/pkgIndex.tcl characterization is goal G-035

8.1 KiB Raw Blame History Unescape Escape