imagine easy / dev

Testing Logging in Silex

yitznewton-blog — Tue, 11 Nov 2014 17:03:21 -0500

Silex is a PHP microframework from the same family as Symfony. My shop, Imagine Easy Solutions, uses Silex for some of our most important applications.

Modular setup is at the core of Silex’s game, by means of Service Providers. The MonologServiceProvider makes it easy to add highly configurable logging to your application.

But how to test your logging? It turns out that this Service Provider includes a DebugHandler which you can use to make log entries available in array form.

The complete sample app for this post is available at https://github.com/yitznewton/silex-log-test

For the purposes of this post, we’ll assume you’ve already set up logging – you can compare your composer.json and bootstrap with the ones in the sample repo. The question is, how to access the logs from your tests.

In the test setup, we need to inject a DebugHandler into our Silex container.

namespace Yitznewton\SilexLogTest\Tests;

use Monolog\Logger;
use Silex\WebTestCase;
use Symfony\Bridge\Monolog\Handler\DebugHandler;
use Symfony\Component\HttpKernel\HttpKernel;

class WebTest extends WebTestCase
{
    /** @var DebugHandler */
    private $logHandler;

    public function setUp()
    {
        parent::setUp();
        $this->logHandler = new DebugHandler();
        $this->app['logger'] = new Logger('test', [$this->logHandler]);
    }
}

As an alternative, we can use the DebugHandler that comes pre-wired in the MonologServiceProvider:

public function setUp()
{
    parent::setUp();
    $this->logHandler = $this->app['monolog.handler.debug'];
    $this->app['monolog']->pushHandler($this->logHandler);
}

Now, we need to examine the collected logs so we have something to assert against:

private function assertLogEntry($level, $message)
{
    $logMatches = function ($record) use ($level, $message) {
        if ($record['level'] != $level) {
            return false;
        }

        return strpos($record['message'], $message) !== false;
    };

    $records = array_filter($this->logHandler->getRecords(), $logMatches);
    $this->assertNotEmpty($records, 'Failed asserting that a log entry was made.');
}

Now can test the presence of a log entry with a given log level, matching a given message.

/**
 * @test
 */
public function notOk()
{
    $client = $this->createClient();
    $client->request('GET', '/do-something/not-ok');
    $this->assertLogEntry(Logger::ERROR, 'woe is me!');
}

Decoupling Domain Modules in AngularJS

yitznewton-blog — Wed, 22 Oct 2014 11:07:00 -0400

by Yitzchak Schaffer (@YitzOfTheBits)

The story and examples in this post are taken from my experience with Angular, but from my cursory survey of popular JavaScript frameworks, the ideas apply just as much to Ember.js and others.

I’m an avowed Uncle Bob-ist when it comes to… well, most things. In this context, I have embraced his Clean Architecture, which describes why and how to define and enforce boundaries between large-scale areas of responsibility within an application, such as

business logic
frameworks (integration with HTTP, etc.)
object storage (database abstraction layers, etc.)

Robert C. Martin - Clean Architecture from NDC Conferences on Vimeo.

Wrecked Angular

This predilection led to an acute point of discomfort for me when my team began working on a new project in AngularJS. This Model-View-Whatever JavaScript framework offers its own dependency injection facility, and in the code examples that I’ve seen, this DI service is injected into domain modules, so that they can in turn access their own dependencies.

This is the controversial Service Locator pattern, and here, it has an unfortunate result that erodes the Clean Architecture.

In allowing a business domain module to request its own dependencies via Angular’s DI service, you are giving knowledge about the framework to the domain, and forever coupling them.

The domain code should be the most core part of the application; in theory, it could exist as part of a Node.js application on a server, or a hypothetical Android.js application where Angular would not be used. By introducing Angular into your code, you are preventing yourself from ever using it outside of an Angular application. Such a coupling would also make it impossible to reuse your domain code in e.g. Ember.js, in case Angular should die, or Ember introduce some killer feature that you want to leverage.

Another outcome of having the framework baked into your domain is that you need to load the framework in order to run your tests, which can be complicated and can also erode performance. In a domain with relatively simple POJOs and few dependencies, you should be able to run your tests fast and without fanfare.

So how do we break this coupling and allow our domain code to stand on its own two feet?

The simple answer is to make sure that all the module’s dependencies are injected explicitly, typically as constructor parameters; however, I was unable to find any examples of this mode of decoupled design on the webz.

How to do it

With some JavaScript help from my colleague Cameron, I was able to pull together a solution over the course of a couple days of intermittent experimentation. Notice how the domain code (the “trelloboard/repository” module) has no knowledge of Angular.

Our example application is a Trello clone. I’ve implemented a bare-bones repository object which returns Trelloboard entities. Presumably it would look them up by ID, but in this naive implementation, we’re just hardcoding it.

Each Trelloboard has a number of CardGroups. We’re using RequireJS for loading.

The test injects the q dependency directly into the module, and the Angular services module wires our module into the framework before the controller needs it.

The module

// trelloboard/repository.js
define(function() {
  'use strict';

  function TrelloboardRepository($q) {
    this.$q = $q;
  }

  TrelloboardRepository.prototype = {
    find: function() {
      // first iteration: just return a hard-coded Trelloboard
      var output = this.$q.defer();

      output.resolve({
        cardGroups: [
          {
            name: 'Ungrouped',
            cards: []
          }
        ]
      });

      return output.promise;
    }
  };

  return TrelloboardRepository;
});

The spec

define(['trelloboard/repository', 'q'], function(TrelloboardRepository, q) {
  'use strict';

  var trelloboardRepository;

  describe('TrelloboardRepository', function() {
    beforeEach(function() {
      trelloboardRepository = new TrelloboardRepository(q);
    });

    describe('#find', function() {
      it('returns a Trello board', function() {
        trelloboardRepository.find(1).then(function(trelloboard) {
          trelloboard.cardGroups.should.be.instanceof(Array);
        });
      });
    });
  });
});

The AngularJS service loader (not used when unit-testing)

// trelloboard/services.js
define([
  'app', // the AngularJS kernel
  'trelloboard/repository'
], function(
  app,
  TrelloboardRepository
) {
  'use strict';

  app.service('TrelloboardRepository', TrelloboardRepository);
});

Our controller

define(['app', 'trelloboard/services'], function(app) {
  'use strict';

  // TrelloboardRepository is magically injected by Angular, now that we've
  // wired it up in trelloboard_services
  app.controller('TrelloboardIndexController', function($scope, TrelloboardRepository, $stateParams) {
    TrelloboardRepository.find($stateParams.id).then(function(trelloboard) {
      $scope.model = trelloboard;
    });
  });
});

Don't abuse the closures

easybibpream — Tue, 23 Sep 2014 14:21:00 -0400

by Pream Totaram

I started to read about clean coding practices and started to wonder how they can apply to JavaScript where it is common to define a function within a function. What I started to think is, how could it be possible for a block of code to obey the Single Responsibility Principle and stay mobile, when you have a function within a function. Time to investigate. Coming from my background, languages with classes (like PHP and Java), it took me a while to realize that a function in JavaScript is a more general concept than I’m used to. But I do realize it’s a ability that does get abused. First, what is the Single Responsibility Principle?

It states:

A class should have only one reason to change

Every object (since we are in JavaScript and everything is an object here) should obtain one, and only one goal. Functions, which are also objects, can nest functions, which took me a while to really understand at first, but I’ve come to appreciate how powerful this really is.

With great power, comes great responsibility

– Stan Lee

Although, I immediately saw the risk in allowing this. When I understand that in JavaScript, functions can be used very well to limit scope, it is still possible to use it in such a way without breaking SRP and keeping your code mobile.

Good


define([
  'jquery',
  'underscore',
  'hyperagent'
], function($,_,hyperagent){
  var doSomething = function(){
    //do something here that would return get a HAL object using $.ajax
    //return the object
  }
});

