Unit Testing

Unit Testing with Race Test Kit

The Race test kit makes unit testing straightforward. You can:

1. Create a test client: Instantiate a TestClient object to simulate a player or server.

// Rust example
use race_test::TestClient;
use race_core::types::ClientMode;

// Create a test client to simulate a player
let mut player = TestClient::player("Alice");

// Create a test client to simulate a transactor server
let mut transactor = TestClient::transactor("Foo");

1. Build a test game account: Use the TestGameAccountBuilder to create a mock game account with the desired initial state and configuration.

// Rust example
use race_test::TestGameAccountBuilder;

// Define your game's account data structure
#[derive(BorshSerialize, BorshDeserialize)]
struct MyGameData {
    // ... game-specific data fields
}

// Create a test game account with initial data and configuration
let game_account = TestGameAccountBuilder::default()
    .add_player(&mut player, 1000) // Add a player with initial balance
    .set_transactor(&mut transactor) // Set the transactor server
    .with_data(MyGameData { /* ... */ }) // Provide initial game data
    .build();

1. Initialize the game context and handler: Create a GameContext object based on the test game account and initialize your game handler using the TestHandler.

// Rust example
use race_core::context::GameContext;
use race_test::TestHandler;

// Create the game context
let mut ctx = GameContext::try_new(&game_account).unwrap();

// Initialize your game handler (replace MyGameHandler with your actual handler)
let mut handler = TestHandler::<MyGameHandler>::init_state(&mut ctx, &game_account).unwrap();

1. Send events and observe outcomes: Use the test client to send custom and built-in events to the game handler. Assert that the game state and generated effects match your expectations.

// Rust example
use race_api::event::Event;

// Create a custom game event (replace MyCustomEvent with your event type)
let custom_event = Event::custom(player.id(), &MyCustomEvent { /* ... */ });

// Send the event to the game handler
handler.handle_event(&mut ctx, &custom_event).unwrap();

// Assert that the game state and effects are as expected
assert_eq!(ctx.get_status(), GameStatus::Running); // Example assertion
// ... more assertions

Remember:

• Replace MyGameHandler and MyCustomEvent with your actual game handler and custom event types.

• Write specific assertions to verify the expected behavior of your game logic after handling events.

By following these steps, you can effectively unit test your Race Protocol game bundles using the Race test kit.

Examples

WASM Bundle (Rust)

Here's an example of unit testing a custom event handler within the WASM bundle using the Race test kit in Rust:

use race_test::{TestClient, TestGameAccountBuilder, TestHandler};

let game_account = TestGameAccountBuilder::new().build();
let context = GameContext::new(game_account);
let handler = TestHandler::new(game_bundle, encryptor, client, decryption_cache);

let mut test_client = TestClient::new(context, handler);

// Send a custom event and assert the expected state update
test_client.submit_event(CustomEvent { ... });

let updated_state = test_client.context().handler_state();

assert_eq!(updated_state, expected_state);

This code snippet demonstrates how to use the test kit in Rust to create a test client, build a mock game account, and send a custom event to the game handler. The test then asserts that the resulting game state matches the expected outcome.

Client-Side (TypeScript)

Here's an example of unit testing in TypeScript using Race JS SDK

import { TestClient, TestGameAccountBuilder, TestHandler } from '@race-foundation/sdk-core';

const gameAccount = new TestGameAccountBuilder().build();
const context = new GameContext(gameAccount);
const handler = new TestHandler(gameBundle, encryptor, client, decryptionCache);

const testClient = new TestClient(context, handler);

// Send a custom event and assert the expected state update
await testClient.submitEvent({ type: 'playerAction', ... });

const updatedState = context.handlerState;

assert.deepEqual(updatedState, expectedState);

This code snippet demonstrates how to use the test kit to create a test client, build a mock game account, and send a custom event to the game handler. The test then asserts that the resulting game state matches the expected outcome.