testing-simulink-models

Testing Simulink Models

Requires Simulink Test and R2023a or later. The requirement-driven entry point also requires Requirements Toolbox. The coverage workflow also requires Simulink Coverage. If Simulink Test is unavailable, use simulating-simulink-models with manual assertions.

When to Use

Writing pass/fail tests for a Simulink model or subsystem
Verifying expected behavior against requirements or acceptance criteria
Creating regression tests to catch future breakage
Reproducing and validating bug fixes with structured assertions
Collecting decision coverage metrics
Authoring persistent tests from linked requirements or a behavioral spec

When NOT to Use

Building or editing model structure → use building-simulink-models
Running simulations for data exploration, sweeps, or custom analysis → use simulating-simulink-models
Querying or resolving parameter values → use model_query_params / model_resolve_params
Creating or editing requirements → use generate-requirement-drafts
Injecting faults onto model signals without test authoring → use inject-faults
FMEA, FHA, FTA, or other safety analysis documents → use manage-safety-analysis
Simulink Test is not installed → fall back to simulating-simulink-models with manual assertions

Testing Approaches

This skill provides two testing approaches. Choose based on task context:

	Gherkin (`model_test`)	Simulink Test API (`test_create` family)
Persistence	Ephemeral — harness discarded after session	Persistent — .mldatx files remain in project
Speed	~3s (draft mode)	~60s (full Simulink Test infrastructure)
Traceability	None	Full requirement linking via `.slreqx`
Use case	Bug fixes, quick validation, agentic loop	Certification, systematic testing, formal V&V; also takes behavioral specs
Approval needed	No	Yes — engineer reviews test plan before execution
Coverage	`coverage` parameter (`'none'` or `'decision'`)	Via `test_run` options
Toolbox	Simulink Test	Simulink Test (+ Requirements Toolbox for requirement path)

→ For Gherkin testing, read references/gherkin-based-fast-testing.md → For Simulink Test API authoring (requirements / behavioral spec), read references/simulink-test-authoring.md

Workflow — Gherkin (Quick Validation)

Understand the component: Use model_overview and model_read on the target subsystem to identify inputs, outputs, and expected behavior.
Write the .feature file: Author a Gherkin test following the syntax in references/gherkin-based-fast-testing.md. Start with one scenario covering the primary nominal case.
Cap StopTime before running: Check the model's StopTime with model_query_params. If it is inf (or unset/auto), you MUST pass a finite stop time to model_test — an infinite sim never returns and hangs MATLAB. Pick a finite value that lets the behavior settle (2–30s for a step response).
Run in draft mode: Call model_test with draft_mode='true' for rapid iteration (~3s). Fix syntax or signal errors.
Run full compilation: Once draft passes, re-run with draft_mode='false' to validate against the actual compiled model (catches type/dimension mismatches).
Expand coverage: Add scenarios for edge cases, fault conditions, and boundary behavior. Use coverage='decision' to identify untested branches.

Workflow — Simulink Test API (Persistent)

Understand the component: Use model_overview and model_read on the target subsystem to identify inputs, outputs, and expected behavior.
Propose test plan → wait for approval: Present what to test, at what scope, and why. Do not call test_create until the engineer approves.
Create test cases: Call test_create with the appropriate entry point — component/model only or requirement-driven (RequirementID + ReqSetPath). Pass TestFile as an absolute path under the working folder (never a bare filename — it would land in the skill's scripts/ dir, since that is the project_path). See references/simulink-test-authoring.md for call shapes.
Propose test configuration → wait for approval: Present stop time, sim config, signal logging, assessments, and parameter overrides for each test case. Do not call test_edit until the engineer approves. Always set a finite StopTime via test_edit — if the model's StopTime is inf (or unset), the test run never returns and hangs MATLAB. Choose a finite value that lets the behavior settle (2–30s for a step response).
Run and report: Call test_run, present pass/fail summary with assessment detail. Engineer decides next steps.

Guardrails

Always

Inspect model (model_overview / model_read) before writing tests — otherwise you write tests against wrong I/O
Report failures with assessment names, conditions, and signal summaries — users can't diagnose without detail
Never run a sim or test with StopTime=inf. Check StopTime before any model_test/test_run; if it is inf or unset, override it with a finite value first. An infinite sim never returns and hangs the MATLAB session (and, in a shared session, every subsequent task).

Never

Guess pass/fail criteria — ask the user if unclear
Change MATLAB working directory while a model is open — breaks harness cache

References

references/gherkin-based-fast-testing.md — Gherkin syntax, draft mode, coverage, Simscape constraints
references/simulink-test-authoring.md — API manual: setup, constraints, test_create entry shapes, edit/read/run signatures
references/assessment-format.md — LoggedSignals and Assessments struct formats
assets/test-structure-template.md — Test structure proposal template (requirement-driven path)
assets/test-config-template.md — Test configuration proposal template (requirement-driven path)