Maze application

For tutorial purposes, we developed an application to act as a system under test - software under test, in this case - called Maze, which we'll use as the target of the tests we develop throughout this tutorial.

Download

We'll need all three versions later on in this tutorial. Download maze-bin.zip and extract it next to the tutorial repository. It unpacks to a bin folder with a subfolder per version, each holding the Windows, Linux and macOS executable:

bin/
  v1.0.0/
    maze-v1.0.0-win.exe
    maze-v1.0.0-linux
    maze-v1.0.0-macos
  v2.0.0/
    maze-v2.0.0-win.exe
    maze-v2.0.0-linux
    maze-v2.0.0-macos
  v3.0.0/
    maze-v3.0.0-win.exe
    maze-v3.0.0-linux
    maze-v3.0.0-macos

Usage

Run the executable with --help to see its available commands and options:

Maze App (v3.0.0)
=================

USAGE
  maze <command> [options]
  maze -h | --help

COMMANDS
  generate    Generate and print a maze (no solving)
  solve       Generate or load a maze, then solve and print the path
  save        Generate a maze and save it to a JSON file
  load        Load a maze from a JSON file and print it

GENERATION OPTIONS  (generate / solve / save)
  --width   INT       Maze width in columns            (default: 20)
  --height  INT       Maze height in rows              (default: 10)
  --seed    INT       Random seed for reproducibility  (default: random)
  --start   ROW,COL   Start coordinate                 (default: 0,0)
  --end     ROW,COL   End coordinate                   (default: last cell)

SOLVE OPTIONS
  --algorithm NAME    Solver: bfs | dfs | astar        (default: bfs)
  --file    FILE      Load maze from FILE instead of generating

SAVE OPTIONS
  --output  FILE      Output file path                 (default: maze.json)

LOAD OPTIONS
  --file    FILE      Path to a saved maze JSON file   (required)

EXAMPLES
  # Generate and print a 30×15 maze with a fixed seed
  maze generate --width 30 --height 15 --seed 42

  # Solve the same maze using A* (custom start/end)
  maze solve --width 30 --height 15 --seed 42 \
      --start 0,0 --end 14,29 --algorithm astar

  # Save a maze to file, then load and solve it with DFS
  maze save --width 20 --height 10 --seed 7 --output my_maze.json
  maze load --file my_maze.json
  maze solve --file my_maze.json --algorithm dfs

Run examples

Generating a maze

Generate a 20×8 maze with a fixed seed, so it comes out identical on every run:

maze generate --width 20 --height 8 --seed 42

Maze App (v3.0.0)
=================

---------------------------------------------------------------------------------
| S |       |       |       |           |                           |           |
|   |   |   |   |   |   -----   -----   |   -----   -------------   |   -----   |
|   |   |   |   |   |   |           |       |       |   |           |       |   |
|   |   |   |   |   |   |   -----------------   -----   |   -----------------   |
|       |       |   |       |       |           |       |   |           |       |
-----------------   |   -----   |   |   ---------   |   |   |   -----   |   |   |
|           |       |   |       |       |           |   |   |       |       |   |
|   ---------   -----   |   -------------   ---------   |   -----   ---------   |
|               |       |   |               |       |   |       |   |   |       |
|   -------------   -----   |   |   -------------   |   -----   |   |   |   -----
|   |               |       |   |   |           |           |       |   |   |   |
|   -----------------   -----   -----   -----   ---------   ---------   |   |   |
|           |       |   |       |       |   |           |               |   |   |
---------   |   |   |   |   -----   -----   ---------   -----------------   |   |
|               |       |                           |                         E |
---------------------------------------------------------------------------------

The maze is printed as ASCII art, with S marking the start cell and E the end cell.

Solving a maze

Solve that same maze with the A* algorithm:

maze solve --width 20 --height 8 --seed 42 --algorithm astar

Maze App (v3.0.0)
=================

