🕵️ Debug Tools#

Debugging is a fundamental aspect of software development. Bookshelf provides tools to help identify and resolve issues effectively.

🧪 Unit Tests#

Tests are essential for ensuring code correctness and preventing future bugs. This project uses Misode’s Minecraft Fabric mod, PackTest, for testing.

⚙️ Running Tests#

To run the tests, you have two options:

  1. Headless Mode: We provide a simple command pdm run modules test that allows you to run the tests headlessly, without having to open the game

  2. In-Game: Download and install the Minecraft Fabric mod. Once that’s done, you can run the tests using the test command in Minecraft

Java Required

Ensure that Java is installed on your system, as it is required for the command to work.

✍️ Writing Tests#

Each test is a .mcfunction file inside the test folder. When writing tests, make sure to clearly define what you are testing and what the expected outcome is. It’s also a good idea to include edge cases to ensure your code can handle all possible inputs.

🛠️ Custom Commands#

PackTest offers a variety of commands to control test flow, validate conditions, and interact with Minecraft’s environment:

Test Flow Commands:

  • fail [<text>]: Immediately fails the current test and logs an optional message

  • succeed: Immediately passes the current test

  • assert <condition>: Fails the test if the condition is false

  • assert not <condition>: Fails the test if the condition is true

  • await <condition>: Continuously checks a condition until it succeeds or times out

  • await not <condition>: Waits until the condition becomes false

  • await delay <time>: Pauses the test for a specified duration

Condition Types:

  • block <pos> <block>: Checks if a block at the specified position matches the given block

  • data <path>: Verifies NBT data using standard Minecraft data syntax

  • entity <selector>: Validates if entities match a selector (works beyond test boundaries)

  • predicate <predicate>: Executes a predicate in the data pack

  • score <target>: Compares scores using Minecraft’s score-based conditions

  • chat <pattern> [<receivers>]: Matches chat messages against a regex pattern

🧍 Player Dummies#

PackTest allows you to spawn and control “dummies,” simulated players for testing:

  • dummy <name> spawn: Spawns a new dummy

  • dummy <name> respawn: Respawns the dummy after it has been killed

  • dummy <name> leave: Makes the dummy leave the server

  • dummy <name> jump: Makes the dummy jump

  • dummy <name> sneak [true|false]: Makes the dummy hold shift or un-shift (not the same as currently crouching)

  • dummy <name> sprint [true|false]: Makes the dummy sprint or un-sprint

  • dummy <name> drop [all]: Makes the dummy drop the current mainhand, either one item or the entire stack

  • dummy <name> swap: Makes the dummy swap its mainhand and offhand

  • dummy <name> selectslot: Makes the dummy select a different hotbar slot

  • dummy <name> use item: Makes the dummy use its hand item, either mainhand or offhand

  • dummy <name> use block <pos> [<direction>]: Makes the dummy use its hand item on a block position

  • dummy <name> use entity <entity>: Makes the dummy use its hand item on an entity

  • dummy <name> attack <entity>: Makes the dummy attack an entity with its mainhand

  • dummy <name> mine <pos>: Makes the dummy mine a block

📋 Test Directives#

You can customize tests using directives (special comments at the beginning of the test):

  • @template: The resource location of a structure template to use for the test, defaults to minecraft:empty, which is an empty 1×1×1 structure

  • @timeout: An integer specifying the timeout, defaults to 100

  • @optional: Whether this test is allowed to fail, defaults to false, if there is no value after the directive it is considered as true

  • @skyaccess: Whether this test needs sky access, defaults to false, which will place barrier blocks above the test

  • @dummy: Whether to spawn a dummy at the start of the test and set @s to this dummy, taking a position which defaults to ~0.5 ~ ~0.5

Learn more…

If you need more information than this page provides, visit Misode’s repository for detailed guidance on writing tests.

📦 Modules#

Bookshelf includes a variety of modules designed to enhance your development experience.

📄 Logging#

Centralizes and streamlines log management, making it easier to monitor and troubleshoot your project. For more details, refer to the log module documentation.

🔬 Var Dumping#

Provides an easy way to display scores or storage values at any given time, helping with debugging and tracking. For more details, refer to the dump module documentation.