This instance shows an instance where you are loading modules from RequireJS. the parent function is being used primarily to limit scope, to avoid working in the global scope. Working in the global scope in JavaScript can be dangerous, due to possible code collision from anything that may load on the page. However, if you need to reuse any of the child functions, it would be pretty easy. In this case, you would just have to worry about third party packages (jquery, underscore, hyperagent), that you may possibly be using in the destination code. This is also an instance of objeying the SRP, because the parent function only has one job, that is to limit scope (which includes providing access to libraries you may want to use in the scope).

Bad


function doALargeTask()
{
    var that = this;
    var smallerTask = function () {
        //code that heavily uses that
    }

    smallerTask();
}

In this case, it could be extremely helpful in a later situation to use smallerTask(), but as the method grows and grows, it would be increasingly tough to reuse it, because it would potentially rely more and more on the parent method. However, if you pull the child method out early, and only pass to it what you need, you can certain that both doALargeTask() and smallerTask() only do one thing.

Naming things considered hard

hakindazs — Thu, 04 Sep 2014 03:20:58 -0400

by Anne-Julia Scheuermann (@dazzlog)

This week I gave a talk at the Berlin PHP Usergroup about naming things.

For us developers it is a constant task to find the right words for describing things and giving them a context to create meaning and transporting what that thing is about to do to other developers.

In my slidedeck I put together a small guideline to share what I found:

[

](https://speakerdeck.com/dazz/nomen-est-omen-naming-things-considered-hard)

– Anne

Bootstrapping a New Project: XP Epiphany

yitznewton-blog — Wed, 30 Jul 2014 09:59:00 -0400

by Yitzchak Schaffer (@YitzOfTheBits)

Our team has recently begun working on a new product, and dedicated eight developers for the task. We have been struggling with how to get the product from concept into implementation. We’re using an up-front planning approach, specifying detailed understanding of both structure of the system (code architecture and design) and the way we’ll be constructing it. The planning is done at the beginning of a sprint, and we even did some initial work that was meant to span sprints.

We’ve discovered that making decisions and building consensus this way is messy, time-consuming and emotionally tiresome, especially when we have nothing on the ground to work off of. We’re also spending a lot of time trying to predict and pre-design the parts of the system and how they will fit together, introducing many utilities up front and imposing/arguing about a file structure to support those many expected parts.

On the train this morning, I was reading Extreme Programming Explained and discovered these magic words from Kent Beck in chapter 10:

The architecture for a little system should not be the same as for a big system. […] First a small team writes a small system. Then they find the natural fracture lines and divide the system into relatively independent parts for expansion. The architects help choose the most appropriate fracture lines and the follow the system as a whole, keeping the big picture in mind as the groups focus on their smaller section.

So you begin with a single pair sitting with the product owner to create a minimal implementation of one or a handful of stories. Consensus is easy, and design fits the needs of the system at this scale. As you continue building out, adding a server, supporting libraries, etc., the boundaries between layers emerge, allowing you to scale your team out, and split work along those boundaries. Communication about localized design concerns is contained within the smaller layer sub-teams; communication across teams is dedicated to specifying and refining the boundary interfaces that define the services one layer provides to another.

One big upside to experiencing our bigger-process deadlock was the high level of communication and patience it demanded from everyone on the team. It forced us to look hard for the most optimal process for the configuration of our team.

Takeaways for the future: where possible, limited the number of developers initially working on the product, and scale out the team together with the project to avoid the difficulty of mob decision-making.

This is just the beginning of a great product, and if you’re interested in joining our ever-evolving team, reach out at devjobs@imagineeasy.com

Yitz is NYC Technical Lead for Imagine Easy Solutions

Intro to PHP extensions

badlynamedcode — Fri, 11 Jul 2014 13:01:52 -0400

These are the slides for a talk about writing PHP extensions that I gave at the Berlin PHP User Group:

Extending PHP - How to mount a rocket launcher on the back of an elephant (online) (PDF version)

The code I used for demos is available on github and can serve as a kind of starting point for PHP extensions.

Other than that, the main thing to know is to not bother with the official documentation on php.net - it’s incomplete and outdated in parts - and to go straight to blog posts and other resources on the net. Google is your friend here.

Another good resource are the extensions that ship with php. They are of varying quality but most can serve as decent examples for how to get your own extension off the ground.

Happy Hacking!

– Richard Wossal

The Realtime Web with Socket.IO and RabbitMQ

yitznewton-blog — Wed, 09 Jul 2014 01:10:00 -0400

by Yitzchak Schaffer (@YitzOfTheBits)

I have been thinking a lot about the best way to implement a realtime collaborative web app. WebSockets is the maturing tech of choice for this, and although there still seem to be some issues in terms of support, things are improving. Internet Explorer has support as of version 10. Mobile carriers and some institutional firewalls might implement some network-level impediments, but apparently it’s possible to serve WebSockets over port 443 and largely escape this problem.

WebSockets inherently offers a two-way connection between a single browser session and the server; the broader context of what other clients might be connected to the application (such as in a collaborative setting) is outside of the scope of WebSockets. There are several solutions already out there for broadcasting across sessions; the most interesting to my mind are Socket.IO (node.js), Faye (node.js and Ruby), and Autobahn (node.js, Python and more). I decided to use Socket.IO to begin my investigation, based on

the high visibility of Socket.IO as per Google Trends,
a high-profile adoption by the Trello team, as well as
their fairly well-documented falling-out
and my personal preference at first glance for its API.

Disclaimer: This is my first experience working with node.js, so

don’t assume I know what I’m doing, and copy-n-paste my code
go easy :}

Scalability

As I was proceeding with research, the one class of thing that kept popping up in blogs, etc. was scalability issues. I was not really interested in solving those problems within Socket.IO or figuring out if it is still an issue with the current release; for now I’m just maintaining a list of articles about the topic.

Instead, I looked for a way to incorporate Socket.IO into our stack without putting any scaling pressure on it directly.

Solution: use Socket.IO as a dumb transport

My experimental solution is to maintain a cluster of Socket.IO processes whose only function is to maintain the browser connections, and shuttle messages to and from a message queue. With this arrangement, each Socket.IO process is independent of the others, so there is no shared backend or storage to scale. These messages constitute both incoming job requests (e.g. “hey server, update a particular entity”), and outgoing announcements (“hey everyone, entity 123 has been updated”). I chose RabbitMQ as the messaging server for this experiment.

Caveat: I have not yet devised a testing plan to compare this architecture with a “plain” Socket.IO setup, so I can’t say whether this actually makes anything better, only that it avoids any poor design that might have hampered multi-process Socket.IO installations.

Bonus: forced decoupling of application code

An extremely useful bonus involved the application code, as distinct from the transport layer. This insight might even be worth more to me than any Socket.IO-specific benefits.

I had been concerned, with these node.js-based server scenarios, about the idea of implementing an application server in JavaScript. Our team’s server-side specialists (including me) don’t have deep experience with node or JS in general, and with my bias toward type safety features, I personally have misgivings about writing complex things in JavaScript, as opposed to our usual mode of somewhat-type-safe PHP. (I discovered that @vanbosse utilized this same concept in his post dealing with a very similar application of RabbitMQ.)

When we treat all requests and responses as generic, context-agnostic messages, and let the application core pull them off a queue and “report back” in this generic way (as opposed to specialized ones like HttpRequest/HttpResponse), we force ourselves to decouple the application code quite starkly from the transport layer.

In most “MVC framework” situations like working with Rails or Symfony, the best you can hope for is to consciously keep your code decoupled from the web framework you’re using, and that takes discipline. Here, however, our point of departure is a “message-in, message-out” application – pretty much perfectly echoing the Uncle Bobbian Clean Architecture. (See also Gary Bernhardt’s talk on boundaries for more architecture porn.) Not only have we made ourselves implement an ideal interface for testability, we have also freed ourselves to make open decisions about the messaging stack, and even change our minds later. Socket.IO not working out? Just swap in Faye, and all you need to do is write a new messaging adapter for the Faye-RabbitMQ interface. The application itself is unchanged.