---------------------------------------------------------------------------------
| S | →   ↓ | →   ↓ |       |           |         →   →   →   →   ↓ |           |
|   |   |   |   |   |   -----   -----   |   -----   -------------   |   -----   |
| ↓ | ↑ | ↓ | ↑ | ↓ |   |           |       | →   ↑ |   | ↓   ←   ← |       |   |
|   |   |   |   |   |   |   -----------------   -----   |   -----------------   |
| →   ↑ | →   ↑ | ↓ |       | →   ↓ | →   →   ↑ |       | ↓ | →   →   ↓ | →   ↓ |
-----------------   |   -----   |   |   ---------   |   |   |   -----   |   |   |
|           | ↓   ← |   | →   ↑ | →   ↑ |           |   | ↓ | ↑   ← | →   ↑ | ↓ |
|   ---------   -----   |   -------------   ---------   |   -----   ---------   |
| ↓   ←   ←   ← |       | ↑ |               |       |   | →   ↓ | ↑ |   | ↓   ← |
|   -------------   -----   |   |   -------------   |   -----   |   |   |   -----
| ↓ |               | →   ↑ |   |   |           |           | →   ↑ |   | ↓ |   |
|   -----------------   -----   -----   -----   ---------   ---------   |   |   |
| →   →   ↓ | →   ↓ | ↑ |       |       |   |           |               | ↓ |   |
---------   |   |   |   |   -----   -----   ---------   -----------------   |   |
|         →   ↑ | →   ↑ |                           |                     →   E |
---------------------------------------------------------------------------------

Path found: 77 step(s) using ASTAR.

The solved maze shows the path from start to end as arrows, followed by the number of steps and the algorithm that was used.

Generating maze save files

Later in this tutorial we'll need saved mazes to feed into tests as file parameters. The save command generates a maze and writes it to a JSON file:

maze save --width 20 --height 10 --seed 7 --output maze.json

Maze App (v3.0.0)
=================

---------------------------------------------------------------------------------
| S     |           |           |                                       |       |
-----   -----   |   -----   |   |   -----------------   -----   -----   -----   |
|   |           |           |   |   |               |       |       |   |       |
|   -------------------------   -----   ---------   -----   -----   |   |   |   |
|                       |   |       |   |       |       |   |       |   |   |   |
|   -------------   |   |   -----   |   |   |   -----   |   |   -----   |   |   |
|               |   |   |       |   |   |   |           |   |   |   |   |   |   |
-----   ---------   |   |   |   |   |   -----   -------------   |   |   |   |   |
|       |           |       |   |   |       |       |           |           |   |
|   -----   |   -------------   |   -----   -----   |   -------------------------
|   |   |   |   |           |   |   |       |       |                   |       |
|   |   |   -----   -----   -----   |   ---------   |   -------------   |   |   |
|   |   |       |   |   |   |       |           |   |               |       |   |
|   |   -----   |   |   |   |   -----   -----   |   ---------   -------------   |
|           |   |   |   |   |   |           |   |   |           |       |       |
---------   |   |   |   |   |   -------------   |   -------------   |   |   -----
|   |       |   |   |   |       |               |           |       |   |       |
|   |   -----   |   |   ---------   ---------------------   |   -----   -----   |
|           |                       |                           |             E |
---------------------------------------------------------------------------------

Maze (20×10) saved to 'maze.json'.

Let's create three of them, each with different dimensions and a fixed seed, so everyone following this tutorial ends up with the exact same mazes:

maze save --width 20 --height 10 --seed 7 --output maze.json

maze save --width 30 --height 15 --seed 42 --output maze2.json

maze save --width 40 --height 20 --seed 99 --output maze3.json

Run these from the v3.0.0 folder, so the three files sit next to the executable:

bin/
  v3.0.0/
    maze-v3.0.0-win.exe
    maze.json
    maze2.json
    maze3.json

A saved maze can be printed again with load, or solved with solve --file, without regenerating it:

maze load --file maze.json

maze solve --file maze.json --algorithm dfs