Add MazeGenerator exercise and related tests (#2355)

* Add MazeGenerator exercise and related tests

This commit introduces a new MazeGenerator class along with related Units Tests. It also adds the `Dimensions` record to represent the size of the maze. Both MazeGenerator and Dimensions classes are incorporated into the build.gradle file. For testing purposes, MazeGeneratorTest along with its configuration file and a test reference were incorporated.

This change allows generating perfect mazes of a specified size with a single correct path, ideal for maze navigation tasks. Can produce random mazes or reproducible ones when provided with a seed. The mazes are represented using box-drawing characters and the entrances/exits are denoted by an arrow symbol(⇨).

* Update exercises/practice/mazy-mice/src/main/java/MazeGenerator.java

Co-authored-by: Sander Ploegsma <[email protected]>

* Update exercises/practice/mazy-mice/src/main/java/MazeGenerator.java

Co-authored-by: Sander Ploegsma <[email protected]>

* Update mazy-mice exercise metadata configuration

The config.json file for the mazy-mice exercise has been improved to include the new 'invalidator' field. This field references the build.gradle file which is used for the construction and testing of the 'MazeGenerator' example. With this addition, users are now able to work with the MazeGenerator class and its related unit tests in their local environment with ease.

* Improve grammar in mazy-mice exercise instructions

Minor grammatical correction has been made in the mazy-mice exercise documentation. Prior sentences were changed from "The small square maze" and "The rectangular maze" to "A small square maze" and "A rectangular maze" respectively, to improve sentence flow and clarity for users.

* Update placeholder in hints.md

The placeholder comment in the 'hints.md' file for the mazy-mice exercise has been replaced with the 'Hints' header. This change is essential for creating a more meaningful start to the document and improving the clarity for users trying to understand maze generation.

* Refactor test method name for clarity

The test method name 'the_dimensions_are_correct' in MazeGeneratorTest has been refactored to 'theDimensionsAreCorrect'. This is in line with Java's camelCase naming convention, improving readability and maintaining a consistent code style.

* Update test method name to reflect logical assertion

Updated the name of the test method in MazeGeneratorTest from 'twoMazesShouldNotBeEqual' to 'aMazeIsDifferentEachTimeItIsGenerated'. The new name better indicates the purpose of the test, which is to check that every maze generated is unique.

* Add 'mazy-mice' to settings.gradle

Included 'practice:mazy-mice' in the settings.gradle to extend the diversity of exercises. This step is necessary for building and running the 'mazy-mice' exercise.

* Add new "mazy-mice" exercise to config.json

A new exercise named "mazy-mice" has been added to config.json. This exercise, which involves character arrays and string handling with for-loops, is intended to diversify the exercise list and give users more exercise choices. The difficulty of this exercise has been set to 8.

* Refactor maze generation and test methods for readability

The methods for maze generation have been refactored to directly accept individual parameters for 'rows' and 'columns' instead of a 'Dimensions' object. This change simplifies the method calls and enhances code readability. Also, updated the corresponding test cases to adhere to the new method signature. Additionally, added enumeration for directions at the end of the test class to improve code organization and readability.

* Add descriptions to auto-generated test cases

An auto-generated 'tests.toml' file is introduced. The descriptions added provide information for each test key about the attributes and functionality that is being tested. These include correct dimensions, valid characters, proper locations of entrances and exits, and generation of mazes with or without a seed parameter. These descriptions help developers understand the purpose of the tests and correct functioning of the maze.

Also, change method names and orders to make the test easier to follow. This allows the clearer reading of the tests, thus increasing productivity. It helps maintainers to spot and understand the new changes faster and easier. Minor changes, such as capitalisation corrections, are also made for improved readability.

* Change access modifier for test methods in MazeGeneratorTest

This commit changes the access modifier of all test methods in the `MazeGeneratorTest` class from default to public.

This necessary change, switching to public, allows JUnit to access the test methods. Previously, due to default access level it could cause issues with the test runner and result in no tests being executed. Access modifiers were also applied to the `setup` method to ensure it properly annotated before each test run. Making these methods public improves test functionality and ensures they are recognized as legitimate JUnit tests.

* Add additional hints for exercise in hints.md

This commit adds important hints in the hints.md file for the 'mazy-mice' exercise. It introduces useful general information regarding the generation of random numbers in Java 17 including links to valuable resources. This could help participants to understand better how to deal with random numbers and thus can improve the exercise's learning objectives.

* Add a new test for seeded maze generator

This commit added a new test case to the MazeGeneratorTest file. The added test, "theMazeIsPerfectWithSeed", simulates a perfect maze generation with a predefined seed. This test aims to help to ensure that the maze generator can correctly use seed to produce the expected unique maze structure. This also enhances the test coverage and further ensures the robustness of the maze generating code.

* Add tests for maze size validation

In this commit, 4 new tests have been added to the MazeGeneratorTest in order to check the validity of size parameters passed to the 'generatePerfectMaze' function. These tests ensure that both rows and columns parameters are within acceptable range (5-100) by throwing an IllegalArgumentException if they are not.

* Add maze dimensions validation to the MazeGenerator class

Dimension validation methods have been included in the maze generation methods of the MazeGenerator class. This is to ensure that the rows and columns of the maze are within an acceptable range (5-100). If these values fall out of the given range, an IllegalArgumentException is thrown. This was introduced to prevent the generation of mazes that would be too small or too big, which could lead to performance issues or unplayable mazes.

* Revise header formatting in instructions.md

The heading formatting in the instructions.md document within the mazy-mice exercise directory has been revised. The markdown format was adjusted from using "##" to make it a sub-heading, to "#" to make it a top level heading. This change has been implemented for clarity and readability, making it easier for users to understand the structure of the document.

* Remove redundant .meta/tests.toml file

* delete version file

* Remove Dimensions.java as its functionality is redundant

The file Dimensions.java was deleted because its purpose - to represent the dimensions of a maze - is already covered by another class in our program. Its functionality including width and height calculations, which were previously done in cells, are now handled elsewhere, making this file unnecessary.

* Update exercises/practice/mazy-mice/src/test/java/MazeGeneratorTest.java

Co-authored-by: Sander Ploegsma <[email protected]>

* Update exercises/practice/mazy-mice/src/test/java/MazeGeneratorTest.java

Co-authored-by: Sander Ploegsma <[email protected]>

* Update config.json to include new practices

Added "strings" and "for-loops" to the "practices" array in the config.json file. This change is necessary to ensure all necessary learning concepts are being covered within the curriculum.

* Add new game "Mazy Mice" in config.json

The new game "Mazy Mice" with corresponding uuid, practices, prerequisites, and difficulty level was added to the config.json. This is essential for including a new game in the curriculum that emphasizes the application of "strings" and "for-loops" practices.

* Add Dimensions.java to Mazy Mice example files

Included "Dimensions.java" in the example files array for the "Mazy Mice" problem in config.json, as it is needed for the correct generation of the maze. Not including this could lead to errors or incomplete solutions.

* Remove redundant mazeNotNull test in MazeGeneratorTest class

The mazeIsNotNull test in MazeGeneratorTest class was removed as it was deemed unnecessary and redundant. The null check is already implicitly covered in the subsequent dimensions and valid characters tests.

* Refactor MazeGeneratorTest for better test organization

Moved `Direction` enum to the top of the MazeGeneratorTest class to improve code organization and readability. Adjusted dimensions test to use Arrays.stream for enhanced test flow and comprehension. Removed redundant mazeNotNull test.

* Add status field to config.json

---------

Co-authored-by: Sander Ploegsma <[email protected]>

Author: Jegors Čemisovs

config.json

@@ -1983,6 +1983,23 @@
           "numbers"
         ],
         "difficulty": 3
