Game Tests

The GameTest framework requires you to activate “Enable GameTest Framework” in your world settings and you must be using Minecraft 1.16.210.60 beta or above

GameTests are a new feature which allow developers to create unit tests to make it easier to test if game mechanics work. They are created with javascript files in the behavior pack folder and each file can register multiple GameTests. Each GameTest must also have an .mcstructure file in the BP/structures folder.

It is recommended that your GameTests go in the BP/scripts/gametests directory.

Type declaration files for the GameTest API

Table of contents

Using GameTests

In the behavior pack manifest you need to add a javascript module where you set an entry point for your GameTests.

BP/manifest.json

{
    "format_version": 2,
    "header": {
        "name": "Pack Name",
        "description": "Pack descripton",
        "min_engine_version": [
            1,
            16,
            210
        ],
        "uuid": "604420b9-f4c3-4df2-9f09-4364486f1195",
        "version": [
            1,
            0,
            0
        ]
    },
    "modules": [
        {
            "description": "",
            "type": "data",
            "uuid": "42651ba5-6619-4547-9d48-84a5a37cf2a3",
            "version": [
                1,
                0,
                0
            ]
        },
        {
            "description": "",
            "uuid": "239c134f-67bf-4738-9bcc-8c69d31b1f72",
            "version": [
                1,
                0,
                0
            ],
            "type": "javascript",
            "entry": "scripts/gametests/Main.js"
        }
    ],
    "dependencies": [
      {
      // Minecraft native module - needed to use the "Minecraft" module
      "uuid": "b26a4d4c-afdf-4690-88f8-931846312678",
      "version": [ 0, 1, 0 ]
    },
    {
      // GameTest native module - needed to use the "GameTest" module
      "uuid": "6f4b6893-1bb6-42fd-b458-7fa3d0c89616",
      "version": [ 0, 1, 0 ]
    }
    ]
}

The entry point should link to a file containing imports to your GameTest files.

BP/scripts/gametests/Main.js

import "scripts/gametests/MyGameTest.js";
import "scripts/gametests/OtherGameTest.js"

GameTests can be used with the /gametest command.

• /gametest runthis

Runs the nearest GameTest in range.

• /gametest runthese

Runs all GameTests in range.

• /gametest pos

Tells you the relative coordinates of the nearest GameTest.

• /gametest clearall [radius: int]

Removes all GameTests in the specified radius.

• /gametest run <testName: GameTestName> [rotationSteps: int]

Creates and runs the specified GameTest.

• /gametest runset [tagTag: GameTestTag] [rotationSteps: int]

Creates and runs all GameTests with the specified tag.

• /gametest create <testName: string> [width: int] [height: int] [depth: int]

Creates a blank GameTest area with the specified dimensions.

Complete examples

// Structure Path: BP/structures/MinecartTests/turn.mcstructure

import * as GameTest from "GameTest";
import { BlockLocation } from "Minecraft";

GameTest.register("MinecartTests", "turn", (test) => {
  const minecartActorType = "minecart";

  const endPos = new BlockLocation(1, 2, 2);
  const startPos = new BlockLocation(1, 2, 0);

  test.assertEntityPresent(minecartActorType, startPos);
  test.assertEntityNotPresent(minecartActorType, endPos);

  test.pressButton(new BlockLocation(0, 3, 0));

  test.succeedWhenEntityPresent(minecartActorType, endPos);
}).tag(GameTest.Tags.suiteDefault);

// Structure Path: BP/structures/DoorTests/four_villagers_one_door.mcstructure

import * as GameTest from "GameTest";
import { BlockLocation } from "Minecraft";

