Basic Configuration Parameters group

The Folder Parameter test we just built doesn't stand on its own - it's one of several tests bundled together under a test group called Basic Configuration Parameters, each demonstrating a different configuration field type. You've already seen this group in the execution tree:

Let's review the code of the file that defines this group:

orcraft-test-suite-tutorial/test_group_basic_configuration_parameters/

Group file structure

Imports

from __future__ import annotations

from orcraft import (
	OrcraftTestGroup,
	OrcraftTestGroupConfig,
	OrcraftTestGroupResult,
	OrcraftConfigField,
)

from test_group_basic_configuration_parameters.test_folder_parameter.test_folder_parameter import TestFolderParameter
from test_group_basic_configuration_parameters.test_boolean_parameter.test_boolean_parameter import TestBooleanParameter
from test_group_basic_configuration_parameters.test_selector_parameter.test_selector_parameter import TestSelectorParameter
from test_group_basic_configuration_parameters.test_folder_list_parameter.test_folder_list_parameter import TestFolderListParameter
from test_group_basic_configuration_parameters.test_file_parameter.test_file_parameter import TestFileParameter
from test_group_basic_configuration_parameters.test_file_list_parameter.test_file_list_parameter import TestFileListParameter
from test_group_basic_configuration_parameters.test_numeric_parameter.test_numeric_parameter import TestNumericParameter
from test_group_basic_configuration_parameters.test_multi_selector_parameter.test_multi_selector_parameter import TestMultiSelectorParameter
from test_group_basic_configuration_parameters.test_string_parameter.test_string_parameter import TestStringParameter

Unlike a test, a group imports OrcraftTestGroup and OrcraftTestGroupConfig instead of OrcraftTest and OrcraftTestConfig - plus one import per test it bundles together.

Config class

class TestGroupBasicConfigurationParametersConfig(OrcraftTestGroupConfig):
	name = OrcraftConfigField.Text(default="Basic Configuration Parameters")
	description = OrcraftConfigField.Text(
		default="Covers tests that demonstrate configuration parameters used with the maze app."
	)
	tests = OrcraftConfigField.Tests(
		default_factory=lambda: [
			TestFolderParameter(),
			TestBooleanParameter(),
			TestSelectorParameter(),
			TestFolderListParameter(),
			TestFileParameter(),
			TestFileListParameter(),
			TestNumericParameter(),
			TestMultiSelectorParameter(),
			TestStringParameter(),
		]
	)

Just like name and description on a test config, a group config has the same two fields - shown for the group itself in the execution tree. The field that matters here is tests, declared with OrcraftConfigField.Tests: it's a list of test instances, each one becoming a child node of this group in the execution tree, in the order given.

If you want to remove a test from showing up - and running - under this group, you can just comment out its line in this list, instead of deleting it.

Group class

class TestGroupBasicConfigurationParametersResult(OrcraftTestGroupResult):
	pass


class TestGroupBasicConfigurationParameters(OrcraftTestGroup):
	def __init__(self) -> None:
		super().__init__(config=TestGroupBasicConfigurationParametersConfig())
		self.result = TestGroupBasicConfigurationParametersResult()

Unlike a test, a group has no _run_case to implement - running it simply means running every test it contains. TestGroupBasicConfigurationParametersResult is empty here, since this group doesn't add any result fields of its own beyond what OrcraftTestGroupResult already provides.

Main

def main() -> None:
	group = TestGroupBasicConfigurationParameters()
	group.run()


if __name__ == "__main__":
	main()

Running the group's main runs every test it contains. When we run the group from the controller in the next chapter, the controller creates a separate run for each child test and executes them in parallel.

Basic configuration parameters

Here's a short summary of each test in this group and the parameter type it demonstrates. See Config field types for complete implementation details of each field type.

Test	Field type	What it demonstrates
Folder Parameter	`OrcraftConfigField.Folder`	A single folder path, picked through a folder browser.
Boolean Parameter	`OrcraftConfigField.Boolean`	An on/off toggle, shown as a checkbox.
Selector Parameter	`OrcraftConfigField.Select`	A single choice out of a predefined list of options.
Folder List Parameter	`OrcraftConfigField.FolderList`	Several folder paths at once, held as a list.
File Parameter	`OrcraftConfigField.File`	A single file path, picked through a file browser.
File List Parameter	`OrcraftConfigField.FileList`	Several file paths at once, held as a list.
Numeric Parameter	`OrcraftConfigField.Numeric`	A number, optionally bounded by a minimum and maximum.
Multi-Selector Parameter	`OrcraftConfigField.MultiSelect`	Any number of choices out of a predefined list of options.
String Parameter	`OrcraftConfigField.Text`	Free-form text, typed directly into the field.