+      },
+      {
+        "slug": "mazy-mice",
+        "name": "Mazy Mice",
+        "uuid": "1bac7473-9ee8-4cfc-928b-77792102ffc1",
+        "practices": [
+          "chars",
+          "strings",
+          "for-loops",
+          "arrays"
+        ],
+        "prerequisites": [
+          "strings",
+          "for-loops"
+        ],
+        "difficulty": 8,
+        "status": "beta"
       }
     ]
   },

exercises/practice/mazy-mice/.docs/hints.md

@@ -0,0 +1,30 @@
+# Hints
+
+## General
+
+-   You can use the [Random class][random-class] to generate random numbers.
+-   Read more in article: [Random Number Generators in Java 17][random-number-generators].
+
+## Maze generation
+
+You can use any algorithm to generate a perfect maze. The [recursive backtracker][recursive-backtracker] is a good choice.
+
+## Box drawing characters
+
+| Character | Name                                  | Unicode |
+|:---------:|:--------------------------------------|:--------|
+|     ┌     | box drawings light down and right     |  U+250C |
+|     ─     | box drawings light horizontal         |  U+2500 |
+|     ┬     | box drawings light down and horizontal|  U+252C |
+|     ┐     | box drawings light down and left      |  U+2510 |
+|     │     | box drawings light vertical           |  U+2502 |
+|     └     | box drawings light up and right       |  U+2514 |
+|     ┴     | box drawings light up and horizontal  |  U+2534 |
+|     ┘     | box drawings light up and left        |  U+2518 |
+|     ├     | box drawings light vertical and right |  U+2520 |
+|     ⇨     | rightwards white arrow                |  U+21E8 |
+
+
+[recursive-backtracker]: https://en.wikipedia.org/wiki/Maze_generation_algorithm
+[random-class]: https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Random.html
+[random-number-generators]: https://www.baeldung.com/java-17-random-number-generators

