Monkey Laravel Package

Product Decisions This Supports

• Feature go/no-go for WordPress-facing code. Brain Monkey lets the team unit-test plugin logic that touches add_action, add_filter, get_option, wp_remote_*, wp_enqueue_*, and shortcodes without booting WordPress. That gives you a real pass/fail signal on new features before integration or QA time is spent, which shortens the decision loop on scope and acceptance. Release 2.7.0 extends this to has_filter() / has_action() with the $priority argument added in WordPress 6.9, so hook-priority assertions — "did we register at priority 20 so we run after WooCommerce?" — are now a first-class unit test rather than an integration-only concern.
• Build vs. buy on test infrastructure. The alternative is writing and maintaining an in-house WP function-mocking harness, or paying the CI-time cost of full WordPress integration tests for every case. Adopting an MIT-licensed, dev-only package is the cheaper path; the buy decision here is effectively free in runtime terms.
• Roadmap risk for refactors and platform upgrades. PHP version bumps, WooCommerce/Gutenberg compatibility work, and "extract business logic out of hooks" refactors are only safe if there is a fast test net. This package is the enabler for those roadmap items — it is infrastructure that de-risks the bigger bets rather than a feature itself. 2.7.0 confirms the maintainer is tracking WordPress 6.9 and PHP 8.4/8.5 ahead of our own upgrade windows, which is precisely the maintenance burden we are buying out of.
• WordPress upgrade readiness. The 6.9 $priority support and the alignment of mock defaults with WP Core (doing_action, doing_filter, do_action_deprecated, apply_filters_deprecated, has_filter, has_action) mean fewer mock-vs-core divergences as we track WP releases. Mocks that drift from core behavior are silent false passes; each release that closes a gap is a direct reduction in that risk.
• Architecture direction. Requiring code to be testable under Brain Monkey pushes the team toward separating pure PHP domain logic from WordPress API calls (thin hook adapters, injected services). That is a design decision with long-term maintenance and hiring implications, and it should be made deliberately.
• Release cadence and CI budget. Unit tests in seconds vs. integration suites in minutes changes how often you can merge and release. Track suite runtime, WP-facing coverage, defect escape rate, and time-to-merge as the success metrics for adoption.
• Test portfolio allocation. The PM decision is not "Brain Monkey vs. nothing" but "how much unit vs. integration vs. E2E." Reasonable target: Brain Monkey covers hook registration (including priority/arg-count), argument shape, option/transient handling, error paths (WP_Error), and remote-call failure branches; a small integration suite covers real DB, REST, and rendering behavior.
• Dependency governance. 345 stars, a single small maintainer base, and no listed dependents mean you are adopting a niche-but-standard dev dependency. Decide up front: pin the version, wrap it in a shared base test case, and accept that MIT licensing gives you a fork option if maintenance stalls. 2.7.0 is a good signal — active, forward-compatible, and cleaning up its own distribution (dev-only files now excluded from the Composer package, which trims vendor noise and audit surface in CI).

When to Consider This Package

Adopt when:

• You ship a WordPress plugin or theme and want unit tests that run without a WordPress install, database, or web server.
• Your critical logic is hook- and API-shaped: verifying add_action was registered with the right hook, callback, priority, and arg count; that wp_enqueue_script got the right handle and version; that a filter returns the expected shape — and, as of 2.7.0, that has_filter() / has_action() return correctly for a given $priority.
• You are targeting or already on WordPress 6.9+ and need the mock layer to keep pace with core signature changes rather than lagging behind them.
• You need to test failure branches — HTTP errors, WP_Error returns, missing options — which are painful to trigger against a real WordPress instance.
• You already use PHPUnit + Mockery; Brain Monkey composes with both rather than replacing them.
• CI time or infrastructure cost is a constraint and you want the bulk of assertions to run in seconds.
• You are willing to accept function-level monkey patching and its constraints (runtime function redefinition via a stream wrapper; it does not mock classes or objects — that is Mockery's job).

Look elsewhere, or supplement, when:

• You need to verify real behavior: actual database queries, REST endpoint responses, capability checks against real roles, template rendering, or upgrade/migration routines. Use the WordPress core PHPUnit test library (wp-phpunit) or WP-CLI-based acceptance tests instead.
• You need browser or end-to-end coverage — Playwright, Cypress, or Codeception; this package is not in that category.
• Your runtime or CI image has opcache/JIT or extension configurations that conflict with function redefinition. Validate on your actual PHP matrix before committing; note that 2.7.0 confirms PHP 8.4 and 8.5, so the compatibility question is now mostly about opcache settings rather than language version. A failed spike here is a cheap way to avoid a wasted quarter.
• You only need class mocking — plain Mockery is sufficient, with less conceptual overhead.
• You have pinned Mockery tightly for other reasons. 2.7.0 tightens the Mockery version constraints; check the resolved version against the rest of your dev dependency graph during the upgrade rather than after.
• Your organization cannot tolerate a small-maintainer dev dependency. Mitigate with a pinned version and a thin internal wrapper, or budget for a fork; do not adopt it as an unmanaged transitive dependency.
• The team has no bandwidth to own test infrastructure. A mocking library without a testing culture produces brittle tests that assert implementation details (e.g., "add_action was called exactly once") and create false confidence. Fund the practice, not just the package.

How to Pitch It (Stakeholders)

For executives: Brain Monkey is a free, MIT-licensed, development-only testing utility for our WordPress plugin. It has zero production footprint — it is not shipped, adds no weight to the plugin, and introduces no runtime or security surface for customers. It lets engineers verify plugin behavior in seconds without standing up a WordPress site, which means faster releases, fewer regressions reaching customers, and cheaper CI. The just-released 2.7.0 is a routine, non-breaking maintenance update: it adds support for a new WordPress 6.9 capability, confirms compatibility with PHP 8.4 and 8.5, and ships a leaner package. That is exactly the upkeep we would otherwise fund internally. It remains a small, reversible, low-cost bet that de-risks the larger roadmap items we already committed to — PHP upgrades, platform compatibility, and refactoring hook-heavy code. Ask: approve as a dev dependency with a pinned version and a defined owner; approve the 2.7.0 bump as a routine low-risk upgrade.

For engineering: It is the de facto standard for unit-testing WordPress plugins. It layers on PHPUnit and Mockery and gives you Functions\when() / expect(), plus helpers for actions, filters, and shortcodes, so you can assert that a hook was registered correctly or that an HTTP failure path returns the right WP_Error. What changed in 2.7.0 and what to do about it: has_filter() / has_action() mocks now accept $priority (WP 6.9) — add priority assertions where ordering matters; several mock defaults were aligned with WP Core, so re-run the suite on the bump and treat any failures as tests that were encoding the old mock's behavior rather than real behavior; Mockery constraints are tighter, so verify the resolved version; and dev-only files are no longer in the distributed package. Constraints to plan around: it redefines functions at runtime via a stream wrapper, so validate against our PHP and opcache matrix first (PHP 8.4/8.5 are now confirmed upstream); it does not mock classes, so Mockery still does that work; and it says nothing about real WordPress behavior, so we keep a small integration suite for DB, REST, and rendering. Mitigations: pin the version, wrap setup/teardown in a shared base test case so a future swap is a one-file change, and enforce assertion style in review so tests describe intent rather than implementation. Success looks like: WP-facing unit coverage up, suite runtime under a minute, defect escape rate down, and no increase in integration-test flakiness.