Getting Started Tutorial

Estimated Time: 5 minutes Prerequisites: Java 21, Docker, Pilaf installed

Learning Objectives

After completing this tutorial, you will be able to:

Start a Pilaf backend (Docker)
Run an existing test story
Understand the basic structure of a test story
Create and run a simple test story

Step 1: Start the Backend

Start a PaperMC server using Docker:

cd pilaf/docker
docker-compose -f docker-compose.pilaf.yml up -d

Wait for the server to start:

# Check logs for "Done" message
docker-compose -f docker-compose.pilaf.yml logs -f

Press Ctrl+C when you see "Done (x.xxs)!" in the output.

Verify the server is running:

docker ps | grep minecraft

You should see the PaperMC container running on ports 25565 and 25575.

Step 2: Run the Demo Story

Run the demo story included with Pilaf:

cd pilaf
./gradlew run --args="--backend docker demo-story.yaml"

You should see output similar to:

[INFO] Pilaf Test Runner v0.1.0
[INFO] Backend: docker
[INFO] Loading story: demo-story.yaml
[INFO] Story: Demo Story
[INFO] Description: Demonstrates basic Pilaf features
[INFO]
[INFO] Setup Actions:
[INFO]   1. Execute RCON command (op test_player)
[INFO]
[INFO] Test Steps:
[INFO]   1. Send chat message (/give @p diamond_sword)
[INFO]   2. Wait 2 seconds
[INFO]   3. Check log for "Given diamond_sword"
[INFO]
[INFO] Cleanup Actions:
[INFO]   1. Execute RCON command (deop test_player)
[INFO]
[INFO] Executing setup...
[INFO] [PASS] Execute RCON command (op test_player)
[INFO]
[INFO] Executing steps...
[INFO] [PASS] Send chat message (/give @p diamond_sword)
[INFO] [PASS] Wait 2 seconds
[INFO] [PASS] Check log for "Given diamond_sword"
[INFO]
[INFO] Executing cleanup...
[INFO] [PASS] Execute RCON command (deop test_player)
[INFO]
[INFO] Test Result: PASSED
[INFO] Report: target/pilaf-reports/report.html

Step 3: Examine the Demo Story

Open demo-story.yaml in your editor:

name: "Demo Story"
description: "Demonstrates basic Pilaf features"

setup:
  - action: "execute_rcon_command"
    command: "op test_player"
    assertions:
      - type: "assert_success"

steps:
  - action: "send_chat"
    player: "test_player"
    message: "/give @p diamond_sword"
    assertions:
      - type: "assert_success"

  - action: "wait"
    seconds: 2

  - action: "check_log"
    pattern: "Given diamond_sword"
    assertions:
      - type: "assert_match"

cleanup:
  - action: "execute_rcon_command"
    command: "deop test_player"

Key components:

name: Descriptive name for the test
description: What the test validates
setup: Prepares the environment (ops the test player)
steps: Main test actions (gives item, waits, checks log)
cleanup: Restores the environment (deops the player)

Step 4: Create Your Own Story

Create a new file my-first-test.yaml:

name: "My First Test"
description: "Testing the give item command"

setup:
  - action: "execute_rcon_command"
    command: "op myplayer"
    assertions:
      - type: "assert_success"

steps:
  - action: "give_item"
    player: "myplayer"
    item: "bow"
    count: 1
    assertions:
      - type: "assert_success"

  - action: "wait"
    seconds: 1

  - action: "check_log"
    pattern: "Given bow"
    assertions:
      - type: "assert_match"

cleanup:
  - action: "execute_rcon_command"
    command: "deop myplayer"

Run your test:

./gradlew run --args="--backend docker my-first-test.yaml"

Expected output:

[INFO] Test Result: PASSED

Step 5: View the Report

Open the generated HTML report:

# macOS
open target/pilaf-reports/report.html

# Linux
xdg-open target/pilaf-reports/report.html

# Windows
start target/pilaf-reports/report.html

The report includes:

Test summary (PASSED/FAILED)
Step-by-step execution log
Assertion results
Execution timestamps

Summary

You’ve successfully:

Started a Pilaf backend
Run an existing test story
Understood story structure (setup, steps, cleanup)
Created and ran your own test story
Viewed the test report

Next Steps

Continue learning with:

Writing Stories Guide - Deep dive into YAML DSL
Best Practices - Tips for effective tests
Command Reference - All available actions

Cleanup (Optional)

When you’re done experimenting, stop the Docker server:

cd pilaf/docker
docker-compose -f docker-compose.pilaf.yml down