exercises/practice/mazy-mice/.docs/instructions.md

@@ -0,0 +1,48 @@
+# Instructions
+
+Your task is to generate the perfect mazes for Mickey and Minerva — those with only one solution and no isolated sections.
+Here's what you need to know:
+
+- The maze has a rectangular shape with an opening at the start and end.
+- The maze has rooms and passages, which intersect at right angles.
+- The program should accept two parameters: rows and columns. The maze should be between 5 and 100 cells in size.
+- A maze which is `x` columns wide and `y` rows high should be `2x + 1` characters wide and `2y + 1` characters high.
+- If no seed is provided, generate a random maze. If the same seed is provided multiple times, the resulting maze should be the same each time.
+- Use [box-drawing][Box-drawing] characters to draw walls, and an arrow symbol (⇨) for the entrance on the left and exit on the right.
+
+It's time to create some perfect mazes for these adventurous mice!
+
+### Examples
+
+1. A small square maze 5x5 cells (or 11x11 characters)
+```text
+	┌───────┬─┐
+	│       │ │
+	│ ┌─┬── │ │
+	│ │ │   │ ⇨
+	│ │ │ ──┤ │
+	⇨ │ │   │ │
+	┌─┤ └── │ │
+	│ │     │ │
+	│ │ ────┘ │
+	│         │
+	└─────────┘
+```
+2. A rectangular maze 6x18 cells
+```text
+	┌───────────┬─────────┬───────────┬─┐
+	│           │         │           │ │
+	│ ┌───────┐ │ ┌─┐ ──┐ └───┐ ┌───┐ │ │
+	│ │       │ │ │ │   │     │ │   │   ⇨
+	│ └─┐ ┌─┐ │ │ │ ├── ├───┐ │ │ ──┼── │
+	│   │ │ │   │   │   │   │ │ │   │   │
+	└── │ │ ├───┴───┤ ┌─┘ ┌─┘ │ ├── │ ──┤
+	⇨   │   │       │ │   │   │ │   │   │
+	┌─┬─┴─┐ └─┐ ┌─┐ │ └─┐ │ ┌─┘ │ ──┴─┐ │
+	│ │   │   │ │ │ │   │   │   │     │ │
+	│ │ │ └── │ │ │ └── │ ──┘ ┌─┘ ──┐ │ │
+	│   │       │       │     │     │   │
+	└───┴───────┴───────┴─────┴─────┴───┘
+```
+
+[Box-drawing]: https://en.wikipedia.org/wiki/Box-drawing_character

exercises/practice/mazy-mice/.docs/introduction.md

@@ -0,0 +1,3 @@
+# Introduction
+
+Meet Mickey and Minerva, two clever mice who love to navigate their way through a maze to find cheese. They enjoy a good challenge, but with only their tiny mouse brains, they prefer if there is only one correct path to the cheese.

exercises/practice/mazy-mice/.meta/config.json

