---
name: testing-simulink-models
description: Creates persistent Gherkin-based pass/fail tests for Simulink models and individual subsystems using model_test. Use when verifying expected behavior, writing regression tests, reproducing issues, or validating bug fixes with structured assertions. Requires Simulink Test.
license: MathWorks BSD-3-Clause
metadata:
author: MathWorks
version: "1.0"
---
# Simulink Gherkin Tests
Requires **Simulink Test**. If unavailable, use `simulating-simulink-models` with manual assertions.
Use this skill when you need persistent, reusable pass/fail verification of model behavior.
## When to Use
- Writing persistent 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 for a component
## 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`
- **Simulink Test is not installed** → use `simulating-simulink-models` with manual assertions
- **Component has no inputs or no outputs** → model_test requires at least one Inport and one Outport; use `simulating-simulink-models` instead
- **Component has physical modeling (Simscape) ports** → test a parent subsystem with signal-based I/O instead
## Workflow
1. **Understand the component:** Use `model_overview` and `model_read` on the target subsystem to identify inputs, outputs, and expected behavior.
2. **Write the `.feature` file:** Author a Gherkin test following the Syntax Reference below. Start with one scenario covering the primary nominal case.
3. **Run in draft mode:** Call `model_test` with `draft_mode='true'` for rapid iteration (~3s). Fix syntax or signal errors.
4. **Run full compilation:** Once draft passes, re-run with `draft_mode='false'` to validate against the actual compiled model (catches type/dimension mismatches).
5. **Expand coverage:** Add scenarios for edge cases, fault conditions, and boundary behavior. Use `coverage='decision'` to identify untested branches.
## Syntax Reference
Write a `.feature` file in this format, then pass it to `model_test`:
```gherkin
# --- front-matter:toml --- # REQUIRED: exactly one, must be first in file
model = "Model.slx" # model filename with .slx extension
component = "Model/Subsystem" # optional; default = model name without .slx
[inputs] # alias = "portReference" for each input port
Speed = "Speed" # scalar port: just the port name
Torque = "'Torque (Nm)'" # single quotes if name contains ( ) or .
Pos = "Position(2)" # vector element: "PortName(N)"
Cmd = "Control.Throttle" # bus element: "PortName.Element"
[outputs] # alias = "portReference" for each output port
Output = "Output" # scalar port
Force = "'Force (N)'" # single-quoted scalar port
Yaw = "'Rate (deg/s)'.Filtered(2)" # single-quoted port with vectorized bus element
# --- end front-matter --- # markers must be exact as shown
Feature: Descriptive title # exactly one Feature, colon required directly after keyword
Description text here. # descriptions cannot start with keywords; prefix * to escape
Scenario: Unique scenario title # at least one Scenario, unique titles, colon required
Description of test case.
Given inputs # exactly one Given; MUST have * line for EVERY declared input
* Speed = const(50) # const(<value>)
* Torque = step(0 -> 100 @ 1s) # step(<from> -> <to> @ <time>) time: Ns or Nms
When simulate for 5s in Normal mode # EXACT syntax; duration: Ns or Nms (>0); mode: Normal|SIL
Then baseline "ref.mat" with tolerances: absTol=0.01, relTol=0.01, timeTol=50ms
* Output: absTol=0.001 # per-signal tolerance override; defaults are 0
Then outputs # 1-2 Then blocks allowed (baseline and/or outputs)
* Positive: Output > 0 # operators: == != < > <= >= (never vs another signal)
* Bounded: Output == [10 .. 90] # ranges with == only: [a..b] (a..b) [a..b) (a..b]
* Settled: Output > 80 when t > 3s # conditional: when t <op> <time>
* InRange: Output == (0 .. 100] # assessment names must be unique
```
**Not supported:** `And` `But` `Rule` `Example` `@tags` `|tables|` `"""`
## Description Line Escape
```gherkin
# ❌ WRONG - starts with keyword:
When input changes, output responds
# ✅ Rephrase:
If input changes, output responds
# ✅ Or escape with *:
* When input changes, output responds
```
## Best Practice
Prefer subsystem component-level tests—top level models can be large and slow to update/test, while subsystem components offer faster iteration, isolation, and clearer failure diagnosis. Use judgment based on what you're verifying.
The component under test must not contain physical modeling ports (PMIOPort / Simscape Connection Port blocks). Only components with standard Simulink Inport/Outport interfaces are supported. If the subsystem you want to test has physical ports, test a parent subsystem that wraps it with signal-based I/O instead.
If the model contains Simscape elements, set the model parameter `SimscapeLogType` to `"none"` before running tests. Simscape logging can interfere with test harness signal routing. This is a one-time model configuration, not a simulation command. Use: `set_param('ModelName', 'SimscapeLogType', 'none')`.
## Coverage
Pass `coverage='none'` (default) or `coverage='decision'` when calling `model_test`. The `coverage` parameter is required. Use `'decision'` to collect both execution and decision coverage metrics (requires Simulink Coverage toolbox). Use `'none'` when coverage is not needed.
## Draft Mode
Pass `draft_mode='true'` for rapid test iteration (~3s vs ~60s). Draft mode skips the main model compile and uses a lightweight harness. Use `'true'` by default during test development.
**Limitation:** Draft-mode harness uses double scalar for all inputs and outputs. If the model under test has non-double ports (boolean, integer, single, bus, vector), draft mode will fail with data type mismatch errors. In that case, re-run with `draft_mode='false'`.
## Directory Warning
Don't change MATLAB's working directory while a model is open. Test harness cache is directory-tied—changing it causes stale harness errors.
----
Copyright 2026 The MathWorks, Inc.
----