Proof of concept: SockBit

To demonstrate this approach, I have created a prototype note-editing application, SockBit. In function, it is sort of like an unfinished 5% of Trello. It uses this stack to allow users to edit notes collaboratively in realtime; when one user edits a note and blurs the input, the change is sent to the server, where it is persisted, and then pushed up to other clients. Here’s a screencast of me demonstrating it.

Conclusion

This was a really fun exercise, and has served as a great demonstration of the possibilities of Clean Architecture in action. The next step will be to see if I can test the scalability of this architecture in comparison with a straight Socket.IO version. My next stop will be checking out PhantomJS at scale.

Yitz is NYC Technical Lead for Imagine Easy Solutions

Choosing your Automated Acceptance Testing framework

asiatheqa — Tue, 01 Jul 2014 14:26:00 -0400

My name is Asia Wolf, and I’m Imagine Easy’s first QA hire. I’ve been writing automated acceptance tests and performing manual regression tests since April 15th, 2014.

After I studied computer science at Carnegie Mellon University, I got my first job as a Quality Assurance Engineer. This was supposed to be the first step on my way to become a “real” web developer. My task was to automate testing for a e-commerce startup. Knowing nothing about automated acceptance testing, I searched the internet for the right framework to use. Unfortunately, most of the articles I could find were incredibly outdated and only talked about one framework’s good or bad points. Since then, I’ve built 3 automated acceptance testing suites in CasperJS, Selenium with RubyBindings and Appium, and Selenium with JavaBindings as well as doing regular research on the tools on the market such as Cucumber, Behat, and Watir. There are almost endless combinations of frameworks you can use for testing, so I hope that by comparing frameworks and advising based on my experience I can help spare your QA team some frustration in choosing the right framework.

Disclaimer: This is mostly geared towards small automation teams who do not need to support Windows or various versions of Internet Explorer (which should probably be manually tested anyway). For those of you who have to support Windows and IE, this is not going to be terribly informative. You should check out Telerik Test Studio, UFT (detailed below), or Selenium Webdriver 2 with IE bindings.

Selenium Webdriver 2

The good: You can automate most browsers and mobile devices in many different programming languages. It’s pretty widely adopted across other frameworks as well, and can integrate with BDD tools such as Cucumber. There are meetups and conferences and Google Hangouts where you can find support. Selenium is pretty easy to pick up with some programming knowledge. I’ve used Selenium with Java with only minor frustration, and Selenium with Ruby and Rspec combined well with minimal set-up for an easy-to-read output and code. You can also use Selenium Grid/Server or SauceLabs to run your tests in parallel across multiple machines.

The bad: Just because you can do almost anything doesn’t mean you should. It’s very tempting to try to make your test suite run on every browser and support mobile devices, but the maintenance cost is very high and it’ll take you a while to figure out how to make each browser’s driver work with your code. I found that utilizing Selenium’s capabilities to run across browsers and devices and in parallel on Sauce was a lot of effort for very little reward. I can remember only one instance where the other browsers caught a bug, because many cross-browser bugs are visual and won’t be caught by automation. All of that effort you spend maintaining can’t be spent making new tests, and you still have to manually check those browsers for visual bugs.

Selenium Webdriver’s documentation leaves something to be desired. I want easy-to-find API docs with good explanations of all of the things I can do, linked from a Getting Started page; but that is not something I can find with Selenium. There are docs, but you have to dig to get to them.

Selenium 3 was promised in August 2013 for a December 2013 release and has been delayed approximately 6 months so far. An effort to combine it with a W3C spec is causing the lateness. After a quick look at the documentation they’ve released so far, I’m not terribly excited and don’t see myself using it for future automation projects.

You should use this if: There are a few cases for choosing Selenium. Maybe your QA team doesn’t have a lot of programming experience and wants to use the language they’re most comfortable with. It’s easy to get support, and you don’t have to learn a new language’s syntax. This approach is also good if you’re a developer making Selenium tests for your product - you can write in the same language your product is in without having to switch contexts as much. Just don’t overreach and try to make it run in every browser on Sauce Labs.

I would mainly recommend Selenium for large teams who intend to utilize the cross-platform and cross-browser testing features or use Sauce Labs. The maintenance cost will be high, but if you have the patience and bandwidth, go for it. Selenium is a widely-adopted and powerful tool for automation and can help you achieve your wildest automated testing dreams if you’re dedicated enough.

CasperJS

The good: I have to start this section out by admitting some bias. I’ve used CasperJS, Selenium, and Cucumber previously and CasperJS is by far my favorite to work with. Writing CasperJS scripts is just more fun. I learned Javascript entirely because I wanted to use this framework, and I am so glad I did. It’s really convinced me that headless is the way to go for automated testing.

I’ve seen people complain about CasperJS’s API, but I’ve found it incredibly helpful compared to the digging I had to do with Selenium. The tester module makes your passes and fails very clear, and the tester API is also nice to work with. You can write your tests in CoffeeScript or JavaScript, and if you can’t figure out how to do what you want in CasperJS you can do it in JavaScript or CoffeeScript. CasperJS is quick, light-weight, and easy to set up. There are very helpful getting started guides for beginners, and one of our interns went from zero programming experience to writing tests in CasperJS in less than two weeks.

Going headless for your automated tests is, in my opinion, the best choice. Automated tests will most likely not completely replace manual testing, and headless browsing takes less time and minimizes the maintenance burden, because you’re not trying to figure out why your tests don’t work a certain way in one browser. This will leave you time for the inevitable manual testing, or for writing even more CasperJS scripts. For those of you who want to try CasperJS but would rather ease into it from Selenium’s easy-to-see Webdriver, I’d recommend running your scripts on SlimerJS. Whereas PhantomJS uses Webkit, SlimerJS runs on Gecko, and launches a small browser window so you can follow along. SlimerJS is not quite ready for prime-time yet, and through experience I would not recommend using it for large test suites. I look forward to following the progress of SlimerJS in the future.

While CasperJS doesn’t have quite as wide an adoption as Selenium, there are already a lot of great open-source tools to help you do a lot of cool things with it. There has been work to incorporate CasperJS with Mocha, Grunt, and Gulp. We use CasperJS with Travis, our continuous integration tool.

The bad: Again, I’m pretty biased. Because my experience with CasperJS has been so positive, I have a hard time finding bad things to say about it. It’s a bit harder to get answers to your questions on the framework because of its newness, and the version I use is a developer version and thus has some bugs. A lot of the tools that work with CasperJS are very new and still have bugs to work out, so you may invest a good chunk of time into them before realizing that they are not mature enough to use for your testing.

Headless browsing is sometimes intimidating; debugging is not incredibly fun to do when you can’t see what your code is doing in a browser. CasperJS’s debug mode combined with its methods to capture screenshots are a good substitute in my opinion, but be patient when you start learning this framework. You can use SlimerJS to see part of the page you’re on for easier debugging, but the engines run a bit differently and what passes on SlimerJS may not always pass on CasperJS.

You should use this if: CasperJS is a great tool for small teams. The output of test passes and fails gets kind of unmanageable once you have a lot of test files, so you may want to look into writing something that outputs a digest of test results to avoid minutes of scrolling. Use this if you’re a small team who wants to make tests quickly. Use this if you know and love Javascript or Coffeescript and want to write your tests in one of those languages. Use this if you want to learn basic Javascript or Coffeescript.

Cucumber/BDD tools in general

