Skip to content

🧪 RevFramework Pickups — Testing Philosophy

This document explains how the Pickups system is tested, what the tests are designed to protect, and what they intentionally do not claim.

This is not marketing material.

It is an engineering-facing overview of the testing philosophy behind the Pickups system.

🎯 The Goal of the Tests

The Pickups tests exist to protect:

  • behavioural guarantees
  • regression safety
  • effect application semantics
  • trigger and relay behaviour
  • authority and gating behaviour
  • cooldown consistency
  • decorator execution rules
  • Unity lifecycle assumptions

The tests are designed to answer questions like:

  • “Does this pickup still apply the correct effect?”
  • “Did a refactor accidentally change null-damageable behaviour?”
  • “Does authority denial still block consumption?”
  • “Do decorators still execute in the intended order?”
  • “Does the runtime trigger path still work in both 2D and 3D?”
  • “Does destroy-on-use still behave correctly in Play Mode?”

The goal is predictability, not “perfect software.”

🔒 Hostile Consumer Tests

Most Pickups tests are written as Hostile Consumer tests.

This means the tests interact with the system exactly the way a real project would:

  • through public APIs
  • through supported interfaces
  • through supported extension points
  • through public Unity components
  • without relying on internal implementation details

These tests intentionally avoid depending on private fields or unsupported runtime access.

If a Hostile test passes, the supported Pickups contract is behaving correctly.

⚙️ InternalTruth Tests

The Pickups system also contains a smaller set of InternalTruth tests.

These tests validate framework assumptions that are important for long-term stability but are not part of the supported public API.

Examples include:

  • authority cache behaviour
  • decorator before/wrapped/after execution order
  • decorator cancellation behaviour
  • internal effect construction details
  • internal shield-effect behaviour
  • private latch re-arm assumptions where useful

InternalTruth tests are intentionally separated from Hostile tests.

They exist to protect framework integrity during future refactors.

They are not an extension mechanism.

They are not a promise that users can rely on internals.

▶️ PlayMode Tests

Pickups also includes PlayMode tests for Unity runtime behaviour.

These tests validate flows that cannot be fully trusted through EditMode method calls alone.

Examples include:

  • 2D physics trigger forwarding
  • 3D physics trigger forwarding
  • relay-to-pickup-to-effect runtime flow
  • same-physics-step duplicate consume prevention
  • latch re-arming after FixedUpdate
  • destroy-on-use behaviour through Unity’s normal runtime lifecycle

These tests are important because Pickups sits directly on Unity trigger callbacks.

EditMode tests prove the logic.

PlayMode tests prove the scene/runtime path.

🧩 What the Pickups Tests Validate

The current Pickups test suite validates behaviour including:

Effect Core Contracts

  • null-damageable rejection
  • explicit null-damageable allowance
  • decorator-chain null allowance
  • cooldown owner resolution
  • cooldown blocking
  • cooldown clearing
  • zero-duration expiry cleanup

Effect Runner Behaviour

  • context-aware effect dispatch
  • classic effect fallback
  • default no-context values
  • null-effect no-op safety
  • context-aware bypass of base null-damageable gating
  • context-aware bypass of base cooldown gating

Effect Factory Behaviour

  • null definition handling
  • null core handling
  • undecorated core return
  • decorator priority ordering
  • missing creator handling
  • throwing creator isolation
  • custom registry replacement
  • creator registration and unregistration

Decorator Behaviour

  • before → wrapped → after execution order
  • cancellation before wrapped effect
  • cancellation skipping after logic
  • null wrapped-effect safety
  • conditional tag blocking
  • conditional random-chance blocking
  • debug logging behaviour
  • sound warning behaviour
  • persistent VFX spawning

Definition Behaviour

  • animator-trigger definition creation
  • teleport definition creation
  • VFX burst definition creation
  • shield definition creation through internal truth coverage

Runtime Effects

  • animator trigger null-damageable allowance
  • teleport movement
  • teleport null-context safety
  • VFX null-context safety
  • VFX null-prefab safety
  • composite effect ordering
  • composite null-child safety
  • shield system creation and reuse
  • shield absorb/depletion behaviour

Trigger Pickup Behaviour

  • null effect safety
  • layer filtering
  • tag filtering
  • damageable requirement enforcement
  • null-damageable allowance
  • parent damageable lookup
  • duplicate same-step consume prevention
  • no-op stay/exit behaviour
  • authority denial blocking consumption
  • authority approval allowing consumption
  • destroy-on-use lifecycle behaviour

Relay and Physics Behaviour

  • 2D relay forwards enter/stay/exit
  • 3D relay forwards enter/stay/exit
  • 2D relay can drive a real pickup consume
  • 3D relay can drive a real pickup consume
  • relay components force trigger collider mode
  • actor root resolution through Rigidbody / Rigidbody2D paths

Interactable Pickup Behaviour

  • prompt visibility rules
  • player/root actor detection
  • success event flow
  • failure event flow
  • success feedback hooks
  • failure feedback hooks
  • facing checks
  • respawn visibility restoration

Authority Behaviour

  • same-object authority resolution
  • parent authority resolution
  • scene-level caching
  • cache invalidation
  • disabled cached authority replacement
  • component overload resolution
  • default binder allow/deny behaviour

🧠 Deterministic Test Infrastructure

The Pickups tests use small deterministic test doubles including:

  • test pickup effects
  • test context-aware effects
  • test damageable components
  • test authority providers
  • test trigger receivers
  • test feedback components
  • test decorator creators
  • test decorator registries

These fakes are intentionally small and explicit.

They support:

  • call-count assertions
  • ordering assertions
  • allow/deny toggles
  • null-safety checks
  • context capture
  • runtime trigger verification
  • predictable effect execution

This allows pickup behaviour to be tested without relying on full game systems.

❌ What These Tests Do NOT Claim

The tests do not claim:

  • the framework is bug-free
  • every possible pickup design is covered
  • multiplayer correctness is guaranteed
  • third-party authority providers are validated
  • third-party inventory systems are validated
  • third-party health systems are validated
  • every physics edge case is covered
  • large-scale performance limits are proven
  • every possible decorator combination is exhaustively tested

The tests validate framework behaviour and guarantees — not every possible project implementation.

🧩 The Philosophy

RevFramework systems are designed around:

  • explicit guarantees
  • predictable behaviour
  • transparent failure handling
  • modular integration seams
  • public API discipline

The Pickups tests exist to lock those guarantees down over time as the framework evolves.

The goal is not to pretend pickup systems are complicated magic.

The goal is to prove that the important seams keep behaving exactly as documented:

  • effects apply when they should
  • effects do not apply when they should not
  • authority can block consumption
  • decorators wrap predictably
  • triggers reach the pickup receiver
  • Unity runtime lifecycle assumptions stay true

That is the difference between a demo script and a framework component.

TL;DR

The Pickups tests are designed to protect guarantees, not pretend software can never fail.

Hostile tests validate supported public behaviour.

InternalTruth tests protect hidden framework assumptions.

PlayMode tests prove the Unity runtime path.

Together, they help keep Pickups predictable as RevFramework evolves.