Class Test

Main class for GameTest functions, with helpers and data for manipulating the respective test. Note that all methods of this class expect BlockLocations and Locations relative to the GameTest structure block.

Index

Methods

assert assertBlockPresent assertBlockState assertCanReachLocation assertContainerContains assertContainerEmpty assertEntityHasArmor assertEntityHasComponent assertEntityInstancePresent assertEntityInstancePresentInArea assertEntityPresent assertEntityPresentInArea assertEntityState assertEntityTouching assertIsWaterlogged assertItemEntityCountIs assertItemEntityPresent assertRedstonePower destroyBlock fail failIf getBlock getDimension getFenceConnectivity getSculkSpreader getTestDirection idle killAllEntities onPlayerJump pressButton print pullLever pulseRedstone relativeBlockLocation relativeLocation removeSimulatedPlayer rotateDirection rotateVector runAfterDelay runAtTickTime setBlockPermutation setBlockType setFluidContainer setTntFuse spawn spawnAtLocation spawnItem spawnSimulatedPlayer spawnWithoutBehaviors spawnWithoutBehaviorsAtLocation spreadFromFaceTowardDirection startSequence succeed succeedIf succeedOnTick succeedOnTickWhen succeedWhen succeedWhenBlockPresent succeedWhenEntityHasComponent succeedWhenEntityPresent triggerInternalBlockEvent until walkTo walkToLocation worldBlockLocation worldLocation

Methods

assert

assert(condition: boolean, message: string): void
Parameters
- condition: boolean
  Expression of the condition to evaluate.
- message: string
  Message that is passed if the condition does not evaluate to true.
Returns void
Remarks
Tests that the condition specified in condition is true. If not, an error with the specified message is thrown.

Throws
This function can throw errors.

GameTestError

assertBlockPresent

assertBlockPresent(
    blockType: string | BlockType,
    blockLocation: Vector3,
    isPresent?: boolean,
): void
Parameters
- blockType: string | BlockType
  Expected block type.
- blockLocation: Vector3
  Location of the block to test at.
- OptionalisPresent: boolean
  If true, this function tests whether a block of the specified type is at the location. If false, tests that a block of the specified type is not present.
Returns void
Remarks
Tests that a block of the specified type is present at the specified location. If it is not, an exception is thrown.

Throws
This function can throw errors.

GameTestError

assertBlockState

assertBlockState(
blockLocation: Vector3,
callback: (arg: Block) => boolean,
): void
Parameters
- blockLocation: Vector3
  Location of the block to test at.
- callback: (arg: Block) => boolean
  Callback function that contains additional tests based on the block at the specified location.
Returns void
Remarks
Tests that a block has a particular state value at the specified location. If it does not have that state value, an exception is thrown.

Throws
This function can throw errors.

GameTestError

assertCanReachLocation

assertCanReachLocation(
    mob: Entity,
    blockLocation: Vector3,
    canReach?: boolean,
): void
Parameters
- mob: Entity
  Entity that you wish to test the location against.
- blockLocation: Vector3
  Structure-relative location to test whether the specified mob can reach.
- OptionalcanReach: boolean
  If true, tests whether the mob can reach the location. If false, tests whether the mob is not able to reach the location.
Returns void
Remarks
Tests that an entity can reach a particular location. Depending on the value of canReach, throws an exception if the condition is not met.

Throws
This function can throw errors.

GameTestError

assertContainerContains

assertContainerContains(itemStack: ItemStack, blockLocation: Vector3): void
Parameters
- itemStack: ItemStack
  Represents the type of item to check for. The specified container must contain at least 1 item matching the item type defined in itemStack.
- blockLocation: Vector3
  Location of the block with a container (for example, a chest) to test the contents of.
Returns void
Remarks
Tests that a container (e.g., a chest) at the specified location contains a specified of item stack. If not, an error is thrown.

Throws
This function can throw errors.

GameTestError

assertContainerEmpty

assertContainerEmpty(blockLocation: Vector3): void
Parameters
- blockLocation: Vector3
  Location of the block with a container (for example, a chest) to test is empty of contents.
Returns void
Remarks
Tests that a container (e.g., a chest) at the specified location is empty. If not, an error is thrown.

Throws
This function can throw errors.

GameTestError

assertEntityHasArmor

assertEntityHasArmor(
    entityTypeIdentifier: string,
    armorSlot: number,
    armorName: string,
    armorData: number,
    blockLocation: Vector3,
    hasArmor?: boolean,
): void
Parameters
- entityTypeIdentifier: string
  Identifier of the entity to match (e.g., 'minecraft:skeleton').
- armorSlot: number
  Container slot index to test.
- armorName: string
  Name of the armor to look for.
- armorData: number
  Data value integer to look for.
- blockLocation: Vector3
  Location of the entity with armor to test for.
- OptionalhasArmor: boolean
  Whether or not the entity is expected to have the specified armor equipped.
Returns void
Remarks
Tests that an entity has a specific piece of armor equipped. If not, an error is thrown.

Throws
This function can throw errors.