The good: Cucumber, Behat, and other BDD tools (including Yadda which plugs into Casper but does not seem quite stable enough for use running tests yet) will restrict the format to combine your acceptance criteria with your automated acceptance tests. It forces you to think through your requirements and makes it easy for non-developers to read your code and run your tests. The syntax is easy to read for people who don’t code.

The bad: Here I have to admit more bias. Every time I start writing a new automation framework I test the part of an app in various languages to compare speed, flexibility, ease of writing tests, and general enjoyment of the language. I’ve never enjoyed writing Cucumber, and find the format kind of limiting. Thus, I have never continued past the experimental stage and actually maintained a cucumber suite.

Many people see poorly developed acceptance criteria and leap to using a BDD tool right away. That might fix the problem, but it will complicate your automated acceptance testing stack unnecessarily. If the root cause is bad acceptance criteria, educate the person writing your acceptance criteria on how you’d like it written, and don’t start writing code until that criteria is clear. Additionally, people see poorly structured automated acceptance tests and leap to BDD. This is again fixing a problem by adding complexity and restrictions, rather than educating your engineers on good practices.

You should use this if: Now, my bias against BDD tools doesn’t completely prevent me from seeing the use. I’ve been a product manager and QA at the same time for the same product, and probably should have used Cucumber instead of Selenium. If your product managers or non-developers read and run your tests, this is probably a good choice. If you are a technical person and everyone reading and running your code is as well, you probably don’t need it. And if you don’t need it, don’t use it and complicate your stack.

Other frameworks and tools I did not include here

I obviously haven’t evaluated every tool on the market. I try not to spout opinions on things I am not informed on, so I can’t pass judgment or advice on the following tools that seem to be decently popular.

Watir: A ruby tool that never really set itself apart enough from Selenium for me to invest the time into investigating it. However, this blog by Allister Scott says some nice things about Watir and makes me wonder if I made the wrong choice, especially given my waning enthusiasm for Selenium.

HP Unified Functional Testing/QuickTest Professional: I run anything but Windows if I have a choice, I like open-source projects, I don’t want to pay for a testing framework, and I have never met anyone who expressed any enthusiasm for this tool. But it does exist and is used pretty frequently at larger companies.

Summary

Look at the disclaimer if you need to automate tests for Windows and Internet Explorer.
There are a lot of tools out there, and what you should use depends on your team size, cross-browser testing needs, and comfort with various programming languages.
For a small team who doesn’t need cross-browser testing, I’d recommend CasperJS.
For a small team who can only write their tests in Ruby, Python, Java, or anything but Javascript for whatever reason, I’d suggest Selenium Webdriver 2 with your favorite language bindings.
For a large team with a lot of patience and cross-browser or cross-platform testing needs, I’d recommend Selenium Webdriver 2 with the various browser drivers, Ruby Bindings, and RSpec.
Only use BDD tools if you have a reason.
Only support cross-browser automated testing if you are ready to put the effort into maintaining it.

Want to join our QA team? Email us at devjobs@imagineeasy.com.

Learn You a Haskell for Great Good in PHP, Ruby, ...

yitznewton-blog — Fri, 27 Jun 2014 09:13:00 -0400

by Yitzchak Schaffer (@YitzOfTheBits)

My main production language is PHP. I started dabbling in Haskell a couple of years ago, out of curiosity. I’ve found a few great resources out there and have gone through the novice lessons a few times. I still haven’t graduated to the point of building Real Things in the language; I have noticed, however, that exposure to the very different approach and style of Haskell had an immediate broadening effect on my PHP work. I encountered a great example of that yesterday.

Iterating with exceptional cases

The problem: we need to collapse a list of strings by interposing a delimiter, the classic sort of implode() operation. But not all cases get the delimiter. The actual application we are building allows for different rules, but let’s treat the “no-Oxford-comma” case for the purposes of this blog post.

class RenderDelimitedTest extends \PHPUnit_Framework_TestCase
{
    public function data()
    {
        return [
            [
                [
                ],
                '',
            ],
            [
                [
                    'jim',
                ],
                'jim',
            ],
            [
                [
                    'jim',
                    'bob',
                ],
                'jim and bob',
            ],
            [
                [
                    'jim',
                    'bob',
                    'joe',
                ],
                'jim, bob and joe',
            ],
            [
                [
                    'jim',
                    'bob',
                    'joe',
                    'pete',
                ],
                'jim, bob, joe and pete',
            ],
        ];
    }

    /**
    * @dataProvider data
    * @param string[] $strings 
    * @param string $expected 
    */
    public function testRenderDelimited(array $strings, $expected)
    {
        $this->assertEquals($expected, render_delimited($strings));
    }
}

If we were to use a loop for this, each iteration would have to know the context of the looping in order to know whether the delimiter should be added. To me, that is both a potential breeding-ground for bugs, and ugly; I should be able to declare the correct rendering for a given segment or combination of segments without reference to segments that I’m not working on.

Pattern matching and recursion

In Haskell, pattern matching is one of the main ways to choose between alternate implementations, given your input. This problem could be solved in Haskell as follows. The function is defined with a type signature first, and then the actual function definition.

renderDelimited :: [String] -> String
renderDelimited [] = ""
renderDelimited [a] = a
renderDelimited [a,b] = a ++ " and " ++ b
renderDelimited (a:theRest) = a ++ ", " ++ renderDelimited theRest

(I’ve bastardized Haskell conventions a little for the sake of unfamiliar readers; Haskellians, forgive me!)

The renderDelimited function takes an array of Strings, and returns a String. There are four cases: the empty array, a one-member array, a two-member array, and “everything else,” in the form of “a merged with theRest.”

I’ve applied recursion to build the full string. Where there are three or more members, we render the first member, the delimiter, and then the output of rendering the rest of the list with the same function. That’s what makes it recursive.

*Main> renderDelimited []
""
*Main> renderDelimited ["bob"]
"bob"
*Main> renderDelimited ["bob", "pete"]
"bob and pete"
*Main> renderDelimited ["bob", "pete", "joe"]
"bob, pete and joe"
*Main> renderDelimited ["bob", "pete", "joe", "larry"]
"bob, pete, joe and larry"

PHP obviously doesn’t support pattern matching in this way, but we can do the same thing with explicit conditionals. Use of the implode() function allows us to merge the 1 and 2 cases.

/**
 * @param array $strings 
 * @return string
 */
function render_delimited(array $strings)
{
    $count = count($strings);

    if ($count === 0) {
        return '';
    }

    if ($count < 3) {
        return implode(' and ', $strings);
    }

    return $strings[0] . ', ' . render_delimited(array_slice($strings, 1));
}

Boom! The tests pass.

By using this technique drawn from bread-and-butter Haskell, we’ve avoided bringing the surrounding context explicitly into the iterations of a loop, and instead we are evaluating each step on its own.

Accessing undefined properties of hashes/objects (in PHP and more)

yitznewton-blog — Wed, 25 Jun 2014 20:45:00 -0400

by Yitzchak Schaffer (@YitzOfTheBits)

The true focus of this post is how to retrieve given member values of associative arrays in PHP, but it will touch on analagous constructs in other popular languages, namely Java’s Map, Python’s dict, Ruby’s Hash, and Javascript objects. The operation can be characterized as:

Given an object Foo, if the Bar property is set, return that; otherwise return a default value Default

This is such a common use case that I would expect this to have decent syntax support in any language that deals with open-ended maps such as the above.

Disclaimer: I’m not well-versed in all of these languages, so forgive any syntax blunders or missed opportunities.

BTW: One of the few “features” of PHP that I genuinely hate is the blurring of the map/list distinction that is the array. I’m psyched that Hack is trying to fix this.

Java

Map.get(key) returns the value for the requested key, or null if it is not set. This has the unfortunate consequence of a logic flaw if null is a possible member of the Map (which is a separate can of worms). So the implementation would still have to be:

foo.containsKey(bar) ? foo.get(bar) : default;

