One of our current projects covers creating a bespoke Salesforce mobile application for a large company in the tourism sector. One of their requirements was to have printing functionality from the app. Seeing as our MobileCaddy SDK provides a toolkit for building hybrid mobile applications for Salesforce we turned to the existing Cordova plugin ecosystem and came across the cordova-plugin-printer plugin. It is common place for the Salesforce consultancies that use our SDK to consume the Cordova plugins via the mightily handy ngCordova project, and luckily this printer plugin was already supported by the project.

Although this plugin, and the ngCordova interface, suited our needs (and worked well) part of the beauty of building hybrid apps is the ability to use common web development workflows, which include building and (doing a certain amount of) testing in the browser.  To do this many of the plugins on ngCordova also include mock instances that either interact with standard browsers capabilities or simply stub the calls. In the case of the cordova-plugin-printer though, this mock did not exist.

This post covers the steps we used to create a mock for the plugin and then create a PR for ngCordova, with the hope our code can be included in a future release. Giving back (even if in a small way) to open source source communities is one of the things we really enjoy. Through this post I hope that others may feel inspired and able to do the same. Creating fixes, patches and features are just small parts of developing software; interacting with an OS project can sometimes feel a bit daunting, but hopefully this post will help.

Getting setup to make our change

First up we need to make a fork of the ngCordova github repo, and I’ve assumed that you already have a github account. This fork is where we will do our development and run initial tests against. So next step is to clone this fork to your development environment.

Once we have our own clone of the project we need to create a branch to work on. In the case for the above (adding a mock for the printer plugin) I created a branch called feat/printerMock.

I also want to confirm that all unit tests for the project currently pass. If I did this after I started making my code changes it would be a bad idea as I wouldn’t know if I’d accidentally altered something. The ngCordova project comes with support for running karma unit tests via gulp. All tests can be run with the following command;

Running this initially gave me the following errors, it seems my project’s development environment isn’t quite ready yet

Looking at the project’s directory I can see that we have a package.json and a bower.json, and so it seems I need to install some packages and dependencies. These can be installed with the following two commands.

From the output of these commands I can see that a whole host of things, including angular, has been installed into my project’s directory… so I run the gulp karma command again. This time all looks good; at the time of writing there were 269 unit tests, and all passed so I was happy to continue.

Adding the Printer Mock

The plugins’ code can be found in the src/plugins directory. And looking at the printer.js file I see a simple interface with just two functions exposed, isAvailable and print. These are the functions I want to create a mock for. First up I create a new file in the src/mocks directory called printer.js (to match the real one). My first skeleton file looks like this;

Add a test for our mock

Next up I create a test spec for this new mock, this is a file called printer.spec.js that I put in the test/mocks directory. This test spec will contain a couple of basic tests to check my mock implementation.

The skeleton file for the test spec looks like this; it’s very basic, and at present doesn’t do anything much other than describe a test block and ready it for use in testing the ngCordovaMocks module.

Following the beforeEach block I now add another describe block that will contain my specific printer plugin tests. This itself contains another beforeEach that injects the cordovaPrinter factory seen in our skeleton mock above. Our spec now looks like this;

If we run gulp karma again now we can see that we still have the same number of tests running and passing… and we’re now ready to add to that.

Firstly let’s add a test to cover the isAvailable function. We know from the code in ngCordova (and the original plugin) that this returns a JavaScript promise resolving to a boolean value, so let’s write a test for this, bearing in mind that our mock code will always return true. The following is the test for that, and this follows the beforeEach block in our nested describe block that we added above.

We are ready to run our gulp karma again, and this time the result shows and extra test has run, but failed;

But this failure is good right… we haven’t written our code yet.

Add our mock code

For our isAvailable call we know we need to return boolean and in our mock’s case this will always be true. To implement this we add the following into our mock’s return block, so that it looks like this;

If we run our gulp karma again to kick off the tests we should see that our new test is now passing. Grab yourself a glass of your favourite beverage to celebrate.

Using the same TDD(ish) approach we can then add the extra test and code for the print function. In fact a slightly better workflow here is to run gulp karma-watch. This will set a watch running on both our source and test specs and will re-run the unit tests when it spots a change to either.

The finished code for the mock and mock test spec are here

Creating the PR

Now that we’re happy with the mock and test code we are ready to create a PR. The ngCordova project actually requires that the project is built prior to submission. The following step performs the build steps that outputs the concatenated and minified versions of the distributable ngCordova modules, and we need to include these in our PR.

Once this is run we should see that we have, as well as our 2 new files, updated files within the dist directory exist. This can be seen by running a git status command.

Now commit the changes and push to your fork of the project on github. If you now view your new branch on github you should see a “compare and create pull request” button. Click this and (at present) select the dev-next branch as the target.

And that’s it, PR created. And in the ngCordova project’s case a travis job will automatically be kicked off causing the unit tests to be run, and we should see these all pass (including our 2 new ones).

The PR mentioned in this post can be found here.

Please don’t feel that contributing to open source projects is a daunting task, only suitable for ninja, guru, unicorn, blah blah developers… get stuck in and have a go.

Our next PR?

Well perhaps we should raise a documentation PR to add the above steps to the CONTRIBUTING.md on the ngCordova repo?