@@ -0,0 +1,23 @@
+{
+  "authors": [
+    "rabestro"
+  ],
+  "files": {
+    "solution": [
+      "src/main/java/MazeGenerator.java"
+    ],
+    "test": [
+      "src/test/java/MazeGeneratorTest.java"
+    ],
+    "example": [
+      ".meta/src/reference/java/MazeGenerator.java",
+      ".meta/src/reference/java/Dimensions.java"
+    ],
+    "invalidator": [
+      "build.gradle"
+    ]
+  },
+  "blurb": "Meet Mickey and Minerva, two clever mice who love to navigate their way through a maze to find cheese. They enjoy a good challenge, but with only their tiny mouse brains, they prefer if there is only one correct path to the cheese.",
+  "source": "Inspired by the 'Maze Generator' created by Jan Boström at Alance AB.",
+  "source_url": "https://mazegenerator.net/"
+}

exercises/practice/mazy-mice/.meta/src/reference/java/Dimensions.java

@@ -0,0 +1,25 @@
+/**
+ * Represents the dimensions of a maze.
+ * <p>
+ * Dimensions of a grid can be represented in cells or characters.
+ * Rows and columns are used for cells, while width and height are used for characters.
+ */
+public record Dimensions(int rows, int columns) {
+    /**
+     * Returns the width of the maze in characters.
+     *
+     * @return the width of the maze
+     */
+    int width() {
+        return 2 * columns + 1;
+    }
+
+    /**
+     * Returns the height of the maze in characters.
+     *
+     * @return the height of the maze
+     */
+    int height() {
+        return 2 * rows + 1;
+    }
+}

exercises/practice/mazy-mice/.meta/src/reference/java/MazeGenerator.java