GameTestError

assertEntityHasComponent

assertEntityHasComponent(
    entityTypeIdentifier: string,
    componentIdentifier: string,
    blockLocation: Vector3,
    hasComponent?: boolean,
): void
Parameters
- entityTypeIdentifier: string
  Identifier of the specified entity (e.g., 'minecraft:skeleton'). If the namespace is not specified, 'minecraft:' is assumed.
- componentIdentifier: string
  Identifier of the component to check for. If the namespace is not specified, 'minecraft:' is assumed.
- blockLocation: Vector3
  Location of the block with a container (for example, a chest.)
- OptionalhasComponent: boolean
  Determines whether to test that the component exists, or does not.
Returns void
Remarks
Tests that an entity has a particular component. If not, an exception is thrown.

Throws
This function can throw errors.

GameTestError

assertEntityInstancePresent

assertEntityInstancePresent(
    entity: Entity,
    blockLocation: Vector3,
    isPresent?: boolean,
): void
Parameters
- entity: Entity
  Specific entity to test for.
- blockLocation: Vector3
  Location of the entity to test for.
- OptionalisPresent: boolean
  Whether to test that an entity is present or not present at the specified location.
Returns void
Remarks
Depending on the value for isPresent, tests that a particular entity is present or not present at the specified location. Depending on the value of isPresent, if the entity is found or not found, an error is thrown.

Throws
This function can throw errors.

GameTestError

assertEntityInstancePresentInArea

assertEntityInstancePresentInArea(entity: Entity, isPresent?: boolean): void

Parameters

entity: Entity
Entity instance to test for.
OptionalisPresent: boolean
If true, this function tests whether the specified entity is present in the GameTest area. If false, tests that the specified entity is not present.

Returns void

Remarks

Tests that an entity instance is present within the GameTest area. If not, an exception is thrown.

Throws

This function can throw errors.

GameTestError

Example: simpleMobTest.ts

import * as gameTest from '@minecraft/server-gametest';

gameTest
    .register('StarterTests', 'simpleMobTest', (test: gameTest.Test) => {
        const attackerId = 'fox';
        const victimId = 'chicken';

        test.spawn(attackerId, { x: 5, y: 2, z: 5 });
        const victim = test.spawn(victimId, { x: 2, y: 2, z: 2 });

        test.assertEntityInstancePresentInArea(victim, true);

        test.succeedWhen(() => {
            test.assertEntityInstancePresentInArea(victim, false);
        });
    })
    .maxTicks(400)
    .structureName('gametests:mediumglass');

assertEntityPresent

assertEntityPresent(
    entityTypeIdentifier: string,
    blockLocation: Vector3,
    searchDistance?: number,
    isPresent?: boolean,
): void
Parameters
- entityTypeIdentifier: string
  Type of entity to test for (e.g., 'minecraft:skeleton'). If an entity namespace is not specified, 'minecraft:' is assumed.
- blockLocation: Vector3
  Location of the entity to test for.
- OptionalsearchDistance: number
  The distance to search for the entity from the blockLocation.
- OptionalisPresent: boolean
  If true, this function tests whether an entity of the specified type is present. If false, tests that an entity of the specified type is not present.
Returns void
Remarks
Depending on the value of isPresent, tests for the presence or non-presence of entity of a specified type at a particular location. If the condition is not met, an exception is thrown.

Throws
This function can throw errors.

GameTestError

assertEntityPresentInArea

assertEntityPresentInArea(
entityTypeIdentifier: string,
isPresent?: boolean,
): void

Parameters

entityTypeIdentifier: string
Type of entity to test for (e.g., 'minecraft:skeleton'). If an entity namespace is not specified, 'minecraft:' is assumed.
OptionalisPresent: boolean
If true, this function tests whether an entity of the specified type is present in the GameTest area. If false, tests that an entity of the specified type is not present.

Returns void

Remarks

Tests that an entity of a specified type is present within the GameTest area. If not, an exception is thrown.

Throws

This function can throw errors.

GameTestError

Example: simpleMobTest.ts

import * as gameTest from '@minecraft/server-gametest';

gameTest
    .register('StarterTests', 'simpleMobTest', (test: gameTest.Test) => {
        const attackerId = 'fox';
        const victimId = 'chicken';

        test.spawn(attackerId, { x: 5, y: 2, z: 5 });
        test.spawn(victimId, { x: 2, y: 2, z: 2 });

        test.assertEntityPresentInArea(victimId, true);

        test.succeedWhen(() => {
            test.assertEntityPresentInArea(victimId, false);
        });
    })
    .maxTicks(400)
    .structureName('gametests:mediumglass');

Example: simpleMobGameTest.ts

import { Test, register } from "@minecraft/server-gametest";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function simpleMobGameTest(test: Test) {
  const attackerId = MinecraftEntityTypes.Fox;
  const victimId = MinecraftEntityTypes.Chicken;

  test.spawn(attackerId, { x: 5, y: 2, z: 5 });
  test.spawn(victimId, { x: 2, y: 2, z: 2 });

  test.assertEntityPresentInArea(victimId, true);

  test.succeedWhen(() => {
    test.assertEntityPresentInArea(victimId, false);
  });
}
register("StarterTests", "simpleMobTest", simpleMobGameTest).maxTicks(400).structureName("gametests:mediumglass");

