Behat And Selenium In Vagrant

Even with testing frameworks like PHPUnit or PHPSpec, I've still felt like something was missing. Unit tests made me sleep a little better at night, knowing my objects were interacting the way they should be...but my tests still didn't give me the dreams I had hoped for. I felt that even though I could unit test the balls off my application, I didn't have anything in place to actually test what users would experience. Does the app actually function in the browser? Do all the forms work as expected? Do all the redirects work and go to the right places? Will the user see certain validation messages in different scenarios? Enter Behat.

Behat is a testing framework that allows you to test what your end users will experience. It's the perfect compliment to PHPUnit and/or PHPSpec. I'll be honest, Behat made me nervous. There are quite a few different components that go into this testing framework: Gherkin, Mink, Goutte, Selenium2, and getting it to work with a framework. It's pretty daunting, but so worth it. If you don't know anything about Behat I suggest watching Knp University's video. It's a great overview of what Behat can do for you.

If you're a Laracast member, Jeffrey Way also has a good video on Behat. He doesn't go into testing with Selenium though.

This is not a Behat tutorial

This post isn't to sell you on the idea of Behat or even a tutorial about how to use it. There are several other tutorials and videos about that. This post is about getting it up and running with Symfony in a Vagrant box. Even though I'm using Symfony, I'm fairly certain the steps can be modified slightly to accommodate any framework.

Prerequisites

I'm using a super simple Vagrant box that I've manually installed apache, php, composer, postgres, and Symfony on. Here's my Vagrantfile. I've also added a line to my mac's /etc/hosts file to point my project's url to my Vagrant box's ip.

Check out Vaprobash and/or PuPHPet for some VM provisioning if you're not use to setting up a VM. Both are awesome resources.

Install via composer

First thing we need to do is to pull in the framework and some extensions via composer.

{
    "require": {
        "other-dependencies": "*",
        "behat/symfony2-extension": "*",
        "behat/mink-goutte-driver": "*",
        "behat/mink-selenium2-driver": "1.2.*@dev",
        "behat/mink-extension": "*",
        "behat/mink-browserkit-driver": "*"
    }
}


Install the dependencies, composer update.

Create a "test" entry point

Next, we need to create an entry point to ensure all our requests into the application are in a "test" environment. Let's create the entry point.

<?php // MySymfonyProject/Web/app_test.php

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Debug\Debug;

$loader = require_once __DIR__.'/../app/bootstrap.php.cache';
Debug::enable();

require_once __DIR__.'/../app/AppKernel.php';

$kernel = new AppKernel('test', true);
$kernel->loadClassCache();
$request = Request::createFromGlobals();
$response = $kernel->handle($request);
$response->send();
$kernel->terminate($request, $response);


Now we can visit our app in the browser in the "test" environment by going to something like, http://myproject.dev/app_test.php/some_route. You should also create a test database to use with this new environment and configure Symfony to use it during testing.

Create the behat.yml file

It's time to create Behat's config file. Create the following file in the root of your app.

# MySymfonyProject/behat.yml
default:
    extensions:
        Behat\MinkExtension\Extension:
            default_session: symfony2
            goutte: ~
            base_url: 'http://myproject.dev/app_test.php'

        Behat\Symfony2Extension\Extension:
            mink_driver: true
            kernel:
                env: test


We've configured Behat to use the Goutte driver. Goutte is a web scraper library created by the creator of Symfony. It allows you to visit urls, click links, fill in forms, and more, all with php.

Init a bundle

Assuming you already have a bundle you're ready to test, you can initialize it for Behat testing with the following command, bin/behat --init @YourBundleName. This will create a Features directory in your bundle as well as a Features/Context/FeatureContext.php file which holds the context class. You'll want to change the FeatureContext class to extend Behat\MinkExtension\Context\MinkContext.

Now, you can start putting your .feature files in this directory. You can test the features in the bundle with the following command, bin/behat @YourBundleName.

What about javascript?