@@ -0,0 +1,185 @@
+import java.util.Random;
+import java.util.random.RandomGenerator;
+import java.util.BitSet;
+import java.util.EnumSet;
+import java.util.Set;
+
+import static java.util.stream.IntStream.range;
+
+public class MazeGenerator {
+
+    public char[][] generatePerfectMaze(int rows, int columns) {
+        validateDimensions(rows, columns);
+        return new Grid(new Dimensions(rows, columns), RandomGenerator.getDefault())
+                .generateMaze()
+                .placeDoors()
+                .print();
+    }
+
+    public char[][] generatePerfectMaze(int rows, int columns, int seed) {
+        validateDimensions(rows, columns);
+        return new Grid(new Dimensions(rows, columns), new Random(seed))
+                .generateMaze()
+                .placeDoors()
+                .print();
+    }
+
+    private void validateDimensions(int rows, int columns) {
+        if (rows < 5 || columns < 5 || rows > 100 || columns > 100) {
+            throw new IllegalArgumentException("Dimensions must be in range.");
+        }
+    }
+}
+
+enum Direction {
+    NORTH(0, 1),
+    EAST(1, 0),
+    SOUTH(0, -1),
+    WEST(-1, 0);
+    private final int dx;
+    private final int dy;
+
+    Direction(int dx, int dy) {
+        this.dx = dx;
+        this.dy = dy;
+    }
+
+    public int dx() {
+        return dx;
+    }
+
+    public int dy() {
+        return dy;
+    }
+}
+
+final class Grid {
+    private final Dimensions dimensions;
+    private final BitSet grid;
+    private final RandomGenerator randomGenerator;
+
+    Grid(Dimensions dimensions, RandomGenerator randomGenerator) {
+        this.dimensions = dimensions;
+        this.grid = new BitSet(dimensions.width() * dimensions.height());
+        this.randomGenerator = randomGenerator;
+    }
+
+    Grid generateMaze() {
+        generate(new Cell(1, 1));
+        return this;
+    }
+
+    private int random(int bound) {
+        return randomGenerator.nextInt(bound);
+    }
+
+    private Direction pickRandomDirection(Set<Direction> directions) {
+        int size = directions.size();
+        int itemIndex = random(size);
+        var direction = directions.toArray(new Direction[size])[itemIndex];
+        directions.remove(direction);
+        return direction;
+    }
+
+    Grid placeDoors() {
+        new Cell(1 + 2 * random(dimensions.rows()), 0).erase();
+        new Cell(1 + 2 * random(dimensions.rows()), dimensions.width() - 1).erase();
+        return this;
+    }
+
+    private void generate(Cell cell) {
+        cell.erase();
+
+        var directions = EnumSet.allOf(Direction.class);
+        do {
+            var direction = pickRandomDirection(directions);
+            var wall = cell.move(direction);
+            var next = wall.move(direction);
+            if (next.isValid() && next.isNotEmpty()) {
+                wall.erase();
+                generate(next);
+            }
+        } while (!directions.isEmpty());
+    }
+
+    char[][] print() {
+        return range(0, dimensions.height())
+                .mapToObj(this::line)
+                .toArray(char[][]::new);
+    }
+
+    private char[] line(int x) {
+        return range(0, dimensions.width())
+                .map(y -> new Cell(x, y).symbol())
+                .collect(StringBuilder::new, StringBuilder::appendCodePoint, StringBuilder::append)
+                .toString()
+                .toCharArray();
+    }
+
+    private final class Cell {
+        final int x;
+        final int y;
+
+        private Cell(int x, int y) {
+            this.x = x;
+            this.y = y;
+        }
+
+        boolean isValid() {
+            return x > 0 && x < dimensions.height() && y > 0 && y < dimensions.width();
+        }
+
+        void erase() {
+            grid.set(index());
+        }
+
+        boolean isNotEmpty() {
+            return !isEmpty();
+        }
+
+        boolean isEmpty() {
+            return grid.get(index());
+        }
+
+        int index() {
+            return x * dimensions.width() + y;
+        }
+
+        boolean isDoor() {
+            return isEmpty() && (y == 0 || y == dimensions.width() - 1);
+        }
+
+        Cell move(Direction direction) {
+            return new Cell(x + direction.dx(), y + direction.dy());
+        }
+
+        char symbol() {
+            if (isDoor()) {
+                return '⇨';
+            }
+            if (isEmpty()) {
+                return ' ';
+            }
+            var n = x > 0 && new Cell(x - 1, y).isNotEmpty() ? 1 : 0;
+            var e = y < dimensions.width() - 1 && new Cell(x, y + 1).isNotEmpty() ? 1 : 0;
+            var s = x < dimensions.height() - 1 && new Cell(x + 1, y).isNotEmpty() ? 1 : 0;
+            var w = y > 0 && new Cell(x, y - 1).isNotEmpty() ? 1 : 0;
+            var i = n + 2 * e + 4 * s + 8 * w;
+            return switch (i) {
+                case 0 -> ' ';
+                case 1, 5, 4 -> '│';
+                case 2, 8, 10 -> '─';
+                case 3 -> '└';
+                case 6 -> '┌';
+                case 7 -> '├';
+                case 9 -> '┘';
+                case 11 -> '┴';
+                case 12 -> '┐';
+                case 13 -> '┤';
+                case 14 -> '┬';
+                case 15 -> '┼';
+                default -> throw new IllegalStateException("Unexpected value: " + i);
+            };
+        }
+    }
+}

exercises/practice/mazy-mice/build.gradle

@@ -0,0 +1,24 @@
+apply plugin: "java"
+apply plugin: "eclipse"
+apply plugin: "idea"
+
+// set default encoding to UTF-8
+compileJava.options.encoding = "UTF-8"
+compileTestJava.options.encoding = "UTF-8"
+
+repositories {
+  mavenCentral()
+}
+
+dependencies {
+  testImplementation "junit:junit:4.13"
+  testImplementation "org.assertj:assertj-core:3.15.0"
+}
+
+test {
+  testLogging {
+    exceptionFormat = 'full'
+    showStandardStreams = true
+    events = ["passed", "failed", "skipped"]
+  }
+}

exercises/practice/mazy-mice/src/main/java/MazeGenerator.java

@@ -0,0 +1,10 @@
+public class MazeGenerator {
+
+    public char[][] generatePerfectMaze(int rows, int columns) {
+        throw new UnsupportedOperationException("Delete this statement and write your own implementation.");
+    }
+
+    public char[][] generatePerfectMaze(int rows, int columns, int seed) {
+        throw new UnsupportedOperationException("Delete this statement and write your own implementation.");
+    }
+}