Python

Python’s dict hooks us up proper. Full stop.

foo.get('bar', default)

Ruby

Hash is a curious beast on this question. A default value can be set on the Hash itself as an instance setting, rather than as part of a specific retrieval call. This works either as an argument passed to the constructor, or via the setter #default=:

foo = Hash.new(default)
# or
foo.default = default

foo[:bar]  # returns default

Original Ruby conclusion

To me, employing that technique in this use case seems like a misleading use of that instance setting, so I would be inclined to do:

foo.has_key?(:bar) ? foo[:bar] : default

Updated Ruby conclusion

Tim Morgan in the comments helpfully pointed out the method I was looking for, namely Hash#fetch. So Ruby and Python are neck-and-neck:

foo.fetch(:bar, default)

JavaScript

JavaScript and its undefined property is its own mess, so I’ll just say that JS gives you the in operator:

("bar" in foo) ? foo.bar : default

PHP

Which brings us to the topic of this post. Similarly to Java, when accessing nonexistent members of an associative array in PHP, null is returned, but with an E_NOTICE error. So, leveraging the beautiful Elvis operator (one of my favorite syntactic sugar cubes), we get:

$foo['bar'] ?: $default  // throws E_NOTICE

To bypass the logic flaw of the null, we “can often assume” that null is not a possible value for the array in question. I had (or saw someone employ) the brilliant idea of using PHP’s error suppression operator, @, to make this behave like the Java version, i.e. not throw the E_NOTICE:

@$foo['bar'] ?: $default  // E_NOTICE is suppressed

Obviously suppressing errors is a controversial matter. Some would argue that it’s altogether poor style. It’s also a slippery slope, especially in a team setting: this is the only scenario where I would consider using @, but it’s hard to enforce that discipline across a team. So, I posted this solution on our team chat for feedback.

We are fortunate enough to have Nils Adermann on our team, and he weighed in with some more fundamental concerns, aside from the question of code style.

The bad

Imagine the @$params being an array access object which triggers autoloading in one of its functions; then @$params['foo'] would hide parse errors in those PHP files. So it’s a generally bad idea, since you can never be quite certain what else you are accidently silencing in addition to what you mean to silence.

Furthermore, @ is actually slow, since it triggers the error, jumps into the error handler, executes code there to figure out it’s supposed to be silent, and only then returns back to the original code.

Ha! So, to address the first concern, if we are disciplined we can only use this practice on the sorts of plain string => string arrays that had conceived of; but that doesn’t solve the performance concern. And it requires discipline.

The alternative

We’re also fortunate to have Richard Wossal on board. He pointed out a function library that provides this functionality: igorw/get-in.

\igorw\get_in($foo, ['bar'], $default);

This is clunkier than my ill-conceived PHP version, or the Python version, but it does what we need. Additionally, as of PHP 5.6, we can import functions, so this would become that much more fluid (without the inline fully-qualified name).

The use of this function together with anonymous functions also lends itself to creative local solutions:

function extractParts(array $data)
{
    $part = function ($key) use ($data) {
        return \igorw\get_in($data, [$key]);
    };

    return [
        $part('family'),
        $part('given'),
        $part('suffix'),
    ];
}

Conclusion

This was a really nice way to explore the powers and limitations of this data structure in various languages, and seeing the implications of pushing those limits. It was also a good illustration of how ideas that smell questionable, very likely are questionable.

Addendum

Here’s my interpretation of Go, using the “comma ok” double-return-value idiom:

if bar, ok := foo["bar"]; ok {
    return bar
} else {
    return default
}

Defining Communication in WebSocket Applications with WAMP

yitznewton-blog — Thu, 19 Jun 2014 10:59:00 -0400

by Yitzchak Schaffer (@YitzOfTheBits)

In an earlier investigation, I conducted a very high-level comparison of WebSockets to AJAX. I discovered that WebSockets, with its inherently persistent connection, makes more sense in principle for a low-latency interactive application, but that there is no built-in semantic for requests and responses in the way that AJAX inherits from HTTP. Enter the ill-named protocol of WAMP.

Web Application Messaging Protocol (WAMP)