Everything we've done so far works great for pages that don't require javascript. Goutte is great for this but it has no means to test pages with javascript. To test pages with javascript you actually need a browser and something to use the browser to do your testing. This is where Selenium comes into play. In conjunction with Behat, Selenium can actually pop open a browser and commandeer it for performing your tests. It's pretty remarkable. That assumes that you've got everything installed on your host machine though because that's where your browser lives. We're using Vagrant though and Vagrant doesn't really have any sort of display for a browser. Obviously we can't use Selenium inside a Vagrant box...right? WRONG!

It's about to get exciting.

Set up the VM to run Selenium

Before we do any of this, let's update the list of available packages, sudo apt-get update.

Let's create a directory especially for Selenium, mkdir /var/selenium. cd into that directory and download Selenium with, wget http://selenium-release.storage.googleapis.com/2.40/selenium-server-standalone-2.40.0.jar.

We've got Selenium now, awesome! Except it's a .jar and we don't have java installed, not awesome. Oh well, let's get some java! sudo apt-get install openjdk-7-jre-headless.

We need a browser now and believe it or not, we can install Firefox in our VM. Do so with, sudo apt-get install firefox.

Because we're testing browser interaction and browsers require a display, we need some way to accommodate that in our VM. We can use Xvfb for this. Xvfb is a display server that performs graphical operations in memory, all without actually displaying anything. Perfect for our VM. Install it with, sudo apt-get install xvfb.

Phew...we're done installing stuff. Woo hoo!

Reconfigure

Now that we have all that pieces in place, we need to reconfigure Behat to take advantage of our new goodies. Update your behat.yml file like below:

# MySymfonyProject/behat.yml
default:
    extensions:
        Behat\MinkExtension\Extension:
            default_session: symfony2
            goutte: ~
            base_url: 'http://myproject.dev/app_test.php'
            javascript_session: selenium2
            browser_name: firefox
            selenium2: ~

        Behat\Symfony2Extension\Extension:
            mink_driver: true
            kernel:
                env: test


Create a test feature

To actually see if this works, create a route to a controller action that uses this template. All the page does is displays a button and uses jQuery to attach a click handler that when clicked, populates a div with "It works!".

Let's create a feature to test this.

# MySymfonyProject/src/YourProject/YourBundle/Features/selenium_test.feature
Feature: Selenium works
  In order to see if selenium works
  As a visitor
  I need to be able to use javascript

  @javascript
  Scenario: Testing selenium
    Given I am on "/your/route"
    And I press "Button"
    Then I should see "It works!"


Note the @javascript annotation. This, along with our new behat configuration, tells behat to use Selenium for this scenario. All scenarios without this annotation will continue to use Goutte.

Run it!

Before we run Behat, we need to start up Selenium. You can do that with DISPLAY=:1 xvfb-run java -jar /var/selenium/selenium-server-standalone-2.40.0.jar. I suggest creating an alias for this in a .bash_aliases file. You should eventually see something like below.

Mar 18, 2014 3:52:04 AM org.openqa.grid.selenium.GridLauncher main
INFO: Launching a standalone server
03:52:04.213 INFO - Java: Oracle Corporation 24.45-b08
03:52:04.214 INFO - OS: Linux 3.2.0-23-generic amd64
03:52:04.231 INFO - v2.40.0, with Core v2.40.0. Built from revision fbe29a9
03:52:04.356 INFO - Default driver org.openqa.selenium.ie.InternetExplorerDriver registration is skipped: registration capabilities Capabilities [{platform=WINDOWS, ensureCleanSession=true, browserName=internet explorer, version=}] does not match with current platform: LINUX
03:52:04.419 INFO - RemoteWebDriver instances should connect to: http://127.0.0.1:4444/wd/hub
03:52:04.421 INFO - Version Jetty/5.1.x
03:52:04.422 INFO - Started HttpContext[/selenium-server/driver,/selenium-server/driver]
03:52:04.423 INFO - Started HttpContext[/selenium-server,/selenium-server]
03:52:04.424 INFO - Started HttpContext[/,/]
03:52:27.029 INFO - Started org.openqa.jetty.jetty.servlet.ServletHandler@67db296e
03:52:27.030 INFO - Started HttpContext[/wd,/wd]
03:52:27.038 INFO - Started SocketListener on 0.0.0.0:4444
03:52:27.044 INFO - Started org.openqa.jetty.jetty.Server@709dd800


