The blog of dlaa.me
Tag: "Grunt"
  • "That's a funny looking warthog", a post about mocking Grunt [gruntMock is a simple mock for testing Grunt.js multi-tasks]
    Wednesday, September 10th 2014

    While writing the grunt-check-pages task for Grunt.js, I wanted a way to test the complete lifecycle: to load the task in a test context, run it against various inputs, and validate the output. It didn't seem practical to call into Grunt itself, so I looked around for a mock implementation of Grunt. There were plenty of mocks for use with Grunt, but I didn't find anything that mocked the API itself. So I wrote a very simple one and used it for testing.

    That worked well, so I wanted to formalize my gruntMock implementation and post it as an npm package for others to use. Along the way, I added a bunch of additional API support and pulled in domain-based exception handling for a clean, self-contained implementation. As I hoped, updating grunt-check-pages made its tests simpler and more consistent.

    Although gruntMock doesn't implement the complete Grunt API, it implements enough of it that I expect most tasks to be able to use it pretty easily. If not, please let me know what's missing! :)

     

    For more context, here's part of the introductory section of README.md:

    gruntMock is simple mock object that simulates the Grunt task runner for multi-tasks and can be easily integrated into a unit testing environment such as Nodeunit. gruntMock invokes tasks the same way Grunt does and exposes (almost) the same set of APIs. After providing input to a task, gruntMock runs and captures its output so tests can verify expected behavior. Task success and failure are unified, so it's easy to write positive and negative tests.

    Here's what gruntMock looks like in a simple scenario under Nodeunit:

    var gruntMock = require('gruntmock');
    var example = require('./example-task.js');
    
    exports.exampleTest = {
    
      pass: function(test) {
        test.expect(4);
        var mock = gruntMock.create({
          target: 'pass',
          files: [
            { src: ['unused.txt'] }
          ],
          options: { str: 'string', num: 1 }
        });
        mock.invoke(example, function(err) {
          test.ok(!err);
          test.equal(mock.logOk.length, 1);
          test.equal(mock.logOk[0], 'pass');
          test.equal(mock.logError.length, 0);
          test.done();
        });
      },
    
      fail: function(test) {
        test.expect(2);
        var mock = gruntMock.create({ target: 'fail' });
        mock.invoke(example, function(err) {
          test.ok(err);
          test.equal(err.message, 'fail');
          test.done();
        });
      }
    };
    

     

    For a more in-depth example, have a look at the use of gruntMock by grunt-check-pages. That shows off integration with other mocks (specifically nock, a nice HTTP server mock) as well as the testOutput helper function that's used to validate each test case's output without duplicating code. It also demonstrates how gruntMock's unified handling of success and failure allows for clean, consistent testing of input validation, happy path, and failure scenarios.

    To learn more - or experiment with gruntMock - visit gruntMock on npm or gruntMock on GitHub.

    Happy mocking!

    Tags: Grunt Node.js Utilities Web
  • Say goodbye to dead links and inconsistent formatting [grunt-check-pages is a simple Grunt task to check various aspects of a web page for correctness]
    Tuesday, August 12th 2014

    As part of converting my blog to a custom Node.js app, I wrote a set of tests to validate its routes, structure, content, and behavior (using mocha/grunt-mocha-test). Most of these tests are specific to my blog, but some are broadly applicable and I wanted to make them available to anyone who was interested. So I created a Grunt plugin and published it to npm:

    grunt-check-pages

    An important aspect of creating web sites is to validate the structure and content of their pages. The checkPages task provides an easy way to integrate this testing into your normal Grunt workflow.

    By providing a list of pages to scan, the task can:

     

    Link validation is fairly uncontroversial: you want to ensure each hyperlink on a page points to valid content. grunt-check-pages supports the standard HTML link types (ex: <a href="..."/>, <img src="..."/>) and makes an HTTP HEAD request to each link to make sure it's valid. (Because some web servers misbehave, the task also tries a GET request before reporting a link broken.) There are options to limit checking to same-domain links, to disallow links that redirect, and to provide a set of known-broken links to ignore. (FYI: Links in draft elements (ex: picture) are not supported for now.)

    XHTML compliance might be a little controversial. I'm not here to persuade you to love XHTML - but I do have some experience parsing HTML and can reasonably make a few claims:

    • HTML syntax errors are tricky for browsers to interpret and (historically) no two work the same way
    • Parsing ambiguity leads to rendering issues which create browser-specific quirks and surprises
    • HTML5 is more prescriptive about invalid syntax, but nothing beats a well-formed document
    • Being able to confidently parse web pages with simple tools is pleasant and quite handy
    • Putting a close '/' on your img and br tags is a small price to pay for peace of mind :)

    Accordingly, grunt-check-pages will (optionally) parse each page as XML and report the issues it finds.

     

    grunt.initConfig({
      checkPages: {
        development: {
          options: {
            pageUrls: [
              'http://localhost:8080/',
              'http://localhost:8080/blog',
              'http://localhost:8080/about.html'
            ],
            checkLinks: true,
            onlySameDomainLinks: true,
            disallowRedirect: false,
            linksToIgnore: [
              'http://localhost:8080/broken.html'
            ],
            checkXhtml: true
          }
        },
        production: {
          options: {
            pageUrls: [
              'http://example.com/',
              'http://example.com/blog',
              'http://example.com/about.html'
            ],
            checkLinks: true,
            checkXhtml: true
          }
        }
      }
    });
    

    Something I find useful (and outline above) is to define separate configurations for development and production. My development configuration limits itself to links within the blog and ignores some that don't work when I'm self-hosting. My production configuration tests everything across a broader set of pages. This lets me iterate quickly during development while validating the live deployment more thoroughly.

    If you'd like to incorporate grunt-check-pages into your workflow, you can get it via grunt-check-pages on npm or grunt-check-pages on GitHub. And if you have any feedback, please let me know!

     

    Footnote: grunt-check-pages is not a site crawler; it looks at exactly the set of pages you ask it to. If you're looking for a crawler, you may be interested in something like grunt-link-checker (though I haven't used it myself).

    Tags: Grunt Node.js Utilities Web