Quick Start

Quick Start Guide

Get started with Pilaf in 5 minutes. This guide walks you through your first test story.

Prerequisites

Ensure you have completed the Installation Guide. You should have:

Java 21 installed
Docker and Docker Compose (for Docker backend)
Pilaf cloned or downloaded

Step 1: Start the Backend

Option A: Docker Backend

Start a PaperMC server with Docker:

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

Wait for the server to start (check logs):

docker-compose -f docker-compose.pilaf.yml logs -f

Look for "Done" in the output, then press Ctrl+C.

Option B: Mineflayer Backend

If you prefer the Mineflayer backend:

# Start the Mineflayer bridge
cd pilaf/mineflayer-bridge
npm install
node server.js &

Option C: HeadlessMc Backend

For CI/CD environments:

./gradlew run --args="--backend headlessmc --config config-headlessmc.yaml"

Step 2: Run Your First Test Story

Use 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
[INFO] Loading story: demo-story.yaml
[INFO] Backend: docker
[INFO] Executing setup actions...
[INFO] Step 1: Execute RCON command (op test_player)
[INFO] Step 2: Send chat message
[INFO] Step 3: Wait 2 seconds
[INFO] ...
[INFO] Test completed: PASSED
[INFO] Report generated: target/pilaf-reports/report.html

Step 3: Examine the Test Story

Open demo-story.yaml to understand the structure:

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"

Story Components

name: Descriptive name for the test
description: What this test validates
setup: Actions to prepare the test environment
steps: Main test actions and assertions
cleanup: Actions to restore the environment

Step 4: Create Your Own Test Story

Create a new file my-test.yaml:

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

setup:
  - action: "execute_rcon_command"
    command: "op myplayer"

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

  - action: "wait"
    seconds: 1

  - action: "check_inventory"
    player: "myplayer"
    item: "bow"
    count: 1
    assertions:
      - type: "assert_contains"

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

Run your test:

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

Step 5: View the Report

Open the generated HTML report:

open target/pilaf-reports/report.html

The report includes:

Test summary (passed/failed)
Step-by-step execution log
Assertions and their results
Error messages (if any)

Common Test Patterns

Testing Server Commands

steps:
  - action: "execute_rcon_command"
    command: "/time set night"
    assertions:
      - type: "assert_success"

Testing Player Actions

steps:
  - action: "send_chat"
    player: "test_player"
    message: "/home set"
    assertions:
      - type: "assert_success"

Testing Assertions

steps:
  - action: "check_log"
    pattern: "Player spawned"
    assertions:
      - type: "assert_match"
        invert: false

Next Steps

Writing Stories Guide - Deep dive into YAML DSL
Command Reference - Complete list of actions
Architecture Overview - Understand the system

Troubleshooting

Test Fails Immediately

Check that your backend is running:

# For Docker backend
docker ps | grep minecraft

# For Mineflayer backend
curl http://localhost:3000/health

Connection Refused Error

Verify your configuration in pilaf.yaml:

server:
  host: "localhost"
  rcon_port: 25575

Timeout Error

Increase the timeout in your story:

- action: "wait"
  seconds: 10  # Increase from default