GameTest.register("DoorTests", "four_villagers_one_door", (test) => {
  const villagerActorType = "minecraft:villager_v2";
  const villagerActorSpawnType =
    "minecraft:villager_v2<minecraft:spawn_farmer>"; // Attempt to spawn the villagers as farmers

  test.spawn(villagerActorSpawnType, new BlockLocation(5, 2, 4));
  test.spawn(villagerActorSpawnType, new BlockLocation(4, 2, 5));
  test.spawn(villagerActorSpawnType, new BlockLocation(2, 2, 5));
  test.spawn(villagerActorSpawnType, new BlockLocation(1, 2, 4));

  test.succeedWhen(() => {
    test.assertEntityPresent(villagerActorType, new BlockLocation(5, 2, 2));
    test.assertEntityPresent(villagerActorType, new BlockLocation(5, 2, 1));
    test.assertEntityPresent(villagerActorType, new BlockLocation(1, 2, 2));
    test.assertEntityPresent(villagerActorType, new BlockLocation(1, 2, 1));
  });
})
  .tag(GameTest.Tags.suiteDefault)
  .padding(50) // Space out villager tests to stop them from confusing each other
  .batch("night") // This should be a constant at some point
  .maxTicks(600);

Modules

Namespace: “GameTest”

Variables

Tags

• Const Tags: Tags

Functions

register

▸ register(namespace: string, identifier: string, func: (test: Test) => void): TestRunner

Registers a GameTest into Minecraft

Parameters:

Returns: TestRunner

Namespace: “Minecraft”

Variables

BlockLocation

• Const BlockLocation: BlockLocationClass

BlockStates

• Const BlockStates: BlockStates

Blocks

• Const Blocks: Blocks

ItemStack

• Const ItemStack: ItemStackClass

Interfaces

Interface: Block

Methods

setState

▸ setState(state: State): Block

Parameters:

Returns: Block

Interface: BlockLocation

Methods

above

▸ above(): BlockLocation

Returns the block position it was called on but increases the y coordinate by 1

Returns: BlockLocation

Interface: BlockLocationClass

Constructors

constructor

+ new BlockLocation(x: number, y: number, z: number): BlockLocation

Creates a block position

Parameters:

Returns: BlockLocation

Interface: Blocks

Methods

Contains a method for every vanilla block. Every method is in camelCase. Example:

▸ air(): Block

get

▸ get(id: string): Block

Fetches the requested block and returns it, if the block doesn’t exist, this returns null

Parameters:

Returns: Block

Interface: BlockStates

Methods

Contains a method for every block state. Every method is in camelCase. Example:

▸ topSlotBit(data: boolean): State

Interface: Commands

Methods

run

▸ run(command: string): void

Runs the given command when called

Parameters:

Returns: void

Interface: Dimension

Interface: Effect

Methods

getAmplifier

▸ getAmplifier(): any

Gets the effect’s amplifier level

Returns: any

getDuration

▸ getDuration(): any

Gets the effect’s remaining duration in ticks

Returns: any

Interface: Effects

Methods

absorption

▸ absorption(): Effect

Returns: Effect

badOmen

▸ badOmen(): Effect

Returns: Effect

blindness

▸ blindness(): Effect

Returns: Effect

conduitPower

▸ conduitPower(): Effect

Returns: Effect

fatalPoison

▸ fatalPoison(): Effect

Returns: Effect

fireResistance

▸ fireResistance(): Effect

Returns: Effect

haste

▸ haste(): Effect

Returns: Effect

healthBoost

▸ healthBoost(): Effect

Returns: Effect

heroOfTheVillage

▸ heroOfTheVillage(): Effect

Returns: Effect

hunger

▸ hunger(): Effect

Returns: Effect

instantDamage

▸ instantDamage(): Effect

Returns: Effect

instantHealth

▸ instantHealth(): Effect

Returns: Effect

invisibility

▸ invisibility(): Effect

Returns: Effect

jumpBoost

▸ jumpBoost(): Effect

Returns: Effect

levitation

▸ levitation(): Effect

Returns: Effect

miningFatigue

▸ miningFatigue(): Effect

Returns: Effect

nausea

▸ nausea(): Effect

Returns: Effect

nightVision

▸ nightVision(): Effect

Returns: Effect

poison

▸ poison(): Effect

Returns: Effect

regeneration

▸ regeneration(): Effect

Returns: Effect

resistance

▸ resistance(): Effect

Returns: Effect

saturation

▸ saturation(): Effect

Returns: Effect

slowFalling

▸ slowFalling(): Effect

Returns: Effect

slowness

▸ slowness(): Effect

Returns: Effect

speed

▸ speed(): Effect

Returns: Effect