assertEntityState

assertEntityState(
    blockLocation: Vector3,
    entityTypeIdentifier: string,
    callback: (arg: Entity) => boolean,
): void
Parameters
- blockLocation: Vector3
  Location of the entity to look for.
- entityTypeIdentifier: string
  Identifier of the entity (e.g., 'minecraft:skeleton') to look for. Note if no namespace is specified, 'minecraft:' is assumed.
- callback: (arg: Entity) => boolean
  Callback function where facets of the selected entity can be tested for. If this callback function returns false or no entity with the specified identifier is found, an exception is thrown.
Returns void
Remarks
Tests that an entity (e.g., a skeleton) at the specified location has a particular piece of data. If not, an error is thrown.

Throws
This function can throw errors.

GameTestError

assertEntityTouching

assertEntityTouching(
    entityTypeIdentifier: string,
    location: Vector3,
    isTouching?: boolean,
): void
Parameters
- entityTypeIdentifier: string
  Type of entity to test for (e.g., 'minecraft:skeleton'). If an entity namespace is not specified, 'minecraft:' is assumed.
- location: Vector3
  Location of the entity to test for.
- OptionalisTouching: boolean
  If true, this function tests whether the entity is touching the specified location. If false, tests that an entity is not testing the specified location.
Returns void
Remarks
Depending on the value of isTouching, tests that an entity of a specified type is touching or connected to another entity. If the condition is not met, an exception is thrown.

Throws
This function can throw errors.

GameTestError

assertIsWaterlogged

assertIsWaterlogged(blockLocation: Vector3, isWaterlogged?: boolean): void
Parameters
- blockLocation: Vector3
  Location of the block to test for.
- OptionalisWaterlogged: boolean
  Whether to test that the block at position is expected to be waterlogged.
Returns void
Remarks
Depending on the value of isWaterlogged, tests that a block at a location contains water. If the condition is not met, an error is thrown. Pure water blocks are not considered to be waterlogged.

Throws
This function can throw errors.

GameTestError

assertItemEntityCountIs

assertItemEntityCountIs(
    itemType: string | ItemType,
    blockLocation: Vector3,
    searchDistance: number,
    count: number,
): void
Parameters
- itemType: string | ItemType
  Type of item to look for.
- blockLocation: Vector3
  Location to search around for the specified set of items.
- searchDistance: number
  Range, in blocks, to aggregate a count of items around. If 0, will only search the particular block at position.
- count: number
  Number of items, at minimum, to look and test for.
Returns void
Remarks
Tests that items of a particular type and count are present within an area. If not, an error is thrown.

Throws
This function can throw errors.

GameTestError

assertItemEntityPresent

assertItemEntityPresent(
    itemType: string | ItemType,
    blockLocation: Vector3,
    searchDistance?: number,
    isPresent?: boolean,
): void
Parameters
- itemType: string | ItemType
  Type of item to test for.
- blockLocation: Vector3
  Location of the item entity to test for.
- OptionalsearchDistance: number
  Radius in blocks to look for the item entity.
- OptionalisPresent: boolean
  If true, this function tests whether an item entity of the specified type is present. If false, tests that an item entity of the specified type is not present.
Returns void
Remarks
Depending on the value of isPresent, tests whether a particular item entity is present or not at a particular location. If the condition is not met, an exception is thrown.

Throws
This function can throw errors.

GameTestError

assertRedstonePower

assertRedstonePower(blockLocation: Vector3, power: number): void
Parameters
- blockLocation: Vector3
  Location to test.
- power: number
  Expected power level.
Returns void
Remarks
Tests that Redstone power at a particular location matches a particular value. If not, an exception is thrown.

Throws
This function can throw errors.

GameTestError

destroyBlock

destroyBlock(blockLocation: Vector3, dropResources?: boolean): void
Parameters
- blockLocation: Vector3
  Location of the block to destroy.
- OptionaldropResources: boolean
  Whether to add resources exposed with a particular drop.
Returns void
Remarks
Destroys a block at a particular location.

This function can't be called in read-only mode.

Throws
This function can throw errors.

GameTestError

fail

fail(errorMessage: string): void
Parameters
- errorMessage: string
  Error message summarizing the failure condition.
Returns void
Remarks
Marks the current test as a failure case.

Throws
This function can throw errors.

failIf

failIf(callback: () => void): void
Parameters
- callback: () => void
  Callback function that runs. If the function runs successfully, the test is marked as a failure. Typically, this function will have .assertXyz method calls within it.
Returns void
Remarks
Runs the given callback. If the callback does not throw an exception, the test is marked as a failure.

Throws
This function can throw errors.

getBlock

getBlock(blockLocation: Vector3): Block
Parameters
- blockLocation: Vector3
  Location of the block to retrieve.