This takes a few seconds, so wait until you see that last line before moving on.

Now that Selenium is running, open up a new console tab in iTerm or PHPStorm and ssh back into your vagrant box to the root of your Symfony project.

What are you waiting for!? Run Behat! bin/behat @YourBundleName

Using javascript in a Behat test


Your tests should pass. Pat yourself on the back!

This is a super simple example, purely for testing whether or not all the pieces are working together. However, I'm sure you can dream up some scenarios where you need to be able to dynamically add some fields to your forms and test the submission, validation, creation, updating, etc. That's now possible with this setup.

Start testing what your users are actually going to use on your development/testing VM that uses the same stack that your production code will be running on. Now you can sleep even better at night! Enjoy!

Tips

You can kill selenium with Control + C in its terminal tab on a mac.

I highly recommend you peruse Sylius's Behat context classes and features. I've found them immensely useful to learn how to test javascript and use Symfony's services behind the scenes.

Tags: PHP, Advanced, Symfony

What To Return From Repositories

Repositories are swell. It's a great idea to have a central place to retrieve entities(models) from. They're even better if you're interfacing them and have different implementations, like an EloquentPersonRepository. It's awesome to hide your ORM behind an interface. Your calling code likely doesn't need to know the ORM exists...but the repositories will still return <insert-your-ORM-here> models to the client code. Isn't the client code suppose to be unaware of the ORM? It doesn't make sense for your client code to do something like, $person->siblings()->attach($brother) when attach() is an Eloquent method. What do you do then? have your repositories cast everything to arrays? convert them to instances of stdClass?

Eloquent is a very nice, clean ORM. It's super easy to work with. I think for many developers it may be their very first ORM, which is great! I think that because more than once I have seen questions come up like the following:

"Regarding repositories, the biggest issue I have with them is that their output data also needs to be abstracted in some way. It defeats the purpose if DbOrderRepository::getAll() returns an array of Eloquent objects but FileOrderRepository::getAll() returns an array of stdclass instances or associative arrays. What's the best way of preventing this? It seems like we would need framework-agnostic 'OrderDetails' and 'OrderCollection' classes but that strikes me as being overkill, and potentially a little confusing." - Laracast member

Eloquent was my introduction into ORMs and I had the exact same question. Let me illustrate a scenario with some code. I'll use the above example.

Note: I've left out some classes and interfaces in the code samples for brevity.

Our Order model

class Order extends Eloquent
{
    protected $table = 'orders';

    public function user()
    {
        return $this->belongsTo('User');
    }
}

Our Order repository interface

interface OrderRepository
{
    public function findById($id);

    public function findByOrderNumber($orderNumber);
}

A repository implementation

class EloquentOrderRepository implements OrderRepository
{
    protected $orders;

    public function __construct(Order $orders)
    {
        $this->orders = $orders;
    }

    public function findById($id)
    {
        return $this->orders->find($id);
    }

    public function findByOrderNumber($orderNumber)
    {
        return $this->orders->whereOrderNumber($orderNumber)->first();
    }
}

That's lookin good. Let's create a controller that has an action to transfer an Order to a User.

Our Controller

class OrderController extends BaseController
{
    protected $users;
    protected $orders;
    protected $mailer;

    public function __construct
    (   
        UserRepository $users, 
        OrderRepository $orders,
        OrderMailer $mailer
    )
    {
        $this->users = $users;
        $this->orders = $orders;
        $this->mailer = $mailer;
    }

    public function transferOrder($userId, $orderId)
    {
        $user = $this->users->findById($userId);
        $order = $this->orders->findById($orderId);

        $order->user()->associate($user);
        $order->save();

        $this->mailer->sendTransferNotification($user->email, $order->orderNumber);
    }
}

Do you see the problem? Part of the reason we created repositories was to hide Eloquent, yet we're using Eloquent's associate() method on an Eloquent BelongsTo object. We're also using Eloquent's magic __get() and __set() methods for the mailer. Our controller obviously knows about our ORM. Hmm...