strength

▸ strength(): Effect

Returns: Effect

waterBreathing

▸ waterBreathing(): Effect

Returns: Effect

weakness

▸ weakness(): Effect

Returns: Effect

wither

▸ wither(): Effect

Returns: Effect

Interface: Entity

Methods

addEffect

▸ addEffect(effect: Effect, duration: number, amplifier: number): Effect

Adds an effect to the Entity

Parameters:

Returns: Effect

getComponent

▸ getComponent(component: string): EntityComponent

Returns the component matching the given identifier

Parameters:

Returns: EntityComponent

getComponents

▸ getComponents(): EntityComponent[]

Returns an array of supported components

Returns: EntityComponent[]

getEffect

▸ getEffect(effect: Effect): Effect

Gets an effect from the Entity

Parameters:

Returns: Effect

getName

▸ getName(): string

Returns the name of the entity (e.g. “Horse”)

Returns: string

hasComponent

▸ hasComponent(component: string): boolean

Returns true if the given component exists on the entity and is supported

Parameters:

Returns: boolean

kill

▸ kill(): void

Kills the entity

Returns: void

Interface: EntityComponent

Methods

getName

▸ getName(): string

Returns the name of the component

Returns: string

leash

▸ leash(entity: Entity): void

Leashes this entity to another given entity. This must be used on the “minecraft:leashable” component

Parameters:

Returns: void

setColor

▸ setColor(color: number): void

Sets the entities color value. This must be used on the “minecraft:color” component

Parameters:

Returns: void

setTamed

▸ setTamed(particles: boolean): void

Sets the entity as tamed

Parameters:

Returns: void

unleash

▸ unleash(): void

Causes this entity to detach leashes. This must be used on the “minecraft:leashable” component

Returns: void

Interface: Item

Interface: Items

Methods

Contains a method for every vanilla item. Every method is in camelCase. Example:

▸ apple(): Item

Interface: ItemStack

Interface: ItemStackClass

Constructors

constructor

+ new ItemStack(item: Item, amount: number, data: number): ItemStack

Creates a an item stack

Parameters:

Returns: ItemStack

Interface: Sequence

Methods

assertEntityData

▸ assertEntityData(position: BlockLocation, id: string, func: (entity: Entity) => void): void

Asserts that the given condition is true for all entities of the given type at the given location

Parameters:

Returns: void

assertEntityHasArmor

▸ assertEntityHasArmor(id: string, slot: number, item: string, data: number, position: BlockLocation, bool: boolean): void

Asserts an error when the armor is found on the entity at the given coordinates

Parameters:

Returns: void

assertEntityHasComponent

▸ assertEntityHasComponent(id: string, component: string, position: BlockLocation, bool: boolean): void

Asserts an error when the given entity has the component

Parameters:

Returns: void

assertEntityInstancePresent

▸ assertEntityInstancePresent(id: string, position: BlockLocation): void

Asserts an error when the given entity is found at the given coordinates

Parameters:

Returns: void

assertEntityNotTouching

▸ assertEntityNotTouching(id: string, position: BlockLocation): void

Asserts that there is no entity of the given type at the given position

Parameters:

Returns: void

assertEntityTouching

▸ assertEntityTouching(id: string, position: BlockLocation): void

Asserts that there is an entity of the given type at the given position

Parameters:

Returns: void

assertIsWaterLogged

▸ assertIsWaterLogged(position: BlockLocation, isWaterLoggged: boolean): void

Asserts that the block at the given location is waterlogged

Parameters:

Returns: void

assertItemEntityCountIs

▸ assertItemEntityCountIs(item: Item, position: BlockLocation, searchDistance: number, count: number): void

Asserts that the entity item count in the given search area matches the expected count

Parameters:

Returns: void

assertRedstonePower

▸ assertRedstonePower(position: BlockLocation, power: number): void

Asserts the redstone power level at the given location

Parameters:

Returns: void

print

▸ print(text: string): void

Prints the given text to the chat

Parameters:

Returns: void

pulseRedstone

▸ pulseRedstone(position: BlockLocation, duration: number): void

Creates a Redstone block at the given position and destroys it after “duration” ticks