Returns Block
Remarks
Gets a block at the specified block location.

This function can't be called in read-only mode.

Throws
This function can throw errors.

minecraftserver.GameTestError

getDimension

getDimension(): Dimension
Returns Dimension
Remarks
Gets the dimension of this test.

Throws
This function can throw errors.

minecraftserver.GameTestError

getFenceConnectivity

getFenceConnectivity(blockLocation: Vector3): FenceConnectivity
Parameters
- blockLocation: Vector3
  Location of the block to retrieve.
Returns FenceConnectivity
Remarks
If the block at the specified block location is a fence, this returns a helper object with details on how a fence is connected.

This function can't be called in read-only mode.

Throws
This function can throw errors.

GameTestError

getSculkSpreader

getSculkSpreader(blockLocation: Vector3): SculkSpreader
Parameters
- blockLocation: Vector3
  Location of the block to retrieve a sculk spreader from.
Returns SculkSpreader
Returns the SculkSpreader or undefined if no SculkSpreader is present on the block.

Remarks
Retrieves a sculk spreader object that can be used to control and manage how sculk grows from a block.

This function can't be called in read-only mode.

Throws
This function can throw errors.

GameTestError

getTestDirection

getTestDirection(): Direction
Returns Direction
Remarks
Returns the direction of the current test - see the minecraftserver.Direction enum for more information on potential values (north, east, south, west - values 2-5).

idle

idle(tickDelay: number): Promise<void>
Parameters
- tickDelay: number
  Amount of time to wait, in ticks.
Returns Promise<void>
Remarks
This asynchronous function will wait for the specified time in ticks before continuing execution.

This function can't be called in read-only mode.

killAllEntities

killAllEntities(): void
Returns void
Remarks
Kills all entities within the GameTest structure.

This function can't be called in read-only mode.

Throws
This function can throw errors.

GameTestError

onPlayerJump

onPlayerJump(mob: Entity, jumpAmount: number): void
Parameters
- mob: Entity
- jumpAmount: number
Returns void
Remarks
This function can't be called in read-only mode.

Throws
This function can throw errors.

GameTestError

pressButton

pressButton(blockLocation: Vector3): void
Parameters
- blockLocation: Vector3
  Location to push the button at.
Returns void
Remarks
Presses a button at a block location.

This function can't be called in read-only mode.

Throws
Will throw an error if a button is not present at the specified position.

GameTestError

print

print(text: string): void
Parameters
- text: string
  Message to display.
Returns void
Remarks
Displays the specified message to all players.

This function can't be called in read-only mode.

Throws
This function can throw errors.

GameTestError

pullLever

pullLever(blockLocation: Vector3): void
Parameters
- blockLocation: Vector3
  Location to pull the lever at.
Returns void
Remarks
Pulls a lever at a block location.

This function can't be called in read-only mode.

Throws
Will throw an error if a lever is not present at the specified position.

GameTestError

pulseRedstone

pulseRedstone(blockLocation: Vector3, duration: number): void
Parameters
- blockLocation: Vector3
  Location to pulse Redstone at.
- duration: number
  Number of ticks to pulse Redstone.
Returns void
Remarks
Sends a Redstone pulse at a particular location by creating a temporary Redstone block.

This function can't be called in read-only mode.

Throws
This function can throw errors.

GameTestError

relativeBlockLocation

relativeBlockLocation(worldBlockLocation: Vector3): Vector3
Parameters
- worldBlockLocation: Vector3
  Absolute location in the world to convert to a relative location.
Returns Vector3
A location relative to the GameTest command block.

Remarks
From a BlockLocation, returns a new BlockLocation with coordinates relative to the current GameTest structure block. For example, the relative coordinates for the block above the structure block are (0, 1, 0). Rotation of the GameTest structure is also taken into account.

Throws
This function can throw errors.

minecraftserver.GameTestError

relativeLocation

relativeLocation(worldLocation: Vector3): Vector3
Parameters
- worldLocation: Vector3
  Absolute location in the world to convert to a relative location.
Returns Vector3
A location relative to the GameTest command block.

Remarks
From a location, returns a new location with coordinates relative to the current GameTest structure block. For example, the relative coordinates for the block above the structure block are (0, 1, 0). Rotation of the GameTest structure is also taken into account.

This function can't be called in read-only mode.

Throws
This function can throw errors.

minecraftserver.GameTestError

removeSimulatedPlayer

removeSimulatedPlayer(simulatedPlayer: SimulatedPlayer): void
Parameters
- simulatedPlayer: SimulatedPlayer
  Simulated player to remove.
Returns void
Remarks
Removes a simulated player from the world.

This function can't be called in read-only mode.

rotateDirection

rotateDirection(direction: Direction): Direction
Parameters
- direction: Direction
  Direction to translate into a direction relative to the GameTest facing. Passing in Direction.south will return the test direction; Passing in Direction.north will return the opposite of the test direction, and so on.
Returns Direction
Remarks
Returns a relative direction given the current rotation of the current test. Passing in Direction.south will return the test direction; Passing in Direction.north will return the opposite of the test direction, and so on.