Boom. This is pretty much exactly what I had been looking for. WAMP (http://wamp.ws/) is a subprotocol of WebSockets, in that it specifies a communication semantic for messages sent over WebSockets.

WAMP identifies two planes of communication (two “patterns”): informational messages and commands. Messages can be sent (“published”) and listened for (“subscribed to”), which WAMP calls the “PubSub” pattern. Commands can also be issued (“called”), implemented, and responded to. WAMP refers to this as the pattern of “RPC,” Remote Procedure Call.

In this scheme, a middle layer (“Router”) is introduced between sending and receiving parties (“Clients”). Each Client (e.g. a browser or application server) can register itself with the Router as subscribing to a certain message type, or implementing a certain procedure type. The Router is responsible for receiving messages, distributing them to the appropriate Clients, and responding to or acknowledging most messages in a sensible way.

The Router with the Clients are referred to collectively as “Peers.”

Use in a typical web application

So in the case of a real-time collaborative web application, each user’s browser would register itself as a listener to the appropriate message types, and each application server would register itself as a provider of the appropriate procedure calls, and possibly messages as well. So to represent a user joining the chat room called “WampChat” and sending a message, the flow might look like this:

Browser which is joining, contacts router

12345 is a session ID generated by the server
44978 is a request ID generated by the browser
64621 is a publication ID generated by the server

Flow:

Browser: ["HELLO", "com.example.chat", {}]
Router: ["WELCOME", 12345, {}]
Browser: ["PUBLISH", 44978, {}, "com.example.chat.joinroom", [], {"user":"bilbo", "room":"WampChat"}]
Router: ["PUBLISHED", 44978, 64621]

Router broadcasts join event

78945 is the “joinroom” subscriber ID of a browser already connected to the room

Server: ["EVENT", 78945, 64621, {"user":"bilbo", "room":"WampChat"}]

Browser requests that a user be kicked

34236 is the request ID for the post, generated by the browser

Browser: ["CALL", "com.example.chat.kickuser", 34236, {}, [], {"room":"WampChat", "user":"trollza987"}]

Router requests fulfillment of the kick

89731 is the registration ID of a server already connected to handle “kickuser” calls

Router: ["INVOCATION", 34236, 89731, {}, [], {"room":"WampChat", "user":"trollza987"}]

Server performs, and result is sent back to browser

Server: ["YIELD", 34236, {}, ["OK"]]
Router: ["RESULT", 34236, {} ["OK"]]

Load balancing the routers

One thing I’m not sure about is how to load-balance Routers. As far as the other Peers are concerned, there is one endpoint for the Router that they need to deal with, so registering listeners and RPC-handlers with a given Router instance means that all Router instances need to be made aware of this. It might be done via a shared Memcached or Redis instance, as in this very ominously stormy diagram:

WebSockets vs. AJAX: an initial comparison

yitznewton-blog — Fri, 13 Jun 2014 09:46:00 -0400

by Yitzchak Schaffer (@YitzOfTheBits)

At ImagineEasy, we are starting on a large new product, with a significant frontend component. We have agreed on the idea of a single-page JavaScript application, but we aren’t sure about whether to use AJAX or WebSockets for the underlying client-server communications; so I decided to put together a high-level comparison. Disclaimer: I have mostly backend experience, and almost no SPA projects under my belt; so I probably have blind spots here.

Browser support

There is no support for WebSockets in IE before IE10 (as well as older versions of other browsers), so if you are committed to supporting those users, you won’t be able to use WebSockets.

Server support

WebSockets require a dedicated process independent of the HTTP server, for handling the WebSocket traffic. If you have HTTP and WebSocket on the same box, it will require a reverse proxy to allow both to listen on port 80. Using WebSockets also requires an implementation in the programming language you are using, with all of the knowledge, ops, and maintenance costs that go along with that.

Statefulness

WebSockets are stateful by nature; the browser-server connection is held open throughout the user’s session, allowing both browser and server to push data to the other party. This means there is no need for special handling to reconstruct session-stateful data, such as a memcached server to share session state among servers in an AJAX cluster. It’s also unnecessary to destroy sessions with WebSockets, as the close of the connection is in itself destruction of the session.

Message semantics

AJAX inherits a number of message semantics from HTTP which have no analogue in WebSockets. Because HTTP uses URLs, requests are inherently namespaced in an implied hierarchical structure. The WebSocket protocol simply specifies a string or binary blob, leaving it up to the implementation to specify “locations” to act upon. HTTP also provides a framework for responding to requests with standard status codes; in WebSockets, a server-client message is not even inherently identified as a response, so it’s up to the implementation to flag a message as the response to an earlier received message, and to impose a system of indicating “error” vs. “OK” status, etc. Finally, HTTP headers provide a convention for attaching metadata to messages.

Data typing

In both AJAX and WebSockets, the actual data payload is untyped, being either a string or plain binary. The application must establish its own convention of type and its enforcement (e.g. JSON Schema).

Conclusion

That’s the skinny on our initial overview of AJAX vs. WebSockets. I would love to see a convention evolve for providing some of those missing features to WebSockets. I did find a post from New Bamboo which seems like an embryonic form of that, but I’m surprised I didn’t find more. Let me know if I’m missing something!

Why Laravel Homestead Makes Me Nervous

yitznewton-blog — Sun, 18 May 2014 12:04:00 -0400

by Yitzchak Schaffer (@YitzOfTheBits)

I had an immediate negative reaction to the news of Laravel’s new Homestead program. In their own words:

Laravel Homestead is an official, pre-packaged Vagrant “box” that provides you a wonderful development environment without requiring you to install PHP, a web server, and any other server software on your local machine.

For starters, part of my reaction was due to my irritation at all the marketing that Laravel has been pushing out regarding an upcoming announcement, which I presume referred to Homestead, and Forge, their new hosting solution. My perception of that as hype, in addition to the not-terribly-innovative nature of this huge revelation, didn’t dispose me well to the announcement.

In truth, I can see how the availability of this pre-built development platform will be a tremendous boon to a lot of Laravel users.

Now that I’ve had a chance to get past the initial emotional reaction, I can start to analyze the more objective reasons this project bothers me.

When I was your age

I’ve been doing web development with PHP for about 6 years. In that time, I’ve bootstrapped my knowledge of Linux in general, and running servers in particular. I learned, from the ground up, all about configuring Ubuntu servers, including using Puppet for management. Since I joined the Imagine Easy team in January, I’ve added some experience with cloud virtual-server hosting and deployment.

This in-the-trenches learning is both a reflection of my natural mode of “dive in there and figure it all out,” and a reinforcement of it. Most of my experience has come with the luxury of time and resources to just dig in and get to know different ways of solving problems in a given space. This means that I value getting my hands dirty with all different parts of the system, and having a hand in setting everything up.

The notion of a pre-built environment is a challenge to that perspective. Whereas I try to get as much perspective and knowledge as I can to inform decisions about my stack, I see Homestead as taking that away from developers. This means they are trained to delegate decision-making, as well as losing the actual knowledge and in-depth experience they might have gotten by being thrown in the deep end.

I fully acknowledge that this is not a complete nor totally fair assessment of Homestead; but this outlook greatly influenced the light in which I see Homestead.

The Laragarden

@yitznewton Laragarden
— Michael Hasselbring (@mikelbring) May 15, 2014

A more serious argument against buying into Homestead is the notion of platform dependency. Over the last two years, Robert C. Martin (“Uncle Bob”) has been by far the greatest influence on my thinking. One of his mantras (see Clean Architecture) is maintaining independence from things that you don’t control. In the context of frameworks, it means isolating your business logic from the framework in discrete, Plain Old Object code. One immediate benefit of this is that the core logic is easier to test, being separated from any framework plumbing. A second is that, when the framework inevitably changes, you are not forced to make painful changes in the midst of your application; instead, all that’s necessary is to write the boundary layer that connects your free-floating business code to the framework.

The same concept applies to other components of the stack. If you hard-code persistence into your core code in terms of (MySQL|MongoDB|ActiveRecord|Redis) or whatever, and mix business logic in the same place as persistence, you are stuck with that decision, unless you want to rewrite it.

Using a full-stack boxed solution like Homestead encourages that sort of thinking. I acknowledge 100% that it doesn’t force the behavior of lazily (or unwittingly) coupling these external elements into your application, but it almost implies that is the way to go.

Down the road

Furthermore, let’s say an application grows, and requires a particular piece added to the stack – Solr search, perhaps. How easy will it be to add those components? Will the knowledge gap fostered by Homestead bite the project developers now that they need to extend the stack? You run into the same fragility problem where decisions made by the Homestead team down the road may conflict with your local emendments to the build.

The project’s documentation also indicates that running multiple Laravel applications on a single Homestead instance is the normal mode of operation; that seems to indicate that the Homesteaders are not taking project-specific build modifications into account.

Conclusion

I am confident that Laravel Homestead will help a lot of people, and I am grateful to the entire Laravel enterprise as a key player in the continuing maturation of the PHP community. I have tried to highlight what I see as the key shortcoming of Homestead, and why I believe sober discretion is required in using such a pre-boxed solution.

Introducing travis-artifacts.php

tillinside-blog — Thu, 08 May 2014 10:28:27 -0400

At Imagine Easy, we pride ourselves on building great products on a great foundation. A great foundation means to also focus on code quality, and with said quality, the right amount of tests and (of course) coding standards.

Travis-CI

For continuous integration and continuous delivery, we’re hugely invested in a platform called Travis-CI. At the very minimum Travis-CI allows us to run tools like phpunit and php codesniffer on code pushes. On successful builds (and merges) it also hooks into our in-house continuous deployment service (to be show-cased later :)).

Travis-CI is a hosted service — it’s in the cloud. When code is pushed, a VM is started and our tooling is run.

In order to keep track of improvements and regressions, we utilize a rubygem called travis-artifacts, which allows anyone to store reports generated on Amazon S3.

travis-artifacts is a neat little tool, however, it comes with a not so small ruby dependency called Nokogiri.

Nokogiri is an XML parser which is probably used inside travis-artifacts or one of its dependencies when they talk to the Amazon APIs to store files on Amazon S3.

Nokogiri

Nokogiri is about 150 MB once installed and needs to be downloaded and compiled during each test run, which implies a considerable slowdown and essentially build backlog when we try to advance.

Since most (if not all) our builds run in a PHP environment, we decided to improve this situation.

travis-artifacts.php

travis-artifacts.php - https://github.com/easybiblabs/travis-artifacts.php

The code is free for use (and open-sourced under a simplified BSD license). We try to mimic the API of the travis-artifacts tool. In a nutshell, here’s how you integrate it into your PHP project:

Because the tool is available through packagist, you add the following to your composer.json:

{
  "require-dev": {
    "easybib/travis-artifacts": "~0.2.0" 
  }
}

On Travis-CI, ensure development dependencies are installed (in .travis.yml):

before_script: composer install --dev --prefer-dist

To publish build artifacts, add the following:

after_script: ./vendor/bin/travis-artifacts --path=results --root=/home/travis

This assumes that the results from your tools are stored in a results directory.

Along with these modifications to your .travis.yml, our tool expects/uses the following environment variables. In case you have not used travis-artifacts before, the following is also required:

  global:
    - ARTIFACTS_S3_BUCKET=your_aws_s3_bucket
    - ARTIFACTS_AWS_ACCESS_KEY_ID=your_aws_key
    - ARTIFACTS_AWS_SECRET_ACCESS_KEY=your_aws_secret

