Laravel Failurelab Laravel Package

Getting Started

• Upgrade to v1.2.0 as an additive minor release on top of v1.1.0. The public Scenario/Replay APIs remain backward compatible, so no immediate code changes are expected; still run your existing suite after updating.
• Look first at the new developer quick start and recovery recipes in the package docs, then at the synthetic unknown-response/reconciliation scenario and its negative controls. These are the best day-to-day references.
• First practical use case: add a Laravel job/consumer integration test that must be idempotent. Configure a fault plan where the handler succeeds, the acknowledgement is deterministically lost, the message is redelivered, and assert your side effect is applied exactly once and the recovery is acknowledged.
• Second use case: simulate an unknown response (handler outcome uncertain to the caller) and drive the reconciliation path, using the test-only idempotent fake capture provider to record what the handler attempted without touching any real provider.
• Run the package's SQLite test path locally, then mirror the same scenarios against MySQL/PostgreSQL in CI where your production database differs.

Implementation Patterns

• Test idempotency after success, not just failure. The critical scenario remains "handler completed, ack lost, redelivery happens." Use it to verify unique constraints, upserts, processed-message markers, or transactional outbox patterns.
• Use the test-only fake capture provider. It records calls idempotently and is explicitly test-only — wire it in place of your real capture/side-effect client so you can assert "captured once" across redeliveries without external dependencies.
• Exercise the unknown-response/reconciliation scenario. When the caller cannot know whether the handler took effect, assert your reconciliation logic queries state, detects the prior success, and does not duplicate side effects.
• Keep the negative controls in your suite. They prove your assertions actually fail when idempotency or reconciliation is broken; treat them as guardrails against false-green tests, not as optional extras.
• Keep fault plans close to the handler test. Define the simulated loss or unknown response around the specific job/consumer path so the scenario stays readable and deterministic.
• Model the full recovery path. Cover: initial delivery, handler execution, simulated ack loss or unknown response, redelivery/reconciliation, idempotent handling, and final acknowledgement.
• Use the disposable Laravel database-queue harness for process-level recovery. The new SIGKILL/recovery CI runs against a real disposable database queue on Laravel 12/13 — mirror that pattern if you need to test worker crash recovery rather than just simulated ack loss.
• Use the DB matrix deliberately. SQLite is fine for fast local feedback, but run the same idempotency and reconciliation assertions on MySQL/PostgreSQL in CI if production uses them. Do not assume SQLite uniqueness, locking, or transaction behavior matches production.
• Keep production code idempotent independently of the package. The package helps simulate failure modes in tests; it does not replace production safeguards such as database uniqueness constraints or idempotency keys.
• Integrate with Laravel feature/integration tests. Use your normal database refresh/migration setup for the test connection, then exercise the package's scenario/replay harness around the handler. Avoid Laravel queue fakes if they bypass the acknowledgement semantics you are trying to test.

Gotchas and Tips

• Respect the explicit safety boundaries: the package never touches a real provider, network, or production worker, and it does not provide an exactly-once guarantee. Do not present it as proving exactly-once delivery.
• The fake capture provider is test-only. Do not wire it into any production or shared environment code path; keep it behind your test configuration.
• The simulated loss happens after a successful handler. If your handler throws or rolls back, you are testing a different failure mode.
• The unknown-response scenario is synthetic. Make sure the reconciliation logic you assert against is the same one your production code path uses.
• Assertion guards and negative controls may fail tests that previously passed with unreachable fault plans or incomplete recovery sequences. Fix the scenario, not the guard.
• The SIGKILL/recovery CI requires a disposable database queue; it is not the same as the in-process ack-loss simulation and has different runtime cost. Keep it in CI rather than the fast local loop.
• Idempotency tests can pass on SQLite while missing MySQL/PostgreSQL-specific behavior. Run the database matrix in CI for confidence.
• Laravel 12/13 is the CI-verified matrix for the recovery harness; check your app version before copying those recipes verbatim.
• Use the package's scenario, replay, and assertion extension points rather than forking test helpers. Add focused plans around the specific handler and keep them deterministic.