Folder Parameter

Covered in detail in the two previous chapters - Adding configuration parameter and Running Folder Parameter test. The test declares a single Maze Executable Folder field and runs the executable found in it.

Boolean Parameter

Adds a Use --help Switch toggle next to the folder field. When it's on, the maze app is run with the --help switch; when off, it's run without it.

Selector Parameter

Adds a Command field offering the maze app's commands - generate, solve and save - as a drop-down, and runs the one selected.

Run example

Here the solve command is selected. The run log records that value in the configuration table, invokes the Maze application with solve, captures its output and finishes with a PASS result:

Orcraft Controller (v0.1.0.dev142)
----------------------------------

                             Test: Selector Parameter | Description                             

Demonstrates a selector configuration parameter.
Presents the available maze app commands as options and runs the maze app with the selected one.


                                                         Test: Selector Parameter | Configuration                                                         

Name                     | Version | Update Endpoint App | Cycles | Case Cycles | Start Time               | Matrix | Maze Executable Folder     | Command
----------------------------------------------------------------------------------------------------------------------------------------------------------
Test: Selector Parameter | -       | on_mismatch         | 1      | 1           | 2026-08-22  21:05:23.478 | -      | C:/Orcraft/Maze/bin/v3.0.0 | solve  


                               Test Cycle 1 | Configuration                          

    Name         | Start Time               | Number Of Cycles | Cycle | Total Cycles
    ---------------------------------------------------------------------------------
    Test Cycle 1 | 2026-08-22  21:05:23.504 | 1                | 1     | 1           

    Running from C:/Orcraft/Maze/bin/v3.0.0:
    	maze-v3.0.0-win solve

    
    Maze App (v3.0.0)
    =================
    
    ---------------------------------------------------------------------------------
    | S |   |           |     →   →   →   ↓ |       |               |               |
    |   |   |   -----   |   |   ---------   |   |   |   ---------   |   ---------   |
    | ↓ |           |       | ↑ | ↓   ← | ↓ |   |       |           |   | →   ↓ |   |
    |   ---------   ---------   |   |   |   |   ---------   ---------   |   |   |   |
    | →   ↓ |   |   |       | ↑ | ↓ | ↑   ← |   |       |           |   | ↑ | →   ↓ |
    -----   |   |   |   |   |   |   ---------   -----   ---------   |   |   -----   |
    |   | ↓ |           |   | ↑ | →   →   ↓ |           | →   ↓ |       | ↑ | ↓   ← |
    |   |   -------------   |   ---------   -------------   |   ---------   |   -----
    |   | →   →   ↓ |       | ↑ |       | →   →   ↓ | →   ↑ | →   →   →   ↑ | ↓ |   |
    |   ---------   ---------   -----   ---------   |   ---------------------   |   |
    |           | ↓ | →   →   ↑ |               | →   ↑ |   |               | ↓ |   |
    |   ---------   |   ---------   ---------   ---------   |   |   -----   |   |   |
    | ↓   ←   ←   ← | ↑   ← |       |       |           |       |       |   | →   ↓ |
    |   -----------------   |   -----   |   ---------   |   ---------   ---------   |
    | ↓ |     →   →   →   ↑ |   |       |               |   |           | ↓   ←   ← |
    |   -----   -------------   ---------   -------------   |   -----   |   ---------
    | →   ↓ | ↑   ← |           |       |   |       |       |       |   | →   →   ↓ |
    -----   -----   |   ---------   |   -----   |   |   ---------   -------------   |
    |     →   →   ↑ |               |           |               |                 E |
    ---------------------------------------------------------------------------------
    
    Path found: 79 step(s) using BFS.
    

                         Test Cycle 1 | Result                     

    Name         | Status | Finish Time              | Elapsed Time
    ---------------------------------------------------------------
    Test Cycle 1 | PASS   | 2026-08-22  21:05:24.152 | 0.648 s     


    Test Cycles | Results

    Test Cycle   | Status
    ---------------------
    Test Cycle 1 | PASS  



                     Test: Selector Parameter | Result                     

Name                     | Status | Finish Time              | Elapsed Time
---------------------------------------------------------------------------
Test: Selector Parameter | PASS   | 2026-08-22  21:05:24.152 | 0.674 s

