agentleFS
zfoggzfogg/ascii-chat/.agents/skills/ascii-chat-testing/SKILL.md

ascii-chat-testing

Skill203 starsChanged 8 days agoMITView on GitHub

Write, select, run, and diagnose ascii-chat C and Python tests across Windows, macOS, and Linux, including Criterion, Docker, JUnit results, and Codecov coverage.

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 3 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use Clang and Ninja. Preserve build/dependency caches and unrelated work.

    line 28
  2. Distinctive:

    Read running-tests.md for focused Criterion commands, Windows Docker, Python harnesses, and standalone fixtures.

    line 43
  3. Very specific:

    Use the locked uv project at tests/ascii_chat_tests.

    line 47
  4. Very specific:

    Keep pytest collection under tests/python/.

    line 59
  5. Very specific:

    Use TestSuite .init/.fini fixtures for logging/options/resources.

    line 65
  6. Distinctive:

    Use typed Criterion assertions with helpful diagnostics: equality, strings, memory and floating-point tolerance where appropriate.

    line 66
  7. Very specific:

    Check asciichat_error_t and meaningful error context.

    line 67
  8. Distinctive:

    Prefer generated media/test patterns and loopback to hardware, public URLs, or credentials.

    line 69
  9. Very specific:

    Check performance output correctness before timing.

    line 71
  10. Very specific:

    Use supported ASan/UBSan checks when memory risks warrant them.

    line 72

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

ascii-chat testing

Run commands from the repository root unless stated otherwise. Read AGENTS.md, then inspect tests/CMakeLists.txt, cmake/deps/Criterion.cmake, and CMakePresets.json for the affected target. Current configuration takes precedence over historical commands. Plain Ninja/CMake builds use all available cores by default; do not add an explicit build job count. ctest --parallel is allowed with no numeric count so CTest can schedule tests across all available cores.

Select the evidence

TypeUse forLocation
Criterion unitIsolated API behavior, boundaries, ownership, validation/error pathstests/unit/
Criterion integrationInteracting subsystems, handshakes, network/session lifecyclesC files in tests/integration/
Criterion performanceRendering/throughput regressions with correctness checks and controlled measurementstests/performance/
Criterion contractsExplicitly linked white-box production contractstests/contracts/
Python pytestPython helper contracts and migrated native-process scenariostests/python/
Python fixture driverSupport program launched by a pytest case or a Criterion wrappertests/ascii_chat_tests/, tests/scripts/
Standalone C probesNecessary separate process, native platform facility, dependency/build boundary, or Python-driven fixturetests/standalone/, selected integration fixtures

The three primary Criterion categories are unit, integration, performance. Contract is an additional style/label; migrated suites retain unit/integration labels when assigned. Some contracts have only criterion;contract, so inspect discovery before claiming complete coverage. CTest labels describe scope, not language: integration also includes registered Python harnesses.

Prefer Criterion for new ordinary C regressions and extend existing suites. Standalone tests should be uncommon: retain them when a process/platform boundary justifies a separate main(), rather than duplicating the test framework. A source file's presence does not prove registration, build inclusion, or coverage participation.

Configure and discover

Use Clang and Ninja. Preserve build/dependency caches and unrelated work; reconfigure rather than deleting build/. The default preset currently disables tests, so enable them explicitly:

uv sync --project tests/ascii_chat_tests --frozen
cmake --preset default -B build -DBUILD_TESTS=ON
cmake --build build --target tests
ctest --test-dir build -N
ctest --test-dir build --print-labels
ctest --test-dir build -L '^unit$' --no-tests=error --output-on-failure --parallel
ctest --test-dir build -L '^integration$' --no-tests=error --output-on-failure --parallel
ctest --test-dir build -L '^performance$' --no-tests=error --output-on-failure --parallel

Criterion works natively on macOS, including Intel, and glibc Linux. This supersedes older Intel-Mac Docker-only testing guidance. Windows and musl builds disable Criterion; from Windows use Linux Docker. Release/RelWithDebInfo disable it by default: add -DASCIICHAT_FORCE_CRITERION_TESTS=ON with BUILD_TESTS=ON on supported platforms. Verify discovery; zero selected tests is not a pass.