So simple! :) So easy(bib)!

Fin

In summary, we saw between 1 to 2 minute faster builds. Since we try to keep our builds fast (and usually under 5 minutes), this is a hefty improvement!

We hope the code is useful to others.

All feedback and pull requests are always very welcome.

Cleaning Code As You Go

yitznewton-blog — Fri, 02 May 2014 17:39:00 -0400

by Yitzchak Schaffer (@yitznewton)

As one of the first steps in a major new feature we are working on for EasyBib, we needed to introduce some polymorphism into the application. The polymorphic class was already implemented in another product; all that we needed to do was refactor the existing implementation to swap in the new polymorphic version.

In the course of doing this in a ~300-line pull request, we were able to make a number of Clean Code improvements to the one class involved:

Remove an unused instance variable, which had been originally added in anticipation of functionality that never materialized
Remove commented-out code
Replace magic values with a named constant
Improve variable names dramatically
Add temporary, placeholder variables to make intent more clear
Refactor business logic out of the web controller and into its own POPO class, with minimal dependencies
Move variable declarations closer to where the variables are used

Additionally, we replaced some very old-school loop-based building of data arrays with array_map() and array_reduce() calls.

We have a long way to go, but these are some wonderful steps toward an ever-cleaner codebase.

Maintaining Clean Boundaries

yitznewton-blog — Tue, 25 Mar 2014 14:20:00 -0400

by Yitzchak Schaffer (@yitznewton)

One of Uncle Bob’s pieces of advice in Clean Code, is to protect the boundaries of your codebase from change. In practical terms, this means insulating the use of third-party libraries in your codebase by wrapping them in an adapter interface.

We use Guzzle extensively in our products, particularly our OAuth2 client. Guzzle is an excellently-designed HTTP client library for PHP. I actually contemplated using a wrapper when first starting a couple of new projects with Guzzle, but the fact of its great design led me to believe that this was unnecessary.

The release of Guzzle 4 showed how I was wrong. The essential structure is very similar to Guzzle 3, but interfaces and namespaces have changed, meaning that I now need to completely rewrite the tests and implementation for all the integration points throughout our products. If I had gone with the adapter layer, I could have simply written a new adapter, and the integration points would have remained unchanged.

Isolate your boundaries with adapter interfaces!

Test-Driven Development in Context

yitznewton-blog — Tue, 25 Mar 2014 11:02:00 -0400

by Yitzchak Schaffer (@yitznewton)

This article comes in response to a critique of TDD eloquently advanced by my colleague, Richard Wossel. Rather than offer a point-by-point comparison of our perspectives, I am going to paint TDD in a broader context, and I hope that this will clarify its value as I see it.

The most essential aspect of my practice of TDD to me, is that it works when I create software in this way. I look at my output, and I see that the quality improves when I test-drive. I have a better understanding of the process and the product. I also prevent myself from introducing bugs, and catch edge cases up front that would have needed post-hoc analysis to identify and correct. My code is better insofar as TDD makes me think more carefully about what I am doing, in order to write correct and comprehensive tests. This alone justifies the practice to me.

So what is TDD? I find it useful to think of it in terms of Behavior-Driven Development. Like Mike Brown and subsequent commenters on this Programmers Stack Exchange answer, I see BDD as nothing more than a clearer restatement of Test-Driven Development. TDD represents a focus on defining and measuring behavior of the system under test (SUT).

Example application

We have a product to build; let’s say that it is the web service API behind a mobile check-in app. We have decided on a framework, and are ready to begin development. How do we proceed? What guides us through the process of building the application? We should start by considering the response we get back from the API for a checkin. We expect that the response code will be 201, the body will consist of a particular JSON status, and the Content-Type header will correspond to this.

Given I have a logged-in user
When I receive a POST to /checkins/ with {lat: 23.45, lng: 98.76}
I should respond with a 201 status
And I should include the Content-Type header of application/json
And I should include a response body of {"status":"ok"}

Sound and look like acceptance tests? Exactly! TDD and “acceptance” tests intersect at this highest level. We can write those tests now, and if we need to, defer writing the implementation, marking them incomplete as we drill down into the application. For the sake of this post, I am going to assume that we have taken care of the “logged-in user” requirement. We can make this test pass easily enough (use your imagination with regard to the framework):