This is the only run example in this section. We won't repeat the output for every parameter test; try running the remaining tests yourself to see how their selected values appear in the configuration and affect the Maze application's command and output.

Folder List Parameter

Replaces the single folder field with a Maze Executable Folders list, so several version folders can be selected at once. The test loops over them, running the selected command against each maze app version in turn.

File Parameter

Adds a required Maze Save/Load File field, used as the target of the save, load and solve commands - this is where the maze save files we generated earlier come in.

File List Parameter

Takes a Maze Save/Load Files list instead of a single file, running the selected command once per file - for example solving maze.json, maze2.json and maze3.json in one test.

Numeric Parameter

Adds several numeric fields - Width, Height, Seed and the Start/End coordinates - which are passed to the maze app as its generation options. This test also shows how fields are arranged into rows, which only applies to the expanded view - the compact view always lists them one per row.

Multi-Selector Parameter

Adds an Algorithms field where any combination of BFS, DFS and ASTAR can be selected, alongside Solve Switches and Generation Switches fields that pick which switches are passed to the maze app. The test runs it once per selected algorithm.

String Parameter

Adds a free-text Command Line field holding a raw argument string, together with a Use String Command Line toggle that decides whether that string is passed through as-is or the arguments are built from the other fields.

Expanded view

All the screenshots so far in this chapter were taken in compact view - the default. It's a dense layout that fits more fields on screen, which helps with tests that declare many parameters like the String Parameter test above.

The button in the configuration panel's top-right corner switches to the expanded view, where each field is drawn as its own labelled box. Its tooltip names the view you'll switch to - Expanded View while compact, Compact View while expanded - and the choice is remembered for the session. Here's the String Parameter test in the expanded view:

The choice only affects how the panel is drawn - the configuration itself is identical in both views.

Arranging the fields

The order and grouping of fields in the panel isn't decided by the controller - it follows the config class. Fields are laid out in declaration order, and each one can carry a layout hint:

Layout	Effect
(none)	Continues the current row, to the right of the previous field.
`OrcraftConfigField.Layout.NewRow`	Starts a new row.
`OrcraftConfigField.Layout.UnderPrevious`	Places the field directly below the previous one, in the same column.

Here's how the String Parameter test uses them to produce the panel shown above:

	maze_executable_folder = OrcraftConfigField.Folder(
		default="",
		label="Maze Executable Folder",
		required=True,
		layout=OrcraftConfigField.Layout.NewRow,
	)

	maze_file = OrcraftConfigField.File(
		default="",
		label="Maze Save/Load File",
		layout=OrcraftConfigField.Layout.UnderPrevious,
	)

	use_command_line = OrcraftConfigField.Boolean(
		default=True,
		label="Use String Command Line",
		layout=OrcraftConfigField.Layout.NewRow,
	)

	command_line = OrcraftConfigField.Text(
		default="solve --width 20 --height 10 --seed 42 --start 0,0 --end 9,19",
		label="Command Line",
		width=520,
	)

	command = OrcraftConfigField.Select(
		default="solve",
		label="Command",
		options=("generate", "solve", "save", "load"),
		layout=OrcraftConfigField.Layout.NewRow,
	)

	height = OrcraftConfigField.Numeric(default=10, label="Height")
	start_row = OrcraftConfigField.Numeric(default=0, label="Start Row", layout=OrcraftConfigField.Layout.UnderPrevious)
	end_row = OrcraftConfigField.Numeric(default=9, label="End Row", layout=OrcraftConfigField.Layout.UnderPrevious)

	width = OrcraftConfigField.Numeric(default=20, label="Width")
	start_col = OrcraftConfigField.Numeric(default=0, label="Start Col", layout=OrcraftConfigField.Layout.UnderPrevious)
	end_col = OrcraftConfigField.Numeric(default=19, label="End Col", layout=OrcraftConfigField.Layout.UnderPrevious)

	seed = OrcraftConfigField.Numeric(default=42, label="Seed")

The folder and file fields each take a full row of their own. Use String Command Line opens a new row, and Command Line follows it on the same row - which is also why it sets an explicit width. The numeric fields form the grid at the bottom: Height, Start Row and End Row stack into one column, Width starts the next column beside it with Start Col and End Col underneath, and Seed sits on its own.

Next: run the group

Now that we've reviewed every test and parameter type, let's configure and run them together in Running a group.