Testing Kit Laravel Package

Getting Started

1.3.0 is an additive minor release on top of 1.2.0. No breaking changes are advertised, so pin ^1.3 and run your test suite after composer update <vendor>/<package>.

The headline feature is a single method: MocksTranslator::useRealTranslator(). It flips a test from the package's mocked translator back to Laravel's real translator and resets the validator so validation messages are resolved through the real translator too.

Where to look first:

1. The MocksTranslator class itself (or the test case/trait that exposes it). Confirm whether the method is static, instance-level, and whether it is auto-reset between tests — the release note is one line.
2. The package README's "running tests" section, which was expanded in this release. It is the quickest way to see the intended setup/teardown shape.
3. Your own test suite's base TestCase, since that is where the mock translator is most likely installed.

First practical use case: a feature test class uses the mocked translator for speed and determinism across most cases, but one test needs the actual strings from lang/en/*.php — for example asserting a real validation message, a pluralised string, or a locale fallback. Call useRealTranslator() in that test before building the validator/request, then assert against the genuine translated output.

Implementation Patterns

Default mock, opt in to real translations per test Keep the mock as the baseline for isolation and speed, and switch to the real translator only where the assertion depends on actual lang files.

public function test_registration_rejects_duplicate_email(): void
{
    MocksTranslator::useRealTranslator();

    $this->post('/register', ['email' => '[email protected]'])
        ->assertSessionHasErrors(['email' => __('validation.unique', ['attribute' => 'email'])]);
}

Switch before the validator is built Because the method "resets the validator", the useful ordering is: switch translator → make the request → assert. If you switch after a validator has already been resolved and used, you are asserting against messages produced by the mocked translator.

MocksTranslator::useRealTranslator();

$response = $this->post('/register', $payload);

$response->assertSessionHasErrors('email');

Class-level separation Prefer splitting translator-sensitive tests into their own class or setUp() branch rather than toggling mid-test repeatedly. A class that calls useRealTranslator() in setUp() reads more clearly than one that flips per method, and it sidesteps ordering questions about whether the mock is reinstalled between tests.

protected function setUp(): void
{
    parent::setUp();
    MocksTranslator::useRealTranslator();
}

Pest / dataset usage If you use Pest, call the method in beforeEach() for the file that needs real strings rather than inside each test, and verify the mock is reinstalled for the next file.

Integration with locale and fallback assertions Real translator is the right tool when testing __(), trans_choice(), or @lang output end to end. Set the locale explicitly in the test (app()->setLocale('fr')) so the assertions do not depend on ambient config.

CI alignment The package's own suite no longer boots PostgreSQL or MariaDB. If your pipeline copied the package's service definitions, you can drop those services for this package's test job — a real if unglamorous speedup. Keep DB services for your app's own suite.

Lean installs .gitattributes now keeps dev files (tests, AGENTS.md, CLAUDE.md, CI config) out of dist archives. That means a composer required copy is smaller, but you also cannot read those files from vendor/ in production debugging — consult the repository, not the installed package.

Gotchas and Tips

• Re-verify the 1.2.0 entry point. Earlier notes assumed 1.2.0's feature was an Inertia snapshot-replace helper. The 1.3.0 notes make clear the package's domain is translator mocking in tests. Treat any prior assumptions about the 1.2.0 API as unconfirmed and check the source before adopting it.
• Validator reset is the subtle part. The reset presumably rebinds or clears the validator's translator. Any validator instance you constructed before calling useRealTranslator() may still hold the mock. Rebuild the validator (or re-resolve it from the container) after switching.
• Check whether the switch is one-way. The method is named "use real translator"; there is no advertised counterpart to restore the mock. Verify whether the package reinstalls the mock in setUp()/tearDown() automatically. If not, a test that switches may leak state into later tests in the same process — restore explicitly or isolate the class.
• Real translator needs real lang files. With the mock out of the way, missing keys return the key string itself (validation.custom_rule), which produces confusing assertion failures. Confirm the relevant lang/ files are present and that published vendor lang files are loaded.
• Locale and fallback. Real translations respect config('app.locale') and fallback_locale; the mock may not. Pin the locale in the test so the assertion is not environment-dependent.
• Pluralisation and trans_choice. These are exactly the paths a mock tends to flatten. If you are writing these assertions, real translator is worth the cost — but assert the concrete string, not just "not the key".
• Debug which translator is bound. dump(get_class(app('translator'))); before and after the call settles most "why is my message still mocked" questions.
• Don't read dev files from vendor/. AGENTS.md, CLAUDE.md, test fixtures, and CI config are now excluded from dist archives. Use the repository for guidance.
• Extension points. If the package exposes a config file or container binding for the mock's behaviour, prefer configuring it over patching vendor code; re-run vendor:publish only if 1.3.0 documents new keys (none are mentioned).
• Version pinning. Still a young 1.x line. Pin ^1.3, and if you subclass or wrap MocksTranslator, re-check signatures on each minor.