القائمة
Use when the user asks to write, add, or improve unit tests for the Ollivanders2 project. Covers project test conventions, MockBukkit constraints, the parallel-execution model, and coverage practices.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when writing or modifying Java production code in the Ollivanders2 project — new spells, effects, potions, listeners, commands, or changes to existing classes. Covers the project's repo-specific conventions distilled from its PR review history: config read-once-at-enable with safe defaults, spell logic stays in the spell class, player-facing failure messages, per-tick scheduler self-termination, shared Material collections in Ollivanders2Common, the copy-paste audit for cloned spell classes, explicit imports, boolean naming polarity, and the mandatory pre-diff self-review checklist. Javadoc rules live in javadoc-writer; test conventions in test-code-writer; review methodology in review-code.
Use when the user asks to write, add, or improve javadoc comments on code. Writes documentation following the Ollivanders2 project's JAVADOC_STANDARDS.md guidelines.
Use when the user asks to review, check, or audit code for issues. Covers logic bugs, javadoc, readability, abstraction, design, and test coverage in the Ollivanders2 project.
| name | test-code-writer |
| description | Use when the user asks to write, add, or improve unit tests for the Ollivanders2 project. Covers project test conventions, MockBukkit constraints, the parallel-execution model, and coverage practices. |
Write JUnit Jupiter unit tests for the Ollivanders2 project. Read the production class under test before writing tests — understand what it does, what its public surface is, and how it integrates with the surrounding system. Read at least one existing sibling test in the same package to match the project's conventions before writing anything new.
For most production classes, the test class is <ClassName>Test.java. Exception: classes that act as implementations of an enumerated type — spells, effects, stationary spells, potions, etc. — use PascalCase based on the SCREAMING_SNAKE_CASE production name, not the raw class name. Examples:
PACK.java → PackTest.javaWINGARDIUM_LEVIOSA.java → WingardiumLeviosaTest.javaItemToItemTransfiguration.java → ItemToItemTransfigurationTest.java (already PascalCase, no transform)Test methods are named <scenarioOrAspect>Test() — e.g. doCheckEffectTest(), radiusTest(), upkeepTest(), invalidTargetTest(). Not test<Thing>() and not bare camelCase verbs. The base class typically declares an abstract doCheckEffectTest() (or equivalent) that subclasses must implement; additional scenario tests follow the same <aspect>Test() shape.
Test packages mirror the production code package layout exactly. A class at Ollivanders/src/net/pottercraft/ollivanders2/spell/PACK.java has its test at Ollivanders/test/java/net/pottercraft/ollivanders2/test/spell/PackTest.java. The test segment is inserted between ollivanders2 and the leaf package; everything below that mirrors prod.
Test classes and test methods get Javadoc, same as production code. Document what the test verifies and why — not just what it does mechanically. Follow JAVADOC_STANDARDS.md.
Any literal whose meaning isn't obvious from context needs an inline comment explaining where it comes from. Examples: 1728 // 27 slots × 64 stack depth — https://minecraft.fandom.com/wiki/Chest, 20 // ticks per second. Prefer a named local variable when the number is reused.
Worlds created via mockServer.addSimpleWorld(...) use a short, descriptive name — typically the spell or effect name, with a scenario suffix when one test class needs several worlds. The first/canonical test in a spell test class commonly passes getSpellType().getSpellName(); sibling methods append a scenario tag (e.g. "PackEnderChest", "PackShulkerBox").
Never copy a constant from production code into a test. If the test needs a value that lives in production (e.g. a spell's maxDuration, a radius, a cooldown), add a copy-returning getter to the production class and call it from the test. The production code becomes the single source of truth, and the test stays correct when the value changes.
Strict rules for these getters:
@BeforeAll vs @BeforeEachSpell tests load the plugin once via a static @BeforeAll and reuse it across all methods in the class (O2SpellTestSuper.globalSetUp). Effect tests load a fresh plugin per method via @BeforeEach (EffectTestSuper.setUp). The split exists because effects mutate plugin-scoped state during a method, while spell tests are read-only against the plugin. When writing a new test class, match whichever base class you extend — don't reinvent the lifecycle. When designing a new base class, choose @BeforeEach if your category mutates plugin state, @BeforeAll otherwise (it's much faster).
When multiple test classes share setup or assertions, push the common code up into a base class. Look at existing bases like O2SpellTestSuper for the pattern: shared MockBukkit lifecycle, shared castSpell helpers, abstract methods that subclasses must implement. New test classes should extend the appropriate base when one exists, and you should propose a new base when you see a third copy of the same setup emerging.
Helpers that are useful across many unrelated test classes belong in TestCommon (or another *Common test utility), not duplicated per test. Examples: createBlockBase, faceTarget, setPlayerSpellExperience. Helpers that are only useful to one test class or to one test family stay local to that class or its base.
Before writing new fixture or assertion code, check whether one of these already exists:
Test-side utilities:
TestCommon): createBlockBase(location, size), createNorthSouthBlockWall(location, size), createEastWestBlockWall(location, size). Use these instead of hand-rolled nested loops.TestCommon): getPlayerInventoryItem(player, material), getPlayerInventoryItem(player, material, name), amountInPlayerInventory(player, material, name). These handle null safety and book/display-name edge cases.TestCommon): cleanChatMessage(message) to strip color codes before assertion, clearMessageQueue(player) to drain pending messages before re-checking output.O2PlayerCommon): rightWand, wrongWand, elderWand constants. Pass these to castSpell(...) overloads instead of magic doubles when testing wand-dependent behavior.Production *Common utilities — also for tests:
Tests can and should call the production helper classes (Ollivanders2Common, EntityCommon, BlockCommon, O2PlayerCommon, etc.) directly when they need the same logic the production code uses. Don't reimplement entity radius scans, block adjacency checks, distance math, player metadata lookups, etc. — find the existing helper first. If a test needs to assert "the spell affected the right entities", the most accurate check is usually "compare against what EntityCommon.getEntitiesInRadius(...) returns at the same location and radius". Reimplementing the logic in the test risks the test agreeing with itself but disagreeing with prod.
Aim for high line coverage of meaningful behavior. Skip:
Always cover:
JUnit Jupiter runs test methods in parallel by default. MockBukkit's ServerMock is a shared static instance across the methods of a test class (set up in @BeforeAll), and the world/entity/scheduler state inside it is global. If two parallel test methods both mutate that shared state — spawning entities, changing blocks, casting spells, advancing the scheduler — they will interfere with each other in nondeterministic ways.
Rule: any sequence of operations that depends on a specific state evolution must live inside a single @Test method, not split across methods. Use sub-sections within one method (with comments delimiting them) when you need multiple scenarios that share state assumptions. Splitting only makes sense when the scenarios are genuinely independent (different worlds, different players, no overlap).
When in doubt, keep related scenarios together. The doCheckEffectTest pattern in the existing spell tests is the canonical example.
Some Bukkit/Paper APIs are not implemented in MockBukkit and will throw UnimplementedOperationException (or similar) if called from a test. Examples seen so far: World.createExplosion, certain entity state queries.
When production code needs to call one of these, wrap the call so it's skipped under test:
if (!Ollivanders2.testMode)
world.createExplosion(location, power);
This sacrifices coverage of the wrapped line in exchange for letting the rest of the method be tested. Keep the wrapped block as small as possible — only the actually-unimplemented call goes inside the guard, not the surrounding logic.
Ollivanders2.testMode is set to true in the @BeforeAll of O2SpellTestSuper (and equivalents). Production never sets it.
MockBukkit does not synthesize Bukkit events the way real Paper does — gameplay actions in a test won't automatically generate the corresponding event. To exercise an event handler, construct the event yourself, call mockServer.getPluginManager().callEvent(event), then performTicks(...) afterward to give the handler time to run.
Some Bukkit effects are instant — they fire once on application and are never stored in the player's active effects list. PotionEffectType.INSTANT_HEALTH is the canonical example: player.hasPotionEffect(INSTANT_HEALTH) returns false even immediately after addPotionEffect(...), because the effect is consumed on application. MockBukkit also doesn't simulate the gameplay side-effects of effects (e.g., health changes from healing, damage from harming), so you can't observe the result either.
To verify that an instant or transient effect was actually applied, register a temporary EntityPotionEffectEvent listener before casting the spell:
AtomicBoolean effectApplied = new AtomicBoolean(false);
mockServer.getPluginManager().registerEvents(new Listener() {
@EventHandler
public void onEffect(EntityPotionEffectEvent event) {
if (event.getEntity().equals(target)
&& event.getNewEffect() != null
&& event.getNewEffect().getType().equals(PotionEffectType.INSTANT_HEALTH)) {
effectApplied.set(true);
}
}
}, testPlugin);
castSpell(caster, location, targetLocation);
mockServer.getScheduler().performTicks(20);
assertTrue(effectApplied.get(), "INSTANT_HEALTH was not applied to target");
This works because MockBukkit fires EntityPotionEffectEvent when addPotionEffect is called, even for instant effects. The listener catches the event in-flight before MockBukkit discards the effect. Use AtomicBoolean (not a plain boolean) because the listener runs in the event dispatch context.
This same pattern works for any effect or event that is difficult to observe after the fact — register a listener, let the spell run, then assert against the captured state.
testMode guard, not test-side workaroundsWhen a spell test is intermittent because the spell rolls a random chance, the project convention is to make the roll deterministic in the production code with an Ollivanders2.testMode guard — never retry loops or inflated-experience magic values in the test. Preferred form:
if (Ollivanders2.testMode && usesModifier >= O2Spell.spellMasteryLevel)
successRate = 100; // else: fall through to the normal random roll
The >= is deliberate: casting at spellMasteryLevel is guaranteed under test, while lower-skill casts still exercise the real roll (so zero-experience "should fail" tests stay deterministic without any guard). Only force the specific case the test needs — don't blanket-bypass, or failure-path tests break. Established examples: OBLIVIATE.canContinue, LEGILIMENS, LAPIFORS.doInitSpell, CISTEM_APERIO.doCheckEffect. Do NOT testMode-bypass core spell logic (e.g. a facing-block requirement) — that changes what the test tests; skip instead (see getLineOfSight below).
The project pins mockbukkit-v1.21:4.71.0. These bite repeatedly:
BlockMock.getLocation() returns a shared mutable Location field (CraftBlock returns a fresh copy). .clone() before mutating, always — mutating it corrupts the block's own location and any map key derived from it.BlockMock has no equals/hashCode — object identity only. HashMap<Block, ...> works in-game (CraftBlock compares coordinates) but not under test; production code that must be testable keys by block-aligned Location (value equality) instead.callEvent does NOT reach a listener the spell self-registered at runtime (registerEvents(this, plugin) in a spell constructor) — only centrally registered listeners. To test a spell's own @EventHandler, call the handler method directly; you then can't test (un)registration, only handler logic.getLineOfSight throws UnimplementedOperationException — spells with a facing-block requirement can't have their success path tested. Skip with Assumptions.assumeTrue(...) plus a TODO; do not testMode-bypass the facing check.launchProjectile creates but never registers the projectile — not in world.getEntities(), no ProjectileLaunchEvent. Observable scope: assert the spell isKilled() after a tick (an unsupported projectile class throws instead). Contrast World.spawnEntity, which IS registered and observable.TestCommon.faceTarget can't produce a clean horizontal vector (vertical component always ≥ ±0.5 for integer target Y). For axis-aligned aims, target straight down (exact (0,-1,0)) or offset on one horizontal axis and flatten.World.spawnFallingBlock IS implemented and observable — but throws on AIR blockData; skip air upstream.MockBukkit's BlockState snapshots can diverge from production Paper semantics for some Container types (notably Chest). When a test reads inventory state that the production code has just written, prefer re-fetching the state via block.getState() immediately before the assertion rather than reusing a stale snapshot reference. If a test still fails despite a fresh snapshot, suspect a MockBukkit-vs-Paper API divergence and check the API references below.
You are pre-authorized to read the local Spigot Javadoc for any read-only operation (Read, Glob, Grep, Bash with grep/cat/find — not modifications). It lives at:
/Users/kristin/minecraft/spigot javadoc/index.html
Class pages follow the standard javadoc layout: org/bukkit/block/Chest.html, org/bukkit/inventory/Inventory.html, etc. Use Read or Grep against these files when you need to verify a method signature, return type, class hierarchy, or snapshot/live semantics — do not guess at the API. Note that WebFetch does not accept file:// URLs; use Read or Bash for local files.
For MockBukkit-specific behavior, the published javadocs are at:
TestCommon helpers you can reuse../gradlew test --tests <FQCN>) to get fast feedback.git add any newly created files so they're staged and visible in git status — new test files are easy to forget because they're untracked, and a missing file won't show up in a diff review.