Solution

Everyone seems to be telling you you should interface all the things, yet, somehow models have been flying under the radar. It's been causing confusion about what in the world your repositories should return.

Eloquent has made it super easy to work with models through the use of the magic methods, __get() and __set(). Interfacing your Eloquent models doesn't even enter your mind! Damn you Taylor for making it so easy! (kidding!)

If you really want to abstract the ORM, you must interface your models! You'll also want stop using the save() method on your models outside of your repositories. This is only seen in ActiveRecord implementations.

Let's refactor.

Interface all the things!

interface Order
{
    public function setUser(User $user);

    public function getUser();

    public function setOrderNumber($orderNumber);

    public function getOrderNumber();
}
interface OrderRepository
{
    public function findById($id);

    public function findByOrderNumber($orderNumber);

    public function save(Order $order);
}
class EloquentOrder extends Eloquent implements Order
{
    protected $table = 'orders';

    public function setUser(User $user)
    {
        $this->user()->associate($user);
    }

    public function getUser()
    {
        return $this->user;
    }

    public function setOrderNumber($orderNumber)
    {
        $this->orderNumber = $orderNumber;
    }

    public function getOrderNumber()
    {
        return $this->orderNumber;
    }

    private function user()
    {
        return $this->belongsTo('User');
    }
}

Our new controller

class OrderController extends BaseController
{
    protected $users;
    protected $orders;
    protected $dispatcher

    public function __construct (   
        UserRepository $users, 
        OrderRepository $orders,
        Dispatcher $dispatcher
    ) {
        $this->users = $users;
        $this->orders = $orders;
        $this->dispatcher = $dispatcher;
    }

    public function transferOrder($userId, $orderId)
    {
        $user = $this->users->findById($userId);
        $order = $this->orders->findById($orderId);

        $order->setUser($user);

        $this->orders->save($order);

        $this->dispatcher->fire(OrderEvents::ORDER_TRANSFERED, [$user, $order]);
    }
}

Now our controller really has no idea about Eloquent or any ORM. Interfacing models gives us a couple of nice benefits apart from abstraction. Mocking models in tests becomes trivial and if you're using an IDE, like PHPStorm, you get some super helpful code completion! You won't always have to remember if you need to attach() or associate() a model to another model. Hide that stuff behind your interfaced method.

You might also have noticed that we made the EloquentOrder::user() method private. This is Eloquent related. Your client code can't use it anymore! That's good.

You probably also noticed I added a dispatcher and am firing an event in the controller. You should probably use the mailer in an event listener, which can make use of your new User and Order interfaces.

Considerations

Things aren't all rosy though. Sometimes things get a bit awkward by accommodating both ORM implementations. For example, if you went the other way and did $user->addOrder($order). In Eloquent that would update and save the model right away, not so in Doctrine. You would still need to use the UserRepository::save() method for that change to actually get sent to the database. This is a price you pay by accommodating both ORM implementations sometimes. I suggest treating relationships like normal model attribute and always using the repositories to persist the changes. Eloquent is smart enough to know if the model is actually dirty and whether or not to perform any database calls. For example:

class OrderController extends BaseController
{
    // other code

    public function transferOrder($userId, $orderId)
    {
        $user = $this->users->findById($userId);
        $order = $this->orders->findById($orderId);

        $user->addOrder($order);

        $this->users->save($user); // In EloquentUserRepository, only save if $user->isDirty is true

        $this->dispatcher->fire(OrderEvents::ORDER_TRANSFERED, [$user, $order]);
    }
}

This brings up my next point...getting to a point where you can swap out your ORM and not alter your client code is a challenge. You have to ditch the ActiveRecord mentality.

Take note! You can treat ActiveRecord models like data mapper models, you can't treat data mapper models like ActiveRecord models though. It just doesn't work.

Is all this necessary to write "good" code? Nope. It all depends on your app and priorities. Do you think you may want to swap in Doctrine2, a data mapper implementation? If so, I'd encourage you to interface your models. If you're fairly confident you won't need to swap out Eloquent, don't bother unless you like the code completion(I do!) and/or testing benefits.

