Tutorial – Using Tenon as a Grunt Task

Sample code for this post is available on Github: grunt-tenon-demo.

Brief primer on automated task running

Grunt is an automated task runner – that is, a tool that is primarily used to automate repetitious development tasks. A whole pile of big companies use Grunt and there are over 4000 plugins for Grunt. Think about the things you do on a regular basis as a developer. Chances are if there’s a repetitious task you do, there will be a Grunt plugin to do it.

• Do some syntax checking on your JavaScript with JSHint
• Minify your CSS files withcssmin
• Compile you Sass files
• Compress your image files with imagemin
• Compile Coffeescript files to JavaScript
• Run your Protractor unit tests for your AngularJS project
• Or, if jQuery is your thing, run QUnit tests
• Lint your Coffeescript files

Using Grunt is pretty easy. One of the things I really like about Grunt isn’t just its ability to run each of these tasks, but the ability to run many tasks. For instance, given the list above, you can choose to lint your Coffeescript files prior to compiling them. With over 4000 Grunt plugins, there’s a ton that it can do. You can even make your own plugin.

Learn more by reading Grunt’s getting started guide.

Set-up Grunt to use Tenon

This is exactly the kind of thing we wanted to provide when we created Tenon, and it didn’t take long for others to see it too. Ed Gauci created grunt-tenon-client a little over a year ago, and it does a really great job. So I used it to create the Grunt Tenon Demo. Here’s what it does:

1. Runs some non-Tenon tasks, like you would in a normal project, such as:
   1. Cleans the ‘dist’ folder (Line 17 ) where our build will eventually go when all tasks are passed
   2. Runs JSHint (Line 22) on our gruntfile and our JS files
   3. Runs JSONLint (Line 41)on our configuration files. This is important because it ensures our tasks actually work right
   4. Sets up some Git pre-commit hooks (Line 48). More on that, later
   5. Sets up some “Watch” tasks (Line 96). More on that later, too.
2. Runs some Tenon Tasks. In the example, it tests all of the files in the ‘src’ directory that end with an ‘html’ extension, but you can customize this using Globbing patterns.
   1. Test with responsive tablet settings (Line 65)
   2. Test with responsive phone settings (Line 76)
   3. Test with default settings (Line 88)

Naturally you don’t have to test with the responsive design options. We just added them to show off how flexible Tenon is.

Customize it for you

Obviously you’ll need to have an account on Tenon in order to proceed, so register, then login and grab your API key.

Create a configuration file

The most portable way to use this is to create a config file. We’ve created .tenonrc which holds your desired configuration settings. It looks like this:

    {
      "key": "", // put your API key here
      "filter": [31, 54],
      "apiURL": "https://tenon.io/api/",
      "certainty":  "40",
      "level":  "AA",
      "priority": "40",
      "ref": "1",
      "store": "1",
      "snippet": true,
      "viewPortWidth": "1280"
    }

Basically, other than “snippet”, all of these configuration options match Tenon API’s Request Parameters. “Snippet” is an option internal to the Grunt plugin which lets you select whether your results file will have the snippet of violating code with each result.

Set up the task in your Gruntfile

Setting up the task in your gruntfile couldn’t be any easier.

    tenon: {
        /* Set most Tenon options in external file */
        options: {
            config: '.tenonrc'
        },
        /* Test em all under default settings */
        all: {
          src: [ 
            'src/*.html'
        ]
      },
    },

On Line 105 we also have our “watch” task set up so that it runs Tenon anytime one of our HTML pages are changed

    /* Watch tasks */
    watch: {
        html : {
            files : ['src/*.html'],
            tasks : ['tenon']
        }
    }

Use It

Once you’re all set up, you can now use Tenon while you work! Based on the demo code you can now do the following:

• Run grunt tenon to explicitly trigger a Tenon check on all your source files
• Run grunt watch to have Tenon test your HTML files as you modify & save them
• Have Tenon test all your code everytime you run git commit.
• Run grunt to perform all of your default Grunt tasks which, in this case, includes Tenon

Where to go from here?

The existing community contributions to NPM, Grunt, and Gulp offer up near limitless possibilities for including accessibility testing at every phase of development, all the way from basic linting to QA automation and Continuous Integration. Getting accessibility testing into your processes early will help avoid expensive and frustrating rework later.

Feel free to clone and play around with the demo. Then write to us and tell us how you integrated Tenon into your toolset.