Weave Code
Starter kit to start BDD testing in PHP with Peridot
Frequently asked questions about Peridot Jumpstart
- What is peridot-php/peridot-jumpstart and can I use it in a Laravel project?
- Peridot Jumpstart is a Composer starter kit that scaffolds a BDD-style test suite powered by the Peridot testing framework, using describe/it blocks instead of PHPUnit test classes. It is framework-agnostic rather than a Laravel package, but you can install it as a dev dependency in a Laravel application and run specs alongside your PHPUnit or Pest tests. It is best suited to behavior-focused unit specs rather than HTTP feature tests that rely on Laravel's TestCase helpers.
- How do I install Peridot Jumpstart with Composer?
- For a standalone spec suite, run composer create-project peridot-php/peridot-jumpstart, which pulls in Peridot and generates a specs directory plus a peridot.php bootstrap file. To add it to an existing project, require it as a dev dependency with composer require --dev peridot-php/peridot-jumpstart and run the binary at vendor/bin/peridot. Commit the generated specs and peridot.php, and keep vendor out of version control as usual.
- Does Peridot Jumpstart work with Laravel 10 or 11?
- There is no Laravel version constraint because the kit is not a Laravel package; it only depends on Peridot and its plugins. Compatibility with Laravel 10 or 11 therefore depends almost entirely on whether Peridot itself runs on your PHP version, which for those releases is 8.1 or newer. Check Packagist for the current PHP constraint before adopting it, since the project has not seen active Laravel-oriented maintenance.
- How is Peridot's describe/it syntax different from PHPUnit?
- Peridot specs are written with describe() and it() closures, so tests read as nested behavioral descriptions rather than classes extending TestCase. Assertions use expect() style matchers, for example expect($value)->to->equal(42), and setup work happens in beforeEach and afterEach hooks instead of setUp and tearDown methods. This is more expressive for behavior-driven work, but existing PHPUnit assertions and Laravel test helpers do not carry over directly.
- How do I run the specs and filter which ones execute?
- Run vendor/bin/peridot from the project root, optionally passing a path such as vendor/bin/peridot specs to scope execution. Peridot's CLI supports grep-style filtering with --grep plus focus and fail-fast options, and you can point it at a custom configuration file. For CI, add that same command to your pipeline after composer install.
- Can I bootstrap a Laravel application inside a Peridot spec?
- Yes, in principle: Peridot's peridot.php bootstrap file or a beforeEach hook can require bootstrap/app.php, resolve the application container, and bind fakes manually. What you cannot do is reuse Laravel's TestCase traits and assertion helpers as-is, because they are built around PHPUnit's lifecycle. Expect to write a small bootstrap helper that creates the app, sets the environment to testing, and tears it down between specs.
- Does Peridot Jumpstart support mocking and test doubles?
- Peridot has companion packages and plugins for this, most notably peridot-php/leo, which provides a Jasmine-style mock and spy API wired into Peridot's expectation system. The jumpstart kit only gives you the scaffold; you add the mocking plugin you need via Composer and enable it in peridot.php. For Laravel facades and container bindings you will usually stub through the container rather than relying on Laravel's built-in mock helpers.
- Is peridot-php/peridot-jumpstart still maintained and safe to depend on?
- The kit is a small starter repository with infrequent releases, and the Peridot ecosystem is far smaller than PHPUnit, Pest, or Behat. Because it is a dev-only dependency it never ships to production, so the risk is limited to your test tooling. Before standardizing on it, check the latest commit and issue activity and confirm it installs cleanly on your PHP version.
- What are good alternatives to Peridot for BDD testing in Laravel?
- Pest is the closest match for describe/it style specs and is built directly on PHPUnit, so Laravel's testing helpers and HTTP assertions work out of the box. PHPSpec offers spec-style unit testing, while Behat and Codeception provide full BDD and Gherkin workflows, and plain PHPUnit remains the safest default. Peridot is a reasonable choice only if you specifically like its API and are comfortable with a smaller community.
- Do I need to change composer.json scripts or autoloading for Peridot Jumpstart?
- You will typically add an autoload-dev PSR-4 entry for your spec namespace and a Composer script that aliases vendor/bin/peridot specs for convenience. Peridot also needs a peridot.php configuration file at the project root, or a path passed on the command line. Keep the kit's files in autoload-dev so nothing leaks into production autoloading.
Weaver
How can I help you explore Laravel packages today?