Place and run every test matching a selector.
An exact id such as mypack:my_test, or a pattern: mypack:* matches every test in the namespace and * matches everything.
Leave empty to run once. With the checkbox on, the run stops at the first failure instead of completing every repeat.
Rotation steps turns each placed test by 90 degrees per step (0 to 3). Tests per row controls the grid layout when many tests are placed.
Places fresh copies of every matching test and runs them. Needs permission level 2 (gamemasters): an operator on a server, or a singleplayer world with cheats on.
A test is a saved structure plus pass and fail conditions. You create the area once, build inside it, save it through the test instance block, then run it as often as you like. A typical session:
/test is the in-game control panel for Minecraft's GameTest framework. One command places automated test structures in the world, runs them once or hundreds of times, points you at failures, resets the structures and cleans them up again, so a contraption can be re-checked automatically after every change.
A GameTest is a saved structure paired with pass and fail conditions. Mojang has used thousands of them internally for years to make sure farms, redstone and mob behavior still work after each game update; Java Edition 1.21.5 opened the same machinery to everyone. Tests live in data packs as test instances (under data/<namespace>/test_instance), each referencing a structure, a test environment and the conditions that decide success. In the world they appear as a test instance block with a bounding box around the build.
For mapmakers and data pack authors this is regression testing without leaving the game: build a piston door, an item sorter or a command chain once as a test, and one /test runthese tells you whether everything still works after you touched the wiring. The command requires permission level 2: an operator on a server, or a singleplayer world with cheats enabled.
Arguments in [brackets] are optional and fill left to right: each optional argument needs every one before it, which the generator above handles for you. A <tests> selector accepts an exact id like mypack:my_test or a wildcard pattern like mypack:* and *.
The repeat arguments mean the same thing everywhere: times is how often to run, untilFailed stops the repeats at the first failure when true, rotationSteps turns the placed test in 90 degree steps and testsPerRow controls the grid layout when many tests are placed at once.
Places a test instance block with an empty 7 by 5 by 7 test area, ready for you to build the contraption and wire up test blocks. The id mypack:piston_door is how every other subcommand finds the test afterwards.
Places the piston door test and runs it up to five times, stopping at the first failure. Drop the trailing arguments to run it once.
Runs every placed test within 200 blocks of where you stand. The fastest way to re-check a whole wall of tests after a change.
Runs every test in the mypack namespace 100 times in each of the four rotations. Use it before publishing a map or data pack to catch tests that only pass sometimes.
Removes every placed test structure within 64 blocks, cleaning the area up once a test session is done.
You do not need to write a single line of code for a block-based test; the whole loop happens in game:
1. Run /test create mypack:my_test 7 5 7 (the generator above builds any size). This places a test instance block and marks out an empty 7 by 5 by 7 area.
2. Build the contraption inside the bounds. Everything inside the box becomes part of the test's structure.
3. Add test blocks: a Start block fires a redstone pulse when the test begins, an Accept block marks the test as passed when it is triggered, a Fail block marks it as failed, and a Log block writes a message. A test that never reaches an Accept block fails on timeout.
4. Open the test instance block and save the structure. The test is now a normal part of your world and shows up for /test run, locate and verify.
5. Iterate: run with /test runthat while looking at it, restore the structure with /test resetthat after a messy run, and finish with /test verify before you ship the map or data pack.
For more advanced cases, function-type test instances in a data pack can run command functions against the structure, which pairs naturally with the /function command for setup and assertions.
It controls the GameTest framework from inside the game. /test places automated test structures in the world, runs them once or hundreds of times, locates placed instances, resets their structures and clears them away. Each test is a saved structure plus pass and fail conditions, so you can re-check a contraption automatically after every change instead of testing it by hand.
Java Edition 1.21.5. That update opened up the GameTest framework Mojang uses to test the game itself, adding the /test command together with the test block and the test instance block. On older versions the command does not exist, which is why the version picker on this page starts at 1.21.5.
Three usual causes: the world runs a version older than 1.21.5, you are missing permission level 2 (enable cheats in singleplayer or get operator status on a server), or the subcommand is missing a required argument, such as the test selector after /test run.
Run /test create with a new id, for example /test create mypack:my_test 7 5 7. That places a test instance block and an empty test area. Build your contraption inside the bounds, add test blocks to start the test and to register success or failure, save the structure through the test instance block, then run it with /test run mypack:my_test.
/test run executes the matching tests once, or as many times as you pass in the optional arguments. /test verify is the stress version: it runs each matching test 100 times in each of the four rotations, which exposes flaky tests that only pass when facing one direction or when timing happens to line up.
No. The /test command is Java Edition only. Bedrock has a separate GameTest system reached through its /gametest command behind the Beta APIs experimental toggle, with different syntax and script-based tests.
Wiring tests into a data pack? Or browse more Minecraft tools:
