Testing Philosophy

What NOT to Assert

• Private/protected property values
• Internal data structures or storage format
• Which private helper methods were called
• How a value was computed (only that the result is correct)
• Static property names or internal variable names

Examples

Good: Test behavior through the public interface

// Tests what consumers see: get/has return correct values
public function test_get_returns_stored_value(): void {
    $registry = new Registry(['name' => 'pitch-vault']);
    $this->assertSame('pitch-vault', $registry->get('name'));
}

// Tests interface compliance (consumers depend on this contract)
public function test_implements_container_interface(): void {
    $registry = new Registry([]);
    $this->assertInstanceOf(ContainerInterface::class, $registry);
}

// Tests error behavior consumers will encounter
public function test_get_throws_not_found_exception_for_unknown_key(): void {
    $registry = new Registry([]);
    $this->expectException(NotFoundExceptionInterface::class);
    $registry->get('nonexistent');
}

Good: Test the guarantee, not the mechanism

// Consumers depend on getting the same instance - test that
public function test_initialize_returns_same_instance(): void {
    $first  = PitchVault::initialize('/path/to/plugin.php');
    $second = PitchVault::initialize('/path/to/plugin.php');
    $this->assertSame($first, $second);
}

Bad: Testing implementation details

// BAD: Asserts on internal property name
public function test_singleton_stores_in_static_property(): void {
    PitchVault::initialize('/path');
    $ref = new ReflectionClass(PitchVault::class);
    $prop = $ref->getProperty('instance'); // couples to property name
    $this->assertNotNull($prop->getValue());
}

// BAD: Tests internal array structure instead of public behavior
public function test_registry_internal_items_array(): void {
    $registry = new Registry(['key' => 'val']);
    $ref = new ReflectionClass($registry);
    $items = $ref->getProperty('items');
    $this->assertArrayHasKey('key', $items->getValue($registry));
}

Good: Test observable side effects

// Tests that the WP hook was registered (consumer-visible behavior)
public function test_init_hooks_register_on_init(): void {
    $cpt = new TestablePostType('test_cpt', 'Test', 'prefix', 'manage_options');
    $cpt->init();
    $this->assertNotFalse(has_action('init', [$cpt, 'register']));
}

// Tests that WP receives the right arguments (the external contract)
public function test_register_meta_prefixes_field_keys(): void {
    Functions\expect('register_post_meta')
        ->once()
        ->with('test_cpt', 'prefix_field_a', \Mockery::type('array'));
    $cpt = new TestablePostType('test_cpt', 'Test', 'prefix', 'manage_options');
    $cpt->register_meta();
}

Checklist Before Writing a Test

1. Am I testing a public method or observable side effect?
2. Would this test break if I refactored internals without changing behavior?
   • If yes, rewrite the test.
3. Does this test use Reflection to access private members?
   • Only acceptable in tearDown() for cleanup (e.g., resetting singletons). Never in assertions.
4. Am I asserting the result or the mechanism?
   • Assert the result.