public function createAction()
{
    return (new Response())
        ->setStatus(201)
        ->setContentType('application/json')
        ->setBody(json_encode(['status' => 'ok'])
        ;
}

Let’s consider the case of invalid coordinates. Assume we have built the above case already, with a CheckinController which has a create action. Here’s an abbreviated test:

When I receive a POST to /checkins/ with {lat: foo, lng: 123.4}
I should respond with a 400 status

When we start writing the CheckinController:create action, we discover that some code somewhere needs to know about valid and invalid coordinates. For the sake of passing the tests, we could place that in the controller, and extract to its own class later. With the following, we should be able to make the above tests pass:

public function createAction()
{
    $coordinates = $this->request->getParams();

    if (!$this->validateCoordinates($coordinates)) {
        return (new Response())
            ->setStatus(400)
            ;
    }

    return (new Response())
        ->setStatus(201)
        ->setContentType('application/json')
        ->setBody(json_encode(['status' => 'ok'])
        ;
}

private function validateCoordinates(array $coordinates)
{
    if (!is_float($coordinates['lat'])) {
        return false;
    }

    return true;
}

This would be a good time to extract that validation into its own class – the “refactor” step of the “red-green-refactor” cycle. Now arriving at the creation of a coordinate validator, we have the ideal opportunity to do our initial thinking about edge cases. We can leave our 400 error test above to test controller behavior, and bring the case itself down as the first unit test for the validator:

When I receive a latitude which is a string and a longitude which is a float
Then I should return false

Since we need concrete test cases, we will need to choose specific values, being careful that there are no assumptions which gloss over further “typey” edge cases, such as floating-point math slop, truthy-falsy inconsistencies, and the like. Here we translate this test into xUnit syntax:

$this->assertFalse($validator->validate(['lat' => 'foo', 'lng' => 123.4]));

Analysis

Based on these examples, we can derive some conclusions about TDD. Firstly, it is not inherently about the “unit.” The focus can be anything from a minor subsystem responsible for validating a particular type of input, to the entire application. It’s also not specifically about finding or preventing bugs. The goal is ensuring that you have defined exactly what your unit of code is supposed to do before writing it, and that the code in fact does those things, and nothing else. It’s a general set of practices that informs the development process for all levels of an application.

TDD carries several immediate design benefits. Firstly, it uses human nature to push the developer to manage dependencies and coupling. The insistence on testability means that we need to set up each system for testing. The more dependencies a SUT has, the more irritating the process of building and maintaining the tests. The ongoing frustration that comes with having to manage excessive dependencies helps spur the developer to appropriately divide responsibilities. This leads to the system being flexible enough to accomodate future growth and changes in the application, and this is a direct design benefit of TDD.

Secondly, because all changes must be preceded by tests, it follows that, if a behavior cannot be tested, it cannot be incorporated into the system. This ensures that the magical and mystical, along with their attendant mystical bugs, will be absent.

An additional design benefit results from the outside-in behavioral orientation that I have assumed. Because we always look at a system under test from the perspective of the consumer of that system, we are more attuned to considerations of interface, which helps us choose better names. We also get direct and immediate feedback on the way we have structured the divisions between subsystems.

Conclusion

I am not a strict TDD practitioner (yet), but I have been working these techniques into my coding over the past several years, and I am still learning and refining them. I do it because I perceive the benefit in the code I create. I would consider my main mentor in this to be Uncle Bob Martin, via his writings. I encourage anyone with further interest to read the excellent material on TDD in his classic Agile Software Development, a.k.a. “the PPP book”.

Epilogue

I used a pseudo-framework for the examples above, but the outside-in design methodology could apply here also: we could continue on building the framework itself based on the interface decisions brought on by our demo application.

Turning Comments into Code

yitznewton-blog — Wed, 12 Mar 2014 13:13:00 -0400

by Yitzchak Schaffer (@yitznewton)

I was just reading in Clean Code:

The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration. So when you find yourself in a position where you need to write a comment, think it through and see whether there isn’t some way to turn the tables and express yourself in code. Every time you express yourself in code, you should pat yourself on the back. Every time you write a comment, you should grimace and feel the failure of your ability of expression.

The day after I read this, I had to modify some code in our API. My initial pass looked like this:

if (!$user) {
    // this must be a guest user

    return [
        'id' => $userId,
        'first' => null,
        'last' => null,
    ];
}

I was reminded of Uncle Bob’s advice, and restructured the code into this:

if (!$user) {
    return self::getGuestUser($userId);
}

// ...

private static function getGuestUser($userId)
{
    return [
        'id' => $userId,
        'first' => null,
        'last' => null,
    ];
}

Instant ROI gratification on that chapter! How’s that for expressive code?

Test Driven Development is not the solution

badlynamedcode — Wed, 12 Mar 2014 09:17:00 -0400

This is the first of a set of posts representing different viewpoints on Test Driven Development.

by Richard Wossal

It’s hard to argue against TDD because that is often construed as arguing against software testing itself.

I guess there are actually people who think that all testing is bollocks, but I am not one of them. I think that there’s value in regression and acceptance testing. Yet I still think that TDD is absolutely the wrong way to go. I’ll try and explain that opinion.

I will try and not bring up any arguments that boil down to “if you’re being stupid, TDD doesn’t help”. Sometimes people claim that TDD makes software development easier. But “easy” is a big concept and I assume they don’t mean “follow that one weird trick and your programs will always work”. Nobody can expect any software development technique to help so much that you can switch your brain off - and I don’t expected that from TDD.

The object of TDD is the unit, and the unit test. That is not necessarily always true, one could theoretically do test driven development against higher-level functional tests. But since one of the claims pro TDD is that it makes the code itself better, and since we write programs by typing in one unit of code after another (roughly), I think it’s fair to say that the unit is the canonical choice for TDD.

So TDD starts out with a simple test. That test fails, so then there’s code being written to satisfy the test. Then add another test and so on.

The usual claim is that, by going by that method, you’re going to end up with a testable (hence well-designed), and well-tested unit of code.

In my opinion there are a few things wrong with that claim.

First, testable does not equal well-designed. In fact, testability and well-designed-ness of code are completely orthogonal. Yes, an easily unit-testable class is probably better than the same class with a design that prohibits unit-testing. But it’s only exactly that.

The class might be completely unnecessary. This is a particularly common oversight. The functionality might already exist elsewhere. Or the class might just not do anything worthwhile at all. TDD doesn’t help here. In fact, it even hurts. With the writing of a unit test for that useless class it cements it into the system. You wouldn’t throw that well-tested class away, now would you?
The class might make assumptions about the context that aren’t valid. A common thing to “demo” TDD itself is to write a function that generates the Fibonacci sequence in test-driven style. Obviously, it’s a demo of a concept and not part of a mathematical library but even so - most implementations will recurse into a stack overflow, and generally be slow as molasses. Because they’re simplistic, and that’s fine. Except when it’s not.

That part, the wrong approach, try again part of software development, is completely ignored by TDD. Sometimes you’d even hear that wrong approaches just don’t happen with TDD (which is so obviously ignorant it hurts). Other times, TDD proponents will lean on the good code coverage their approach generates. This supposedly makes rewriting the code easy and - most of all - save.

So that’s the next topic: code coverage.

There are a couple of ways to measure code coverage. And there’s the nice buzz word of “100% code coverage”.

Yes, there is such a thing as 100% coverage. For example, you can exhaustively test the addition of two 32 bit integers by writing 18446744073709551616 tests. But since running those tests would take a few years, I think we can conclude that exhaustive testing isn’t practical. With exhaustive testing also dies the idea of “100% code coverage”. What do people even measure to come to the incredibly stupid conclusion that they are testing 100% of anything?

In the PHP world, when people say “100%”, they mean “100% lines of code” because that’s what the main PHP testing tool puts out. Other environments will have other conventions - slightly different stupidity of the same magnitude.

Line-based, and token-based, coverage measurement is easily debunked by changing the value of the things the tokens stand for. In other words: if the program is using variables, constants, or symbols of any kind, a lexical approach to coverage-measurement won’t tell you anything. Your tests may cover the whole space of possible tests (unlikely, see integer example above), or they may just cover a tiny portion of it.

Branch coverage is a stronger measurement, since that at least has a runtime portion to it. But what is a branch? Do you count every single jump-if-zero on the CPU level? Do you count fall-through cases in switch-case statements? Do you count vtables and dynamic dispatch systems? Obviously, even if that is all factored-in: you still don’t know if you are really covering 100%. Many common sources of bugs - integer overflows, buffer overruns, off-by-one errors of all kinds - are still easily achieved with 100% branch coverage.

And then there’s “100% of all functions or methods called” - well, you’re not even trying, are you?

So that kind of “coverage” (and even “more coverage than before”) doesn’t tell you shit about how save it is to refactor that code. It doesn’t tell you anything about what is tested, how it’s tested, and whether or not that all makes sense. It doesn’t tell you if you’re going to be lucky and break your new code in exactly such a way that a test catches it. Increased “coverage” does not imply increased safety. Not at all.

Aside: this has a social/cognitive dimension, too. If you believe that what you’re doing is save because of bogus measurements of test effectiveness, that can actually be more dangerous than not having any tests at all. If there are no tests then it’s clear that your brain is the thing that will have to make it work. So you have to think about what you’re doing, and how it affects the system. If, however, you believe that the tests catch you, you’re probably going to be a little more sloppy. It’s like a handrail that’s not bolted on properly. If people lean on it, that can easily be more dangerous than not having a handrail at all.

But TDD proponents being ignorant is one thing. What really bugs me about this is that the “100% coverage” story is what programming is all about.

This is the fundamental thing about programming: there are umpteen-million-billion cases, and we just cannot try them all. We do not, and we can not know if that program will even halt.

And coming into that fundamental problem of computer programming, coming to people who all work around it in various clever ways, with a “solution” that basically says “I know, we’ll just ignore it” - that, my friend, that makes me angry.

What we ought to do instead is trying to make sure our programs are correct by making it easy to reason about them. Patiently write our regression tests for every reported bug. Write acceptance tests, automated integration tests, that make sure that at least the common paths through the whole thing still work.

And not claim that this is the silver bullet that kills all bugs.

Dijkstra:

Testing shows the presence, not the absence of bugs.

The Angel of Refactoring

yitznewton-blog — Wed, 05 Mar 2014 11:54:00 -0500

by Yitzchak Schaffer (@yitznewton)

This is one of the nicest feelings in coding. You’ve been working a couple of hours on some legacy code, with a thorny refactoring of stuff that’s used in a couple of places. After a morning buried in the code that deals with one of the implementations, you have a nicely reworked version, and you’re at a few hundred lines of delta.

You realize you now need to implement the new solution in the other place where this problem is addressed. That code, you remember, is a bunch of hacked-together smelly rubbish. You grumble, wondering how much more work this is going to take.

But the Angel of Refactoring is waiting for you in the other spot. You look at the code, and realize that the new version has this case covered without contorsions, and this:

$presenter = $this->getPresenter();
$presenter->setProjects(array($project->toArray()));
$collection = json_decode(json_encode($presenter->handle()), true);
$this->result = $this->apiLinkTransformer->transform($collection[0]);

… becomes this:

$this->result = $this->getProjectDecorator()->decorateProject($project);

And all you can say is: XD

Thank you, Angel of Refactoring!