Parameters:

Returns: void

spawn

▸ spawn(id: string, position: BlockLocation): Entity

Spawns the specified entity at the specified coordinates

Parameters:

Returns: Entity

spawnItem

▸ spawnItem(item: ItemStack, location: WorldLocation): Item

Spawns an item at the given location

Parameters:

Returns: Item

thenExecute

▸ thenExecute(func: () => void): Sequence

Executes the function when called

Parameters:

Returns: Sequence

thenExecuteAfter

▸ thenExecuteAfter(time: number, func: () => void): Sequence

Executes the function after the time given when called

Parameters:

Returns: Sequence

thenIdle

▸ thenIdle(time: number): Sequence

Causes the sequence to wait for the given amount of time

Parameters:

Returns: Sequence

thenSucceed

▸ thenSucceed(): void

Causes the GameTest to succeed

Returns: void

thenWait

▸ thenWait(func: () => void): Sequence

Causes the sequence to wait until the function asserts an error

Parameters:

Returns: Sequence

thenWaitWithDelay

▸ thenWaitWithDelay(delayTicks: number, func: () => void): Sequence

Causes the sequence to wait until the function asserts an error and the delay has passed

Parameters:

Returns: Sequence

Interface: State

Interface: Tags

Properties

suiteAll

• suiteAll: string

suiteBroken

• suiteBroken: string

suiteDebug

• suiteDebug: string

suiteDefault

• suiteDefault: string

Interface: Test

Methods

assertBlockNotPresent

▸ assertBlockNotPresent(id: Block, position: BlockLocation): void

Asserts an error when the given block is not found at the given coordinates

Parameters:

Returns: void

assertBlockPresent

▸ assertBlockPresent(id: Block, position: BlockLocation): void

Asserts an error when the specified block is found at the specified coordinates

Parameters:

Returns: void

assertBlockState

▸ assertBlockState(state: string, stateValue: string | number, position: BlockLocation): void

Asserts an error when the given block at the given coordinates has the block state

Parameters:

Returns: void

assertContainerContains

▸ assertContainerContains(itemStack: ItemStack, position: BlockLocation): void

Asserts an error if there is a container with the given item at the given coordinates

Parameters:

Returns: void

assertContainerEmpty

▸ assertContainerEmpty(position: BlockLocation): void

Asserts an error if there is an empty container at the given coordinates

Parameters:

Returns: void

assertEntityNotPresent

▸ assertEntityNotPresent(id: string, position: BlockLocation): void

Asserts an error when the given entity is not found at the given coordinates

Parameters:

Returns: void

assertEntityNotPresentInArea

▸ assertEntityNotPresentInArea(id: string): void

Throws an Error if an entity matching the given identifier does not exist in the test region

Parameters:

Returns: void

assertEntityPresent

▸ assertEntityPresent(id: string, position: BlockLocation): void

Asserts an error when the given entity is found at the given coordinates

Parameters:

Returns: void

assertEntityPresentInArea

▸ assertEntityPresentInArea(id: string): void

Throws an Error if an entity matching the given identifier exists in the test region

Parameters:

Returns: void

assertItemEntityNotPresent

▸ assertItemEntityNotPresent(item: Item, position: BlockLocation, amount: number): void

Asserts an error when the given item is not found at the given coordinates

Parameters:

Returns: void

assertItemEntityPresent

▸ assertItemEntityPresent(item: Item, position: BlockLocation, amount: number): void

Asserts an error when the given item stack is found at the given coordinates

Parameters:

Returns: void

fail

▸ fail(errorMessage: string): void

Causes the GameTest to fail

Parameters:

Returns: void

failIf

▸ failIf(func: () => void): void

When the func parameter calls an assert function the GameTest will fail

Parameters:

Returns: void

killAllEntities

▸ killAllEntities(): void

Kills all entities in the test

Returns: void

pressButton

▸ pressButton(position: BlockLocation): void

Presses a button at the specified coordinates if there is one there

Parameters:

Returns: void

pullLever

▸ pullLever(position: BlockLocation): void

Pulls a lever at the given coordinates if there is one there

Parameters:

Returns: void

runAfterDelay