Read running-tests.md for focused Criterion commands, Windows Docker, Python harnesses, and standalone fixtures. Read coverage-and-ci.md for XML generation, Codecov uploads, and CI diagnostics. Use ascii-chat Cross Platform Development and/or Testing for SSH, source transfer, compiler setup, and persistent environments.

Python tests

Use the locked uv project at tests/ascii_chat_tests. New Python tests go under tests/python/ and must be import-safe: create processes, parse arguments, and mutate environment only in fixtures or test functions. Share non-pytest mechanics through ascii_chat_tests; use pytest fixtures for isolation and lifecycle. Run uv run --project tests/ascii_chat_tests --frozen ruff check tests and uv run --project tests/ascii_chat_tests --frozen ty check tests after Python changes. Both check the entire test tree. CTest also registers these as python-ruff and python-ty. Pass the built binary with --ascii-chat-binary (or ASCII_CHAT_TEST_BINARY). Pytest uses xdist on all logical cores by default. CTest coordinates separate pytest batches using PROCESSORS to avoid nested oversubscription; preserve explicit CTest serialization for existing tests that share exclusive resources. Keep pytest collection under tests/python/; helper programs and manual scripts are not collected. See running-tests.md for direct and CTest commands.

Write useful C and Criterion tests

  • Reproduce observable failure with concrete inputs and expected outputs/state. Cover meaningful success, rejection, boundary, partial-failure, rollback, and cleanup paths. Do not mirror the implementation or refresh a golden without independently establishing correct behavior.
  • Use TestSuite .init/.fini fixtures for logging/options/resources; follow nearby suites and include/ascii-chat/tests/{common,logging}.h / lib/tests/. Isolate global options, errno, environment, temporary files, and sockets. Cases must work independently and in different orders.
  • Use typed Criterion assertions with helpful diagnostics: equality, strings, memory and floating-point tolerance where appropriate. Fatal assertions establish prerequisites before dereference; nonfatal expectations are suitable only when continuing is safe. Never put required operations inside C assert(), which disappears with NDEBUG.
  • Check asciichat_error_t and meaningful error context. Clear expected errno between independent operations. Follow project allocation tracking, ownership, platform/thread/socket abstractions, and log_*; raw debug printf/fprintf bypass filtering and disrupt terminal tests.
  • For worker-thread checks, inspect tests/contracts/worker_assert.h; ordinary Criterion assertions may require runner-thread context. Join workers and propagate failures. Prefer readiness signals and bounded deadlines to sleeps as synchronization. Clean up subprocesses on failure.
  • Prefer generated media/test patterns and loopback to hardware, public URLs, or credentials. Skip only for genuinely absent prerequisites and report why. Verify rejected mutations leave prior state intact. A quiet log is not positive evidence that frames or transitions occurred.
  • For a CI-safe synthetic client fixture, use --test-pattern --test-audio --no-audio-playback: the first two replace camera and microphone input, while disabling playback prevents PortAudio from requiring a speaker device. If audio behavior is outside the test's scope, use --test-pattern --audio=false instead. --test-pattern is a video source, so do not combine it with --file, --url, --waveform, or --fft; file/URL tests retain their media source, while waveform/FFT tests use an audio source instead.
  • Check performance output correctness before timing. Compare equivalent optimized builds, record CPU/SIMD/configuration, and avoid fragile timing thresholds on shared/emulated hosts. Coverage instrumentation changes performance.
  • Use supported ASan/UBSan checks when memory risks warrant them; inspect cmake/platform/Sanitizers.cmake for actual options. Debug alone is not proof instrumentation ran. Do not suppress findings just to obtain green tests.

Verify and report

Build the changed suite and run focused cases, then the relevant category/process scenario. Reconfigure after adding globbed C sources. Inspect ctest -N -V and CMake for exclusions, platform guards, fixture dependencies, serialization and deadlines. Report SHA/dirty patch, OS/architecture, commands, exits, counts/skips, and artifact paths. Distinguish compilation, executed assertions, coverage generation, accepted uploads, and native runtime evidence. Docker proves Linux behavior, not native Windows or macOS behavior.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.