MockBukkit Allure

Domain-aware Allure reporting for MockBukkit tests. When a test fails, the report shows Minecraft-level diagnostics instead of a bare stack trace:

• Block mismatch diffs — expected and actual block side by side as isometric renders of the exact block state, built from the game's own blockstate and model definitions (a lit campfire shows flames, an unlit one doesn't), plus the full block data strings (minecraft:grass_block[snowy=false]) with the differing block-state properties highlighted. The required assets are fetched once from Mojang's public version manifest for the exact Minecraft version this build targets and cached in ~/.cache/mockbukkit-allure/textures/<version>/ (they are Mojang's property and never bundled). Blocks that cannot be model-rendered fall back to their flat texture; offline environments fall back further to per-material color swatches.
• Fired-event forensics — every event fired during the failed test, in order, with cancellation state and involved player/block/entity. When MockBukkitAllureAssertions.assertEventFired fails, a dedicated attachment explains the failure ("it never fired" vs. "it fired twice but no instance matched the predicate") and highlights events from the same family in the timeline.
• Chat transcripts — every message each player received, rendered as a Minecraft-style chat window with chat colors and formatting applied (including §x hex colors).
• Scheduler state — where the simulated clock stopped and which tasks were still pending, flagging tasks the clock never reached ("scheduled for tick 20 — needed 10 more ticks").

Passing tests produce no attachments.

Usage

Register the extension next to MockBukkitExtension and use the diff-aware assertions:

@ExtendWith({MockBukkitExtension.class, MockBukkitAllureExtension.class})
class ChestShopTest
{

	@MockBukkitInject
	private ServerMock server;

	@Test
	void breakingTheSignClosesTheShop()
	{
		Block sign = ...;
		// records a rich diff on mismatch, then fails like a normal assertion
		MockBukkitAllureAssertions.assertBlockMaterial(Material.AIR, sign);
	}

}

Allure results are written to build/allure-results by the bundled allure-junit5 listener. Render them with the Allure Gradle plugin or allure serve build/allure-results.

Trying it out

The repo ships intentionally failing demo tests (DemoBlockDiffTest, DemoSessionTest) that are excluded from normal builds:

./gradlew test -Pmockbukkit.allure.demo --tests 'Demo*'
allure serve build/allure-results

The Gradle build fails (the demo tests are supposed to fail) — that's expected. The served report shows a material mismatch (stone vs. grass block) and block-state-only mismatches that only differ in a property — a campfire, a lit redstone lamp, a half-eaten cake, a brewing stand with one bottle, a snowy grass block, a charged respawn anchor and an extended piston — plus an event assertion failure with forensics and chat transcript, and a scheduler failure showing a task the clock never reached.

Architecture

MockBukkitAllureAssertions ──records──▶ FailureContext (thread-local DiffFacts)
                                              │ drained on test failure
MockBukkitAllureExtension ──renders──▶ BlockDiffHtmlRenderer ──▶ AttachmentSink ──▶ Allure

AttachmentSink is the seam for tests and alternative report backends.

Dependencies

• MockBukkit (org.mockbukkit.mockbukkit:mockbukkit-v26.1.2) — the mock server the extension introspects. The targeted MockBukkit/Paper version is configured in gradle.properties (paper.api.version, paper.api.full-version, mockbukkit.version).
• Paper API (compile-only)
• Allure JUnit 5 and JUnit Jupiter

Roadmap

• Variant/element rotations in the model renderer (a rotated campfire currently renders unrotated).
• ItemStack and inventory-grid diffs.
• Tick-anchored session timeline via Allure steps (events, scheduler tasks, commands).
• EventNotFired forensics wired into MockBukkit's own assertEventFired.