Filtering Matrix Dimensions

A dimension filter changes which values a dimension offers, so the matrix produces a different set of cases. It follows Matrix and Cases, which introduces the matrix and the cases generated from it, and it works on the same test.

This is not the same thing as clearing a check mark in the Select column. Case selection leaves the matrix alone and unticks combinations that exist; a filter takes a value away, the matrix is rebuilt without it, and the cases carrying that value are never generated at all. The two are told apart by what the panel reports, and the difference is visible in a single number.

Select the Matrix and Cases test. Its four dimensions produce 3 × 2 × 2 × 2 = 24 cases, all of them selected:

Two readings matter here. Total Cases: 24 is what the run will execute, and the Test Cases (24/24) group header is selected cases over generated cases. The second number is the size of the matrix itself, and it is the one a filter moves.

Opening the filter

Click a dimension's column header in the case table — algorithm, seed, height or width. Each header opens the filter for that dimension only:

The dialog is titled Dimension Filter: algorithm and lists every value the dimension offers, each one checked. A checked value stays in the matrix; an unchecked value is removed from it. Select All and Clear All apply to the whole list. The Add value field below them widens a dimension rather than narrowing it, and is covered further down.

Keeping a single value

Clear ASTAR and DFS, leaving BFS checked, then click Apply:

Apply commits the dialog's state to the panel and leaves the dialog open, so several adjustments can be judged one after another. OK applies and closes, Cancel discards anything not yet applied, and Reset to Defaults restores this one dimension to the values the test declared.

Close the dialog. The panel has been rebuilt around the surviving value:

The table now holds eight rows, all of them BFS, renumbered Case 1 to 8. The algorithm column header is marked as changed, and the 🔸 badge reports that the panel no longer matches the committed plan.

The group header is the telling one: it reads Test Cases (8/8), not 8/24. Eight cases are selected out of eight that exist. Had the same eight been reached by clearing check marks in the Select column, the header would have read 8/24 — the sixteen ASTAR and DFS cases would still be there, merely unticked. They are gone because the values that produced them are gone.

The plan holds until it is committed

The panel is a proposal. Look at the test's row in the execution tree while the filter sits on the panel uncommitted:

Plan still counts 24. The tree reports what was committed, not what is currently on the panel, so a filter can be tried, judged and abandoned without disturbing the recorded plan or the runs measured against it.

Click Update Plan and confirm with Yes:

The test's plan drops to 8, and the totals above it follow: the Advanced Configuration Parameters group falls from 153 to 137 and the Tutorial suite from 282 to 266 — sixteen fewer planned cases in each. A run started now executes the eight surviving cases and counts against this plan.

Filtering several dimensions

Each dimension has its own filter, and they combine the way the matrix does. Keep BFS on algorithm and 42 on seed, leaving both heights and both widths:

1 × 1 × 2 × 2 = 4 cases survive, and both filtered column headers are marked. The surviving cases are the product of the values kept on every dimension, not a list of rows chosen by hand.

This is what makes filtering worth reaching for on a large matrix. Pinning three dimensions and leaving one open isolates that dimension's effect, and the case count states plainly how much work the next run is.

Undoing a filter

A filter that could not be lifted would narrow the matrix for good. Click Reset To Defaults. Nothing changes yet — a confirmation appears first:

It is worth reading before answering, because the reset is not limited to the filter: every field returns to its declared default, and a required field that has no default is cleared.

Confirm with Yes:

All three algorithms are back and the matrix produces its full 24 cases again. Note the Maze Executable Folder row: it has been emptied and flagged, exactly as the dialog warned. It has no default to fall back on, so it must be set again before the test can run.

To restore a single dimension without touching the rest of the configuration, use Reset to Defaults inside that dimension's own filter dialog instead.

Adding a value the matrix never declared

Everything so far has narrowed the matrix. The Add value field at the bottom of the dialog works in the other direction, and this section uses a different dimension to show it: width, which the test declares as (15, 20).

Open the filter from the width column header, type 30 into Add value and click Add:

The value joins the list already checked, marked with ✶ to distinguish it from the values the test declared. The entry is read as an integer when it looks like one, otherwise as a floating-point number, otherwise as text — so 30 arrives as a number and GREEDY would arrive as a string. Adding a value that is already listed simply checks it.

Click OK. The matrix is rebuilt around three widths instead of two:

3 × 2 × 2 × 3 = 36 cases, and the width column now cycles through 15, 20 and 30. A dimension can therefore be widened as well as narrowed from the panel, without editing the test source.

The field is present only while Random Configuration is set to Disabled; a dimension that draws its values randomly is covered on its own page.

Filtering, selection and the plan

Three mechanisms narrow a run, and they sit at different levels:

The matrix, declared in the test source, defines which dimensions exist and which values they can take. Dimension filters change the values a dimension offers for this configuration, so they change which cases are generated. Case selection leaves the generated cases in place and chooses which of them run. Only Update Plan commits any of it, and until then the execution tree keeps reporting the plan that is already there.

A dimension can also be told to draw its values at random instead of listing them, which replaces the value list rather than filtering it — while a random mode is active the list, Select All and Clear All are disabled, and Add value is hidden. That is the subject of Matrix Dimensions Randomization.

Filters and selection are decisions made in the controller for one configuration. A combination that never makes sense for the application is removed in the test source instead, which is what Matrix Cases Exclusion covers next.