This function can't be called in read-only mode.

Throws
This function can throw errors.

minecraftserver.GameTestError

rotateVector

rotateVector(vector: Vector3): Vector3
Parameters
- vector: Vector3
Returns Vector3
Remarks
This function can't be called in read-only mode.

Throws
This function can throw errors.

minecraftserver.GameTestError

runAfterDelay

runAfterDelay(delayTicks: number, callback: () => void): void
Parameters
- delayTicks: number
  Number of ticks to delay before running the specified callback.
- callback: () => void
  Callback function to execute.
Returns void
Remarks
Runs a specific callback after a specified delay of ticks

This function can't be called in read-only mode.

Throws
This function can throw errors.

runAtTickTime

runAtTickTime(tick: number, callback: () => void): void
Parameters
- tick: number
  Tick (after the start of the GameTest) to run the callback at.
- callback: () => void
  Callback function to execute.
Returns void
Remarks
Runs the given callback after a delay of tick ticks from the start of the GameTest.

This function can't be called in read-only mode.

Throws
This function can throw errors.

setBlockPermutation

setBlockPermutation(blockData: BlockPermutation, blockLocation: Vector3): void
Parameters
- blockData: BlockPermutation
  Permutation that contains the configuration data for a block.
- blockLocation: Vector3
  Location of the block to set.
Returns void
Remarks
Sets a block to a particular configuration (a BlockPermutation) at the specified block location.

This function can't be called in read-only mode.

Throws
This function can throw errors.

GameTestError

setBlockType

setBlockType(blockType: string | BlockType, blockLocation: Vector3): void

Parameters

blockType: string | BlockType
Type of block to set.
blockLocation: Vector3
Location of the block to set.

Returns void

Remarks

Sets a block to a particular type at the specified block location.

This function can't be called in read-only mode.

Throws

This function can throw errors.

GameTestError

Example: minibiomes.ts

import { EntityComponentTypes } from "@minecraft/server";
import { Test, register } from "@minecraft/server-gametest";
import { MinecraftBlockTypes, MinecraftEntityTypes } from "@minecraft/vanilla-data";

function minibiomes(test: Test) {
  const minecart = test.spawn(MinecraftEntityTypes.Minecart, { x: 9, y: 7, z: 7 });
  const pig = test.spawn(MinecraftEntityTypes.Pig, { x: 9, y: 7, z: 7 });

  test.setBlockType(MinecraftBlockTypes.Cobblestone, { x: 10, y: 7, z: 7 });

  const minecartRideableComp = minecart.getComponent(EntityComponentTypes.Rideable);

  minecartRideableComp?.addRider(pig);

  test.succeedWhenEntityPresent(MinecraftEntityTypes.Pig, { x: 8, y: 3, z: 1 }, true);
}
register("ChallengeTests", "minibiomes", minibiomes).structureName("gametests:minibiomes").maxTicks(160);

setFluidContainer

setFluidContainer(location: Vector3, type: FluidType): void
Parameters
- location: Vector3
  Location of the fluid container block.
- type: FluidType
  Type of fluid to set. See minecraftserver.FluidType for a list of values.
Returns void
Remarks
For blocks that are fluid containers - like a cauldron - changes the type of fluid within that container.

This function can't be called in read-only mode.

Throws
This function can throw errors.

GameTestError

setTntFuse

setTntFuse(entity: Entity, fuseLength: number): void
Parameters
- entity: Entity
  Entity that is explodable.
- fuseLength: number
  Length of time, in ticks, before the entity explodes.
Returns void
Remarks
Sets the fuse of an explodable entity.

This function can't be called in read-only mode.

Throws
This function can throw errors.

GameTestError

spawn

spawn(entityTypeIdentifier: string, blockLocation: Vector3): Entity

Parameters

entityTypeIdentifier: string
Type of entity to create. If no namespace is provided, 'minecraft:' is assumed. Note that an optional initial spawn event can be specified between less than/greater than signs (e.g., namespace:entityType).
blockLocation: Vector3

Returns Entity

The spawned entity. If the entity cannot be spawned, returns undefined.

Remarks

Spawns an entity at a location.

This function can't be called in read-only mode.

Throws

This function can throw errors.

minecraftserver.GameTestError

Example: simpleMobTest.ts

import * as gameTest from '@minecraft/server-gametest';

gameTest
    .register('StarterTests', 'simpleMobTest', (test: gameTest.Test) => {
        const attackerId = 'fox';
        const victimId = 'chicken';

        test.spawn(attackerId, { x: 5, y: 2, z: 5 });
        test.spawn(victimId, { x: 2, y: 2, z: 2 });

        test.assertEntityPresentInArea(victimId, true);

        test.succeedWhen(() => {
            test.assertEntityPresentInArea(victimId, false);
        });
    })
    .maxTicks(400)
    .structureName('gametests:mediumglass');

Example: simpleMobGameTest.ts