It's tough and unless you're familiar with multiple ORMs you'll probably have some work to do if/when you swap ORMs.

The best display of this I've found is the FOSUserBundle for Symfony. It can be used with both Propel(an ActiveRecord implementation) and Doctrine2(a data mapper implementation). Check out the Models, Propel, and Doctrine directories to see what I mean.

All that said, you must decide for yourself if this abstraction is worth it for your project. It not always is!

Tags: PHP, Intermediate, Laravel

Stop Using Facades

Apparently when experienced developers are introduced to Laravel they're immediately disgusted by all of the static method calls they see. As soon as someone vocalizes this "atrocity" there are multiple prominent Laravel ambassadors to quickly defend the framework by explaining the facade pattern, "Nope, you're wrong! It's actually using OOP behind the scenes!"

Both sides have valid points. Here's my case against using them...

Before we start! I think some people have taken this article as anti-Laravel. That wasn't my intention at all! Using facades are great for gettin crap done quickly. I don't think anyone needs to read a post about throwing stuff together to make things work. We all know how to do that. This post is about some of the benefits you get when you decide(for yourself) not to use them and illustrate how to do that.
A response! Taylor has now made injecting the dependencies under the facades a lot easier. Check out his response to this post.

It seems like an anti-pattern

Many people view injecting your IoC container into your classes as an anti-pattern. I can understand this. If I were looking at someone else's class and trying to figure out what its dependencies were, I would absolutely prefer to be able to look at the constructor rather than track down everywhere the injected container is used.

Injecting the IoC container seems like an easy way to accidentally turn your unit tests into integration tests. Imagine this, you come back to work on a class which you've injected the container. In this class, you add code to use the container to retrieve and use a new service object. It's much easier to forget to go back to your unit test and mock that new service object. Your test might even still pass if you forget to come back. You wouldn't have that problem if you injected the service object rather than resolved it out of the IoC. Your unit tests would fail immediately if you used constructor injection(which would be a good thing).

In my opinion, using facades in Laravel introduces the same baggage as injecting the IoC container. It's practically the same thing, if not worse. The application/IoC container is statically available on all facade classes. This service location is available everywhere. With Laravel, you don't have a choice. However, Laravel facades are great for new devs getting their feet wet with OOP in a solid framework. I can completely understand why Taylor included them. It's sexy for some people.

They tie you to Laravel

Recently there's been a lot of twitter/blog/reddit bantering about being more mindful of creating framework agnostic packages. Phil Sturgeon recently posted an article on his blog about ditching framework fanboy-ism and focusing more on interoperability among code bases. He ruffled some feathers but I agree with his main point. If you develop framework agnostic code, you and others are going to be able to use it when you work in another project. I don't think anyone will argue that that's not a good thing.

You probably don't have framework interoperability code as your primary focus when developing, but by using Laravel's facades you're immediately tying that code to Laravel.

There are some places, like controllers, that this argument is moot. You're most likely not going to share controllers. I'd still advocate ditching facades in your controllers just for the sake of establishing the habit. Establish this habit for your service objects! There's a far better chance you're going to like a service class you wrote and want to use that code again. It'll be much easier if you typehinted an interface into the constructor of that service object's class rather than have to refactor the facades out to be able to use it in framework X.

Okay, I'm sold. How do I do it?

Let's start with the default HomeController shipped with every Laravel install.

class HomeController extends BaseController 
{
        public function showWelcome()
        {
                return View::make('hello');
        }
}


Let's first inject the renderer. If we take a peek under the hood at the facade located at, project/vendor/laravel/framework/src/Illuminate/Support/Facades/View.php we can see the string view being returned from the getFacadeAccessor() method. This facade is pulling out the object from the IoC container with the key of view. With this information we can register a binding.

// project/bootstrap/start.php

/* --other code-- */

$app->bind('HomeController', function($app) {

    return new HomeController($app->make('view'));
});

return $app;


Now we have to update update our controller...but we don't actually know what in the world $app->make('view') returns. After a bit of searching you can see in the Illuminate\View\ViewServiceProvider::registerEnvironment() method the actual object is an instance of Illuminate\View\Environment. Let's modify the controller.