▸ runAfterDelay(ticks: number, func: (test: Test) => void): void

Runs the a function after the set delay

Parameters:

Returns: void

runAtTickTime

▸ runAtTickTime(tick: number, func: () => void): any

Parameters:

Returns: any

setBlock

▸ setBlock(id: Block, position: BlockLocation): void

Places the specified block at the specified coordinates

Parameters:

Returns: void

startSequence

▸ startSequence(): Sequence

Allows finer control over advanced test sequences

Returns: Sequence

succeed

▸ succeed(): void

When this is called, the GameTest succeeds

Returns: void

succeedOnTick

▸ succeedOnTick(tick: number): void

The GameTest will succeed when the given amount of ticks has passed

Parameters:

Returns: void

succeedOnTickWhen

▸ succeedOnTickWhen(tick: number, func: () => void): void

The GameTest will succeed when the given amount of ticks has passed and the func parameter calls an assert function

Parameters:

Returns: void

succeedWhen

▸ succeedWhen(func: () => void): void

When the func paramater calls an assert function the GameTest will succeed

Parameters:

Returns: void

succeedWhenBlockPresent

▸ succeedWhenBlockPresent(id: Block, position: BlockLocation): void

The GameTest will succeed when the given block is found at the given coordinates

Parameters:

Returns: void

▸ succeedWhenBlockPresent(id: Block, position: BlockLocation): void

The GameTest will succeed when the specified block is found at the specified coordinates

Parameters:

Returns: void

succeedWhenEntityHasComponent

▸ succeedWhenEntityHasComponent(id: string, component: string, position: BlockLocation, hasComponent: boolean): void

The GameTest will succeed when the given entity has the given component

Parameters:

Returns: void

succeedWhenEntityNotPresent

▸ succeedWhenEntityNotPresent(id: string, position: BlockLocation): void

The GameTest will succeed when the given entity is not found at the given coordinates

Parameters:

Returns: void

succeedWhenEntityPresent

▸ succeedWhenEntityPresent(id: string, position: BlockLocation): void

The GameTest will succeed when the given entity is found at the given coordinates

Parameters:

Returns: void

Interface: TestRunner

Methods

batch

▸ batch(time: night | day): TestRunner

Sets the time of day when the GameTest is run. The time will be changed to the time set here when the GameTest is run

Parameters:

Returns: TestRunner

maxAttempts

▸ maxAttempts(attempts: number): TestRunner

Sets the maximum number of times a test will try to rerun if it fails

Parameters:

Returns: TestRunner

maxTicks

▸ maxTicks(ticks: number): TestRunner

Sets the maximum amount of ticks the GameTest must complete until it fails

Parameters:

Returns: TestRunner

padding

▸ padding(time: number): TestRunner

Sets the padding between GameTests being run

Parameters:

Returns: TestRunner

required

▸ required(isRequired: boolean): TestRunner

Parameters:

Returns: TestRunner

requiredSuccessfulAttempts

▸ requiredSuccessfulAttempts(attempts: number): TestRunner

Sets the number of successful test runs to be considered successful

Parameters:

Returns: TestRunner

setupTicks

▸ setupTicks(ticks: number): TestRunner

Sets the ticks at which the GameTest begins

Parameters:

Returns: TestRunner

structureName

▸ structureName(name: string): TestRunner

Sets the structure name linked with this GameTest

Parameters:

Returns: TestRunner

tag

▸ tag(tag: any): TestRunner

Sets a tag for the GameTest to be referenced in the “/gametest runall” command

Parameters:

Returns: TestRunner

Interface: World

Methods

addEventListener

▸ addEventListener(event: WorldEvent, func: (entity: Entity) => void): void

Registers an event listener for entity events Supported

Parameters:

Returns: void

getDimension

▸ getDimension(): Dimension

Gets the current dimension

Returns: Dimension

Interface: WorldLocation

Interface: WorldLocationClass

Constructors

constructor

+ new Location(x: number, y: number, z: number): WorldLocation

Creates a location

Parameters:

Returns: WorldLocation

Type aliases

WorldEvent

Ƭ WorldEvent: “onEntityCreated” | “onEntityDefinitionTriggered”