import { Test, register } from "@minecraft/server-gametest";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function simpleMobGameTest(test: Test) {
  const attackerId = MinecraftEntityTypes.Fox;
  const victimId = MinecraftEntityTypes.Chicken;

  test.spawn(attackerId, { x: 5, y: 2, z: 5 });
  test.spawn(victimId, { x: 2, y: 2, z: 2 });

  test.assertEntityPresentInArea(victimId, true);

  test.succeedWhen(() => {
    test.assertEntityPresentInArea(victimId, false);
  });
}
register("StarterTests", "simpleMobTest", simpleMobGameTest).maxTicks(400).structureName("gametests:mediumglass");

Example: phantomsShouldFlyFromCats.ts

import { Test, register } from "@minecraft/server-gametest";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function phantomsShouldFlyFromCats(test: Test) {
  test.spawn(MinecraftEntityTypes.Cat, { x: 4, y: 3, z: 3 });
  test.spawn(MinecraftEntityTypes.Phantom, { x: 4, y: 3, z: 3 });

  test.succeedWhenEntityPresent(MinecraftEntityTypes.Phantom, { x: 4, y: 6, z: 3 }, true);
}

register("MobBehaviorTests", "phantoms_should_fly_from_cats", phantomsShouldFlyFromCats)
  .structureName("gametests:glass_cells");

Example: minibiomes.ts

import { EntityComponentTypes } from "@minecraft/server";
import { Test, register } from "@minecraft/server-gametest";
import { MinecraftBlockTypes, MinecraftEntityTypes } from "@minecraft/vanilla-data";

function minibiomes(test: Test) {
  const minecart = test.spawn(MinecraftEntityTypes.Minecart, { x: 9, y: 7, z: 7 });
  const pig = test.spawn(MinecraftEntityTypes.Pig, { x: 9, y: 7, z: 7 });

  test.setBlockType(MinecraftBlockTypes.Cobblestone, { x: 10, y: 7, z: 7 });

  const minecartRideableComp = minecart.getComponent(EntityComponentTypes.Rideable);

  minecartRideableComp?.addRider(pig);

  test.succeedWhenEntityPresent(MinecraftEntityTypes.Pig, { x: 8, y: 3, z: 1 }, true);
}
register("ChallengeTests", "minibiomes", minibiomes).structureName("gametests:minibiomes").maxTicks(160);

spawnAtLocation

spawnAtLocation(entityTypeIdentifier: string, location: Vector3): Entity
Parameters
- entityTypeIdentifier: string
  Type of entity to create. If no namespace is provided, 'minecraft:' is assumed. Note that an optional initial spawn event can be specified between less than/greater than signs (e.g., namespace:entityType).
- location: Vector3
Returns Entity
The spawned entity. If the entity cannot be spawned, returns undefined.

Remarks
Spawns an entity at a location.

This function can't be called in read-only mode.

Throws
This function can throw errors.

minecraftserver.GameTestError

spawnItem

spawnItem(itemStack: ItemStack, location: Vector3): Entity
Parameters
- itemStack: ItemStack
  ItemStack that describes the item entity to create.
- location: Vector3
  Location to create the item entity at.
Returns Entity
Remarks
Spawns an item entity at a specified location.

This function can't be called in read-only mode.

Throws
This function can throw errors.

minecraftserver.GameTestError

spawnSimulatedPlayer

spawnSimulatedPlayer(
    blockLocation: Vector3,
    name?: string,
    gameMode?: GameMode,
): SimulatedPlayer
Parameters
- blockLocation: Vector3
  Location where to spawn the simulated player.
- Optionalname: string
  Name to give the new simulated player.
- OptionalgameMode: GameMode
Returns SimulatedPlayer
Remarks
Creates a new simulated player within the world.

This function can't be called in read-only mode.

Throws
This function can throw errors.

GameTestError

spawnWithoutBehaviors

spawnWithoutBehaviors(
entityTypeIdentifier: string,
blockLocation: Vector3,
): Entity
Parameters
- entityTypeIdentifier: string
- blockLocation: Vector3
  Location where the entity should be spawned.
Returns Entity
Remarks
Spawns an entity at a location without any AI behaviors. This method is frequently used in conjunction with methods like .walkTo to create predictable mob actions.

This function can't be called in read-only mode.

Throws
This function can throw errors.

minecraftserver.GameTestError

spawnWithoutBehaviorsAtLocation

spawnWithoutBehaviorsAtLocation(
entityTypeIdentifier: string,
location: Vector3,
): Entity
Parameters
- entityTypeIdentifier: string
- location: Vector3
  Location where the entity should be spawned.
Returns Entity
Remarks
Spawns an entity at a location without any AI behaviors. This method is frequently used in conjunction with methods like .walkTo to create predictable mob actions.

This function can't be called in read-only mode.

Throws
This function can throw errors.

minecraftserver.GameTestError

spreadFromFaceTowardDirection

spreadFromFaceTowardDirection(
    blockLocation: Vector3,
    fromFace: Direction,
    direction: Direction,
): void
Parameters
- blockLocation: Vector3
  BlockLocation containing a multiface block.