use Illuminate\View\Environment as View;

class HomeController extends BaseController 
{    
    protected $view;
    
    public function __construct(View $view)
    {
        $this->view = $view;
    }

    public function showWelcome()
    {
        return $this->view->make('hello');
    }
}


Note! We've aliased the class to View to be consistent with the facade. This will probably make people using facades more comfortable with your code.

This is already a heck of lot clearer to see what classes are being used. It will be much easier to tell if we're adhering to the Single Responsibility Principle.

Let's accommodate the Input facade for funzies.

This one is a little harder to track down. If you open up the Input.php facade file, you'll see request being returned. I found this binding in the project/vendor/laravel/framework/src/Illuminate/Foundation/Application.php file. You can see the request binding in the registerBaseBindings() method. We can add this to the controller like so:

use Illuminate\Http\Request as Input;
use Illuminate\View\Environment as View;

class HomeController extends BaseController 
{
    protected $input;

    protected $view;

    public function __construct(Input $input, View $view)
    {
        $this->input = $input;
        $this->view = $view;
    }

    public function showWelcome()
    {
        $test = $this->input->get('test');
        
        return $this->view->make('hello');
    }
}


Then update our binding.

// project/bootstrap/start.php

/* --other code-- */

$app->bind('HomeController', function($app) {

    return new HomeController($app->make('request'), $app->make('view'));
});

return $app;


Now if we go to /?test=123, $test will equal "123". Perfect.

Edit! This is an edit made after I originally posted the article. I hadn't looked at Laravel's facade documentation in a while. They have added a handy table for you to find out what the facades actually map to. You can find the Facade Class Reference here.

Stripping facades from service objects

You'll notice we didn't create any interfaces for the controller. Again, this is because we're not going to be sharing controllers across frameworks.

I would create my own interface if I were writing code that I, or others, could possibly be used in the future outside of Laravel. Take the following example.

use MyUserInterface as UserInterface;

class PasswordResetService
{
    protected $user;
   
    public function setUser(UserInterface $user)
    {
        $this->user = $user;
    }
    
    public function fire()
    {
        $email = $this->user->getEmail();
        $message = 'Follow the link: www.project.dev/reset/' . $this->user->getUniqueString();

        Queue::push('SendEmail', array('email' => $email, 'message' => $message));
    }
}


Because we're using the Queue facade, we've unnecessarily tied this service to Laravel. Let's fix that.

use MyUserInterface as UserInterface;
use MyQueueInterface as QueueInterface;

class PasswordResetService
{
    protected $queue;

    protected $user;

    public function __construct(QueueInterface $queue)
    {
        $this->queue = $queue;
    }

    public function setUser(UserInterface $user)
    {
        $this->user = $user;
    }

    public function fire()
    {
        $email = $this->user->getEmail();
        $message = 'Follow the link: www.project.dev/reset/' . $this->user->getUniqueString();

        $this->queue->push('SendEmail', array('email' => $email, 'message', $message));
    }
}


Here's what those new interfaces and class could look like.

interface MyUserInterface {

    public function getEmail();

    public function getUniqueString();
}

interface MyQueueInterface {
    
    public function push($service, array $data);
}

class MyQueueService implements MyQueueInterface
{
    public function push($service, array $data)
    {
        Queue::push($service, $data);
    }
}


We're basically just wrapping the facade. We won't use MyQueueService outside of Laravel. It's adapter code. Now we just need to bind it in the IoC container.

// project/bootstrap/start.php

/* --other code-- */

$app->bind('PasswordResetService', function($app) {

    return new PasswordResetService($app->make('MyQueueService'));
});

return $app;


This is a very simple example but we've completely removed Laravel from this service class. We could package our interfaces and service class up and use it in any other framework now. Awesome.

Get in the habit

Hopefully I've adequately illustrated the benefits of not using facades. Although Laravel's facades are super easy to use, injecting the actual dependencies could really pay off down the line. I think everyone, even Laravel users, will prosper if the use of facades gets phased out. Go forth and develop framework agnostic code by ditching facades!

Tags: PHP, Intermediate, Laravel