PHPackages devkind/laravel-cypress - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. devkind/laravel-cypress ActiveLibrary[Utility & Helpers](/categories/utility) devkind/laravel-cypress ======================= Laravel Cypress Boilerplate 1.2.5(2y ago)0504MITPHPPHP ^8.0 Since Feb 16Pushed 2y agoCompare [ Source](https://github.com/rome2o/laravel-cypress)[ Packagist](https://packagist.org/packages/devkind/laravel-cypress)[ Docs](https://github.com/laracasts/cypress)[ RSS](/packages/devkind-laravel-cypress/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependencies (4)Versions (9)Used By (0) Laravel + Cypress Integration ============================= [](#laravel--cypress-integration) This package provides the necessary boilerplate to quickly begin testing your Laravel applications using Cypress. [![](https://user-images.githubusercontent.com/183223/89684657-e2e5ef00-d8c8-11ea-825c-ed5b5acc37a4.png)](https://user-images.githubusercontent.com/183223/89684657-e2e5ef00-d8c8-11ea-825c-ed5b5acc37a4.png) Video Tour ---------- [](#video-tour) If you'd prefer a more visual review of this package, [please watch this video](https://laracasts.com/series/jeffreys-larabits/episodes/22) on Laracasts. Table of Contents ----------------- [](#table-of-contents) - [Installation](#installation) - [Environment Handling](#environment-handling) - [API](#api) - [Routing](#routing) Installation ------------ [](#installation) If you haven't already installed [Cypress](https://www.cypress.io/); that's your first step. ``` npm install cypress --save-dev ``` Now you're ready to install this package through Composer. Pull it in as a development-only dependency. ``` composer require laracasts/cypress --dev ``` Finally, run the `cypress:boilerplate` command to copy over the initial boilerplate files for your Cypress tests. ``` php artisan cypress:boilerplate ``` That's it! You're ready to go. We've provided an `example.cy.js` spec for you to play around with it. Let's run it now: ``` npx cypress open ``` In the Cypress window that opens, Choose "E2E Testing," and then "Start E2E Testing in Chrome." This will bring up a list of all specs in your application. Of course, at this point, we only have the single example spec. Click `example.cy.js` to run it. Wew! All green. Cypress Configuration --------------------- [](#cypress-configuration) We've declared some initial settings in your project's `cypress.config.js` file. Have a quick look now to ensure that everything is in order. In particular, please ensure that the `baseUrl` property is set correctly (we default to your app's `APP_URL` environment setting). Environment Handling -------------------- [](#environment-handling) After running the `php artisan cypress:boilerplate` command, you'll now have a `.env.cypress`file in your project root. To get you started, this file is a duplicate of `.env`. Feel free to update it as needed to prepare your application for your Cypress tests. Likely, you'll want to use a special database to ensure that your Cypress acceptance tests are isolated from your development database. ``` DB_CONNECTION=mysql DB_DATABASE=cypress ``` When running your Cypress tests, this package, by default, will automatically back up your primary `.env` file, and swap it out with `env.cypress`. Once complete, of course the environment files will be reset to how they originally were. > All Cypress tests run according to the environment specified in `.env.cypress`. However, when your Cypress tests fail, it can often be useful to manually **browse your application in the exact state that triggered the test failure**. You can't do this if your environment is automatically reverted after each test run. To solve this, you have two choices: #### Option 1: [](#option-1) Temporarily disable the Cypress task that resets the environment. Visit `cypress/support/index.js` and comment out this portion. ``` after(() => { // cy.task("activateLocalEnvFile", {}, { log: false }); }); ``` That should do it! Just remember to manually revert to your local .env file when you're done performing your Cypress tests. #### Option 2: [](#option-2) When booting a server with `php artisan serve`, you can optionally pass an `--env` flag to specify your desired environment for the application. ``` php artisan serve --env="cypress" ``` ^ This command instructs Laravel to boot up a server and use the configuration that is declared in `.env.cypress`. Now visit `cypress.json` and change the `baseUrl` to point to your local server. ``` { "baseUrl": "http://127.0.0.1:8000" } ``` And you're all set! I'd recommend creating an npm script to simplify this process. Open `package.json`, and add: ``` { "scripts": { "test:cypress": "php artisan serve --env=cypress & cypress open" } } ``` Now from the command line, you can run `npm run test:cypress` to start a local server and open Cypress. If you choose this second option, visit `cypress/support/index.js` and delete the `activateCypressEnvFile` and `activateLocalEnvFile` tasks, [as shown here](https://github.com/laracasts/cypress/blob/master/src/stubs/support/index.js#L23). They're no longer required, as you'll be handling the environment handling yourself. API --- [](#api) This package will add a variety of commands to your Cypress workflow to make for a more familiar Laravel testing environment. We allow for this by exposing a handful of Cypress-specific endpoints in your application. Don't worry: these endpoints will **never** be accessible in production. ### cy.login() [](#cylogin) Find an existing user matching the optional attributes provided and set it as the authenticated user for the test. If not found, it'll create a new user and log it in. ``` test('authenticated users can see the dashboard', () => { cy.login({ username: 'JohnDoe' }); cy.visit('/dashboard').contains('Welcome Back, JohnDoe!'); }); ``` Should you need to also eager load relationships on the user model or specifiy a certain model factory state before it's returned from the server, instead pass an object to `cy.login()`, like so: ``` test('authenticated users can see the dashboard', () => { cy.login({ attributes: { username: 'JohnDoe' }, state: ['guest'], load: ['profile'] }); cy.visit('/dashboard').contains('Welcome Back, JohnDoe!'); }); ``` If written in PHP, this object would effectively translate to: ``` $user = User::factory()->guest()->create([ 'username' => 'JohnDoe' ])->load('profile'); auth()->login($user); ``` ### cy.currentUser() [](#cycurrentuser) Fetch the currently authenticated user from the server, if any. Equivalent to Laravel's `auth()->user()`. ``` test('assert the current user has email', () => { cy.login({ email: 'joe@example.com' }); cy.currentUser().its('email').should('eq', 'joe@example.com'); // or... cy.currentUser().then(user => { expect(user.email).to.eql('joe@example.com'); }); }); ``` ### cy.logout() [](#cylogout) Log out the currently authenticated user. Equivalent to Laravel's `auth()->logout()`. ``` test('once a user logs out they cannot see the dashboard', () => { cy.login({ username: 'JohnDoe' }); cy.logout(); cy.visit('/dashboard').assertRedirect('/login'); }); ``` ### cy.create() [](#cycreate) Use Laravel factories to create and persist a new Eloquent record. ``` test('it shows blog posts', () => { cy.create('App\\Post', { title: 'My First Post' }); cy.visit('/posts').contains('My First Post'); }); ``` Note that the `cy.create()` call above is equivalent to: ``` App\Post::factory()->create(['title' => 'My First Post']); ``` You may optionally specify the number of records you require as the second argument. This will then return a collection of posts. ``` test('it shows blog posts', () => { cy.create('App\\Post', 3, { title: 'My First Post' }); }); ``` Lastly, you can alternatively pass an object to `cy.create()`. This should be the preferred choice, if you need to eager load relationships or create the model record in a given model factory state. ``` test('it shows blog posts', () => { cy.create({ model: 'App\\Post', attributes: { title: 'My First Post' }, state: ['archived'], load: ['author'], count: 10 }) }); ``` If written in PHP, this object would effectively translate to: ``` $user = \App\Post::factory(10)->archived()->create([ 'title' => 'My First Post' ])->load('author'); auth()->login($user); ``` ### cy.refreshRoutes() [](#cyrefreshroutes) Before your Cypress test suite run, this package will automatically fetch a collection of all named routes for your Laravel app and store them in memory. You shouldn't need to manually call this method, however, it's available to you if your routing will change as side effect of a particular test. ``` test('it refreshes the list of Laravel named routes in memory', () => { cy.refreshRoutes(); }); ``` ### cy.refreshDatabase() [](#cyrefreshdatabase) Trigger a `migrate:refresh` on your test database. Often, you'll apply this in a `beforeEach` call to ensure that, before each new test, your database is freshly migrated and cleaned up. ``` beforeEach(() => { cy.refreshDatabase(); }); test('it does something', () => { // php artisan migrate:fresh has been // called at this point. }); ``` ### cy.seed() [](#cyseed) Run all database seeders, or a single class, in the current Cypress environment. ``` test('it seeds the db', () => { cy.seed('PlansTableSeeder'); }); ``` Assuming that `APP_ENV` in your `.env.cypress` file is set to "acceptance," the call above would be equivalent to: ``` php artisan db:seed --class=PlansTableSeeder --env=acceptance ``` ### cy.artisan() [](#cyartisan) Trigger any Artisan command under the current environment for the Cypress test. Remember to precede options with two dashes, as usual. ``` test('it can create posts through the command line', () => { cy.artisan('post:make', { '--title': 'My First Post', }); cy.visit('/posts').contains('My First Post'); }); ``` This call is equivalent to: ``` php artisan post:make --title="My First Post" ``` ### cy.php() [](#cyphp) While not exactly in the spirit of acceptance testing, this command will allow you to trigger and evaluate arbitrary PHP. ``` test('it can evaluate PHP', () => { cy.php(` App\\Plan::first(); `).then(plan => { expect(plan.name).to.equal('Monthly'); }); }); ``` Be thoughtful when you reach for this command, but it might prove useful in instances where it's vital that you verify the state of the application or database in response to a certain action. It could also be used for setting up the "world" for your test. That said, a targeted database seeder - using `cy.seed()` - will typically be the better approach. Routing ------- [](#routing) Each time your test suite runs, this package will fetch all named routes for your Laravel application, and store them in memory. You'll additionally find a `./cypress/support/routes.json` file that contains a dump of this JSON. This package overrides the base `cy.visit()` method to allow for optionally passing a `route` name instead of a URL. ``` test('it loads the about page using a named route', () => { cy.visit({ route: 'about' }); }); ``` If the named route requires a wildcard, you may include it using the `parameters` property. ``` test('it loads the team dashboard page using a named route', () => { cy.visit({ route: 'team.dashboard', parameters: { team: 1 } }); }); ``` Should you need to access the full list of routes for your application, use the `Cypress.Laravel.routes` property. ``` // Get an array of all routes for your app. Cypress.Laravel.routes; // ['home' => []] ``` Further, if you need to translate a named route to its associated URL, instead use the `Cypress.Laravel.route()` method, like so: ``` Cypress.Laravel.route('about'); // /about-page Cypress.Laravel.route('team.dashboard', { team: 1 }); // /teams/1/dashboard ``` ### Security [](#security) If you discover any security related issues, please email instead of using the issue tracker. Credits ------- [](#credits) - [Jeffrey Way](https://twitter.com/jeffrey_way) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 28 — LowBetter than 54% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity12 Limited adoption so far Community16 Small or concentrated contributor base Maturity56 Maturing project, gaining track record Bus Factor1 Top contributor holds 82.6% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~22 days Recently: every ~0 days Total 8 Last Release 1029d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/7828ff29033f88e33044a6606e46c6f729ad1729914a4efd4c3b2086ef91094c?d=identicon)[devkind](/maintainers/devkind) --- Top Contributors [![JeffreyWay](https://avatars.githubusercontent.com/u/183223?v=4)](https://github.com/JeffreyWay "JeffreyWay (123 commits)")[![rome2o](https://avatars.githubusercontent.com/u/68844541?v=4)](https://github.com/rome2o "rome2o (7 commits)")[![bastihilger](https://avatars.githubusercontent.com/u/1419634?v=4)](https://github.com/bastihilger "bastihilger (6 commits)")[![bencarter78](https://avatars.githubusercontent.com/u/848019?v=4)](https://github.com/bencarter78 "bencarter78 (3 commits)")[![Jamesking56](https://avatars.githubusercontent.com/u/253237?v=4)](https://github.com/Jamesking56 "Jamesking56 (1 commits)")[![jenky](https://avatars.githubusercontent.com/u/1808758?v=4)](https://github.com/jenky "jenky (1 commits)")[![jeroenvanrensen](https://avatars.githubusercontent.com/u/46967616?v=4)](https://github.com/jeroenvanrensen "jeroenvanrensen (1 commits)")[![laravel-shift](https://avatars.githubusercontent.com/u/15991828?v=4)](https://github.com/laravel-shift "laravel-shift (1 commits)")[![mpociot](https://avatars.githubusercontent.com/u/804684?v=4)](https://github.com/mpociot "mpociot (1 commits)")[![sam-ngu](https://avatars.githubusercontent.com/u/30950704?v=4)](https://github.com/sam-ngu "sam-ngu (1 commits)")[![tnorthcutt](https://avatars.githubusercontent.com/u/796639?v=4)](https://github.com/tnorthcutt "tnorthcutt (1 commits)")[![carlobeltrame](https://avatars.githubusercontent.com/u/7566995?v=4)](https://github.com/carlobeltrame "carlobeltrame (1 commits)")[![dillingham](https://avatars.githubusercontent.com/u/29180903?v=4)](https://github.com/dillingham "dillingham (1 commits)")[![Jakski](https://avatars.githubusercontent.com/u/8525083?v=4)](https://github.com/Jakski "Jakski (1 commits)") --- Tags laracastscypress ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/devkind-laravel-cypress/health.svg) ``` [![Health](https://phpackages.com/badges/devkind-laravel-cypress/health.svg)](https://phpackages.com/packages/devkind-laravel-cypress) ``` ### Alternatives [barryvdh/laravel-ide-helper Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion. 14.9k123.0M687](/packages/barryvdh-laravel-ide-helper)[laracasts/cypress Laravel Cypress Boilerplate 6273.2M4](/packages/laracasts-cypress)[illuminate/pipeline The Illuminate Pipeline package. 9446.6M213](/packages/illuminate-pipeline)[illuminate/pagination The Illuminate Pagination package. 10532.5M862](/packages/illuminate-pagination)[spatie/laravel-pjax A pjax middleware for Laravel 5 513371.8k11](/packages/spatie-laravel-pjax)[spatie/laravel-mix-preload Add preload and prefetch links based your Mix manifest 169176.0k2](/packages/spatie-laravel-mix-preload) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)