Flutter & shipping

Testing

Test game logic with a bare World or a headless Engine, step time yourself, and load scenes and assets without a device.

Make a new engine, or a new world, in each test and dispose it afterwards. Nothing ticks by itself in a test, because there is no GameWidget driving the loop: you step time yourself.

A world on its own

For plain ECS logic, a World() on its own is enough, and much faster than an engine. It makes a fresh context with the ECS core's components (the transform, the parent and children links, tags) and disposes it with itself; a test that reads or writes scenes gives it the engine's too, World(extensions: [BuiltInComponents.extension]). Add the systems you are testing and call world.update(1 / 60) once per step:

test/movement_test.dart
import 'package:flutter_test/flutter_test.dart';
import 'package:just_game_engine/just_game_engine.dart';

void main() {
  TestWidgetsFlutterBinding.ensureInitialized();

  test('velocity moves an entity', () {
    final world = World()..initialize();
    addTearDown(world.dispose);
    world.addSystem(MovementSystem());

    final box = world.createEntityWithComponents([
      TransformComponent(),
      VelocityComponent(velocity: Vector3(60, 0, 0)),
    ]);
    for (var i = 0; i < 30; i++) {
      world.update(1 / 60);
    }

    expect(
      box.getComponent<TransformComponent>()!.position.x,
      closeTo(30, 1e-9),
    );
  });
}

A headless engine

When a test needs the engine's subsystems, make an engine with DefaultSystems.headless: every standard system except rendering and audio. Await initialize(), register dispose as a tear-down, and step its world directly.

test/level_test.dart
import 'package:flutter_test/flutter_test.dart';
import 'package:just_game_engine/just_game_engine.dart';

void main() {
  TestWidgetsFlutterBinding.ensureInitialized();

  test('a level loads', () async {
    final engine = Engine(
      config: const EngineConfig(defaultSystems: DefaultSystems.headless),
    );
    addTearDown(engine.dispose);
    await engine.initialize();

    SceneLoader.loadString(engine.world, """
      {"version": 11, "name": "test", "mode": "2d", "entities": [
        {"name": "Spawn", "components": [
          {"type": "TransformComponent", "fields": {}},
          {"type": "SpawnComponent", "fields": {"spawner": "player"}}
        ]}
      ]}
    """);
    engine.world.update(1 / 60);

    expect(SpawnPoints.first(engine.world, 'player')?.name, 'Spawn');
  });
}

In a test, the engine's storage cannot open its file, so engine.cache keeps everything in memory (isUsingMemoryFallback is true), and the audio engine's failure to start is logged and ignored. Neither stops the test.

Running the whole loop

world.update runs the systems only. To run a step the way a game does, with the input update and every other update task, start the engine and tick its game loop with frame timestamps. The first tick only starts the clock; after that, each tick 1/60 s later runs one fixed step.

test('a pressed key reaches the actions', () async {
  final engine = Engine();
  addTearDown(engine.dispose);
  await engine.initialize();
  engine.input.loadAsset(InputActionAsset.parse(inputJson)); // your asset
  engine.start();

  const frame = Duration(microseconds: 16667);
  engine.gameLoop.tick(Duration.zero); // starts the clock
  engine.input.handleKeyEvent(
    const KeyDownEvent(
      physicalKey: PhysicalKeyboardKey.space,
      logicalKey: LogicalKeyboardKey.space,
      timeStamp: Duration.zero,
    ),
  );
  engine.gameLoop.tick(frame); // one fixed step

  expect(engine.input.actions.action('player/jump').isPressed, isTrue);
});

KeyDownEvent and the key classes come from package:flutter/services.dart. While the engine is paused, a tick still updates input, so you can test pause menus the same way.

Assets in tests

  • SceneLoader.loadString and SceneLoader.load read a scene without an asset bundle.
  • SceneLoader.loadAsset reads through world.context.bundle. An engine made with Engine(context: EngineContext(bundle: myTestBundle)) loads from a test bundle of your own, such as a CachingAssetBundle subclass that serves files from a map.
  • SceneLoader.loadManifest does not use the context's bundle: it reads scenes.json from Flutter's rootBundle unless you pass it one, so give it the same test bundle with loadManifest(bundle: myTestBundle).
  • A context you pass in is yours to dispose: call context.dispose() once the engine has been disposed.

Widget tests

GameWidget works in testWidgets. Run the engine's asynchronous work with tester.runAsync, and pump frames to tick it:

testWidgets('the game draws', (tester) async {
  final engine = Engine(
    config: const EngineConfig(defaultSystems: DefaultSystems.all),
  );
  addTearDown(() => tester.runAsync(engine.dispose));

  await tester.pumpWidget(
    MaterialApp(home: GameWidget(engine: engine, showFPS: false)),
  );
  await tester.runAsync(engine.initialize);
  engine.start();

  for (var i = 0; i < 10; i++) {
    await tester.pump(const Duration(milliseconds: 16));
  }
  expect(engine.performanceStats['frame'], greaterThan(0));
});

A GameWidget built before initialize() finishes picks the engine up once it is ready, so the order above works without a rebuild.

This page as Markdown