- fromFace: Direction
  Face to spread from. This face must already be set.
- direction: Direction
  Direction to spread. Use the Minecraft.Direction enum to specify a direction.
Returns void
Remarks
Tests that a particular item entity is present at a particular location. If not, an exception is thrown.

This function can't be called in read-only mode.

Throws
This function can throw errors.

GameTestError

startSequence

startSequence(): GameTestSequence
Returns GameTestSequence
A new GameTestSequence with chaining methods that facilitate creating a set of steps.

Remarks
Creates a new GameTestSequence - A set of steps that play out sequentially within a GameTest.

This function can't be called in read-only mode.

succeed

succeed(): void
Returns void
Remarks
Marks the current test as a success case.

This function can't be called in read-only mode.

Throws
This function can throw errors.

succeedIf

succeedIf(callback: () => void): void
Parameters
- callback: () => void
  Callback function that runs. If the function runs successfully, the test is marked as a success. Typically, this function will have .assertXyz method calls within it.
Returns void
Remarks
Runs the given callback. If the callback does not throw an exception, the test is marked as a success.

This function can't be called in read-only mode.

Throws
This function can throw errors.

succeedOnTick

succeedOnTick(tick: number): void
Parameters
- tick: number
  Tick after the start of the GameTest to mark the test as successful.
Returns void
Remarks
Marks the test as a success at the specified tick.

This function can't be called in read-only mode.

Throws
This function can throw errors.

succeedOnTickWhen

succeedOnTickWhen(tick: number, callback: () => void): void
Parameters
- tick: number
  Tick after the start of the GameTest to run the testing callback at.
- callback: () => void
  Callback function that runs. If the function runs successfully, the test is marked as a success.
Returns void
Remarks
Runs the given callback at tick ticks after the start of the test. If the callback does not throw an exception, the test is marked as a failure.

This function can't be called in read-only mode.

Throws
This function can throw errors.

succeedWhen

succeedWhen(callback: () => void): void

Parameters

callback: () => void
Testing callback function that runs. If the function runs successfully, the test is marked as a success.

Returns void

Remarks

Runs the given callback every tick. When the callback successfully executes, the test is marked as a success. Specifically, the test will succeed when the callback does not throw an exception.

This function can't be called in read-only mode.

Throws

This function can throw errors.

Example: simpleMobGameTest.ts

import { Test, register } from "@minecraft/server-gametest";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function simpleMobGameTest(test: Test) {
  const attackerId = MinecraftEntityTypes.Fox;
  const victimId = MinecraftEntityTypes.Chicken;

  test.spawn(attackerId, { x: 5, y: 2, z: 5 });
  test.spawn(victimId, { x: 2, y: 2, z: 2 });

  test.assertEntityPresentInArea(victimId, true);

  test.succeedWhen(() => {
    test.assertEntityPresentInArea(victimId, false);
  });
}
register("StarterTests", "simpleMobTest", simpleMobGameTest).maxTicks(400).structureName("gametests:mediumglass");

succeedWhenBlockPresent

succeedWhenBlockPresent(
    blockType: string | BlockType,
    blockLocation: Vector3,
    isPresent?: boolean,
): void
Parameters
- blockType: string | BlockType
  Type of block to test for.
- blockLocation: Vector3
  Location of the block to test at.
- OptionalisPresent: boolean
  If true, this function tests whether a block of the specified type is present. If false, tests that a block of the specified type is not present.
Returns void
Remarks
Depending on the condition of isPresent, tests for the presence of a block of a particular type on every tick. When the specified block of a type is found or not found (depending on isPresent), the test is marked as a success.

This function can't be called in read-only mode.

Throws
This function can throw errors.

GameTestError

succeedWhenEntityHasComponent

succeedWhenEntityHasComponent(
    entityTypeIdentifier: string,
    componentIdentifier: string,
    blockLocation: Vector3,
    hasComponent: boolean,
): void
Parameters
- entityTypeIdentifier: string
  Type of entity to look for. If no namespace is specified, 'minecraft:' is assumed.
- componentIdentifier: string
  Type of component to test for the presence of. If no namespace is specified, 'minecraft:' is assumed.
- blockLocation: Vector3
  Block location of the entity to test.
- hasComponent: boolean
  If true, this function tests for the presence of a component. If false, this function tests for the lack of a component.
Returns void
Remarks
Tests for the presence of a component on every tick. Depending on the value of hasComponent, when the specified component is found, the test is marked as a success.

This function can't be called in read-only mode.

Throws
This function can throw errors.

succeedWhenEntityPresent

succeedWhenEntityPresent(
    entityTypeIdentifier: string,
    blockLocation: Vector3,
    isPresent?: boolean,
): void

Parameters

entityTypeIdentifier: string
Type of entity to test for (e.g., 'minecraft:skeleton'). If an entity namespace is not specified, 'minecraft:' is assumed.
blockLocation: Vector3
Location of the entity to test for.
OptionalisPresent: boolean
If true, this function tests whether an entity of the specified type is present. If false, tests that an entity of the specified type is not present.

