Test CI

MNN Test / CI SKILL (index)

This skill is an index. Pick the document that matches the task and follow it:

The two tracks are independent: Android/host regression testing goes through test.sh, while iOS LLM benchmarking goes through transformers/llm/engine/ios/ios_llm_bench.sh.

Quick start

# Static checks only:
./test.sh static

# Host regression (CPU only): build + unit suite + smoke + LLM smoke.
./test.sh local

# Full on-device matrix on the attached arm64 device:
./test.sh android <serial>          # e.g. ./test.sh android R5CY71BJJ9D

<serial> comes from adb devices (the script prefers adbk and falls back to adb). If the device shows as unauthorized, the user must tap Allow USB debugging on the phone first.

Running a subset (filters)

Android mode takes an optional filter as the third argument:

./test.sh android <serial> cpu        # CPU unit + lowmem + llm
./test.sh android <serial> opencl     # OpenCL unit (image+buffer) + opencl smoke
./test.sh android <serial> vulkan     # Vulkan unit + vulkan smoke
./test.sh android <serial> gpu        # opencl + vulkan
./test.sh android <serial> unit       # all unit/op stages only
./test.sh android <serial> lowmem     # only the low-memory matrix
./test.sh android <serial> android-ci # bench + smoke + llm only (no unit/lowmem)

Valid filters: all (default) · cpu · opencl · opencl-image · opencl-buffer · vulkan · gpu · unit · lowmem · android-ci.

Reading the result (agent-friendly)

• Each stage prints a delimited ═══ stage: <name> ═══ block, then a PASS / FAIL / SKIP line.
• A final summary prints total / passed / failed / skipped and one line per stage. SKIP is not a failure — it means the prerequisite was absent (e.g. a GPU library, a model, or a missing build artefact).
• Exit code is non-zero iff any stage failed. Gate automation on the exit code, not on log scraping.
• Combined stdout/stderr for every stage is saved under logs/test-<UTC-timestamp>/<stage>.log — read the named log of a failing stage for the trailing output. rc=137 ≈ OOM-kill, rc=139 ≈ SIGSEGV.

Dynamic-shape device smoke tests

A zero exit code only proves that a backend context ran; it does not prove that the requested input shape selected the intended dynamic context. For a shape-sensitive device test, record and validate the runtime-observed input shape (for example, from a backend dump manifest or the runner's input tensor) before treating the test as dynamic-shape coverage.

Environment variables

Offline / no-network and mainland-China notes

LLM model provisioning is lazy: the download (or LLM_MODEL_DIR check) is deferred until the llm stage actually runs, and a provisioning failure skips only that stage. So the unit / smoke / bench stages run fine with no network.

# Already have the model on disk → no download attempt at all:
LLM_MODEL_DIR=/path/to/Qwen2.5-0.5B-Instruct-MNN ./test.sh local

# huggingface.co unreachable (e.g. mainland China) → fetch from ModelScope:
LLM_MODEL_SOURCE=modelscope ./test.sh android <serial>

For the built-in default model the ModelScope org is remapped automatically (taobao-mnn/* → MNN/*); an explicitly-set LLM_MODEL_REPO is used verbatim.

LLM backend/layout smoke

For backend or tensor-layout optimizations, do not stop at operator tests. Run an end-to-end llm_demo correctness smoke with a short prompt and another prompt long enough to cross backend prefill branch thresholds. This catches real exported-graph layout bugs where an op test covers only the output format, but the graph also changes an input tensor format.

macOS Metal answer A/B checks

For answer-level comparisons between two macOS Metal runtimes:

• A Metal config does not prove that Metal ran. In a restricted execution context, MTLCreateSystemDefaultDevice() may return nil, after which llm_demo prints Init Metal Error / Can't Find type=1 backend, use 0 instead and silently produces a plausible CPU answer. Run in a GPU-visible context and fail the case on either fallback marker.
• Use the same exported model, prompt bytes, backend settings and greedy sampler on both sides. Isolate each runtime's tmp_path / working directory so cache reuse cannot cross the A/B boundary.
• Decide the multi-line prompt contract before running. llm_demo normally treats every non-empty line as a separate prompt; if one file is intended to be one long prompt, flatten or use an explicitly one-line-aware runner and record the transformed-input checksum.
• Fixed token limits can stop in the middle of a UTF-8 token and can leave code answers incomplete. Exact matches are strong evidence, but low character similarity after an early greedy fork needs semantic review. For code prompts, use a large enough budget and compile/test the extracted code before claiming functional correctness.

Configuring stages

Editing test_stages.json is the supported way to add, drop, or retune unit / lowmem / smoke / bench stages. Every parameter (forward type, precision, gpuMode, thread count, tag, memory mode, dynamic-quant option, KleidiAI flag, per-stage skip list, smoke model list, benchmark args) lives there, and the _documentation block at the top of the file explains every field and every skip entry's rationale.

• Add a stage that runs an existing test in a new config → add an object to android.stages (or local.stages). See docs/testing.md § "增加专门阶段".
• Skip a known-broken test on one stage → add its exact name to that stage's skip array and document why under _documentation.skip_rationale.
• Add a smoke model / bench entry → see docs/testing.md § "新增 smoke 模型或 bench 阶段".

Auditing stale CI/test scripts

When asked to clean up old CI or test scripts, build a usage map before recommending deletion:

• Prefer git ls-files plus targeted rg/git grep over broad filesystem scans, so generated build directories and local experiments do not look like maintained CI surface.
• Classify scripts by role: active CI entrypoints, declarative test driver, release/package scripts, manual benchmark helpers, third-party vendored tests, and local device/debug helpers.
• Treat lack of in-repo references as a "review/deprecate" signal, not proof of dead code; internal CI systems can invoke tracked files by convention. Prefer a staged deprecation plan unless a script is both unreferenced and clearly superseded by test.sh / test_stages.json.
• When renaming or consolidating test entrypoints, grep for both executable names and generated-artifact prefixes. Update CI config, .gitignore, test_stages.json self-documentation, developer docs, skill docs, and code comments in the same change so the old entrypoint disappears completely.

Adding a new test

See test-suite.md § "Adding a new test" for the full steps. Two traps worth knowing up front: test/CMakeLists.txt globs sources at configure time, so a new test file needs a cmake re-run before it exists in run_test.out; and run_test.out prints an all-passed line even when the filter matched nothing, so confirm passed:N.

For deeper work on operators themselves, see the add-new-op skill.

Read next

docs/testing.md is the authoritative deep reference — read it for the per-stage breakdown, the stage-object field table, and worked examples.