Returns void

Remarks

Depending on the value of isPresent, tests for the presence of an entity on every tick. When an entity of the specified type is found or not found (depending on isPresent), the test is marked as a success.

This function can't be called in read-only mode.

Throws

This function can throw errors.

Example: phantomsShouldFlyFromCats.ts

import { Test, register } from "@minecraft/server-gametest";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function phantomsShouldFlyFromCats(test: Test) {
  test.spawn(MinecraftEntityTypes.Cat, { x: 4, y: 3, z: 3 });
  test.spawn(MinecraftEntityTypes.Phantom, { x: 4, y: 3, z: 3 });

  test.succeedWhenEntityPresent(MinecraftEntityTypes.Phantom, { x: 4, y: 6, z: 3 }, true);
}

register("MobBehaviorTests", "phantoms_should_fly_from_cats", phantomsShouldFlyFromCats)
  .structureName("gametests:glass_cells");

Example: minibiomes.ts

import { EntityComponentTypes } from "@minecraft/server";
import { Test, register } from "@minecraft/server-gametest";
import { MinecraftBlockTypes, MinecraftEntityTypes } from "@minecraft/vanilla-data";

function minibiomes(test: Test) {
  const minecart = test.spawn(MinecraftEntityTypes.Minecart, { x: 9, y: 7, z: 7 });
  const pig = test.spawn(MinecraftEntityTypes.Pig, { x: 9, y: 7, z: 7 });

  test.setBlockType(MinecraftBlockTypes.Cobblestone, { x: 10, y: 7, z: 7 });

  const minecartRideableComp = minecart.getComponent(EntityComponentTypes.Rideable);

  minecartRideableComp?.addRider(pig);

  test.succeedWhenEntityPresent(MinecraftEntityTypes.Pig, { x: 8, y: 3, z: 1 }, true);
}
register("ChallengeTests", "minibiomes", minibiomes).structureName("gametests:minibiomes").maxTicks(160);

triggerInternalBlockEvent

triggerInternalBlockEvent(
    blockLocation: Vector3,
    event: string,
    eventParameters?: number[],
): void
Parameters
- blockLocation: Vector3
- event: string
  Event to trigger. Valid values include minecraft:drip, minecraft:grow_stalagtite, minecraft:grow_stalagmite, minecraft:grow_up, minecraft:grow_down and minecraft:grow_sideways.
- OptionaleventParameters: number[]
Returns void
Remarks
Triggers a block event from a fixed list of available block events.

This function can't be called in read-only mode.

Throws
This function can throw errors.

GameTestError

until

until(callback: () => void): Promise<void>
Parameters
- callback: () => void
  Function with code to evaluate.
Returns Promise<void>
Remarks
This asynchronous function will wait until the code in the specified callback successfully completes. until can be used in conjunction with .assert functions to evaluate that a condition is true.

This function can't be called in read-only mode.

walkTo

walkTo(mob: Entity, blockLocation: Vector3, speedModifier?: number): void
Parameters
- mob: Entity
  Mob entity to give orders to.
- blockLocation: Vector3
  Location where the entity should be walk to.
- OptionalspeedModifier: number
  Adjustable modifier to the mob's walking speed.
Returns void
Remarks
Forces a mob to walk to a particular location. Usually used in conjunction with methods like .spawnWithoutBehaviors to have more predictable mob behaviors. Mobs will stop navigation as soon as they intersect the target location.

This function can't be called in read-only mode.

Throws
This function can throw errors.

GameTestError

walkToLocation

walkToLocation(mob: Entity, location: Vector3, speedModifier?: number): void
Parameters
- mob: Entity
  Mob entity to give orders to.
- location: Vector3
  Location where the entity should be walk to.
- OptionalspeedModifier: number
  Adjustable modifier to the mob's walking speed.
Returns void
Remarks
Forces a mob to walk to a particular location. Usually used in conjunction with methods like .spawnWithoutBehaviors to have more predictable mob behaviors. Mobs will stop navigation as soon as they intersect the target location.

This function can't be called in read-only mode.

Throws
This function can throw errors.

GameTestError

worldBlockLocation

worldBlockLocation(relativeBlockLocation: Vector3): Vector3
Parameters
- relativeBlockLocation: Vector3
  Location relative to the GameTest command block.
Returns Vector3
An absolute location relative to the GameTest command block.

Remarks
From a BlockLocation with coordinates relative to the GameTest structure block, returns a new BlockLocation with coordinates relative to world. Rotation of the GameTest structure is also taken into account.

Throws
This function can throw errors.

minecraftserver.GameTestError

worldLocation

worldLocation(relativeLocation: Vector3): Vector3
Parameters
- relativeLocation: Vector3
  Location relative to the GameTest command block.
Returns Vector3
An absolute location relative to the GameTest command block.

Remarks
From a location with coordinates relative to the GameTest structure block, returns a new location with coordinates relative to world. Rotation of the GameTest structure is also taken into account.

Throws
This function can throw errors.

minecraftserver.GameTestError