React on dwmkerr.com

Tips and Tricks for Beautifully Simple Mobile App CI

Mon, 03 Apr 2017 11:14:58 +0000

In this article I’m going to demonstrate some simple tips and tricks which will help you build and maintain beautifully simple mobile build pipelines. These techniques can be applied to different mobile app technologies and integrated into almost any build system:

Each tip is demonstrated in the sample apps in the dwmkerr/beautifully-simple-app-ci repo.

The Challenges of Mobile App CI
Tip 1 - Embrace Makefiles for Consistency
Tip 2 - Control Version Numbers with a ‘Touch’ Command
Tip 3 - Control App Icons with a ‘Label’ Command
Tip 4 - Support Configurable App Ids
Tip 5 - Document, Document, Document
Conclusion

The Challenges of Mobile App CI

Conceptually, a mobile app CI pipeline is pretty simple:

We take our code, perform some kind of validation (such as testing, linting, whatever), generate our artifacts and then deploy them to some devices.

Often though there’s a bit more to it than that:

Our source code has some metadata associated with it at the point in time you create your binaries, such as:

The SHA, which uniquely identifies your exact location in the source history.
The branch, which may have some semantic meaning for your project, for example master meaning ‘production’ or alpha meaning your current unstable public build.
A tag, which may represent something like a semver, or may have more project-specific meaning.
A version, which might be in something like a package.json or embedded in your project files for iOS or Android.

When we build we have to:

Think about how we test and validate
Think about how we sign
Handle package names and bundle ids, which can cause headaches if you are going to install multiple versions of an app (e.g. dev and UAT builds)
Consider build numbers and version number

So even the ‘basic’ CI isn’t all that basic. The rest of this article is a set of tips and techniques which I have found useful when developing mobile apps.

Tip 1 - Embrace Makefiles for Consistency

There are a raft of platform and framework specific tools and interfaces we will have to use in mobile projects. XCode, Gradle, NPM, framework specific CLIs, tools such as Fastlane, etc etc.

If you ensure that your main ’entrypoint’ to key operations is a recipe in a makefile, you can provide a degree of consistency to mobile projects. For example:

make build - Creates an IPA and APK, saving them to the ./artifacts folder.
make test - Runs all test suites.
make deploy - Deploys the binaries.

A makefile for such commands might look like this:

test:
# Run all the tests.
npm test
build:
# Create the apk, copy to artifacts.
cd android && ./gradlew assembleRelease && cd ..
cp -f ./android/app/build/outputs/apk/myapp.apk ./artifacts
# Create the ipa, copy to artifacts.
cd ./ios; fastlane gym --scheme "app" --codesigning_identity "$(CODE_SIGNING_IDENTITY)"; cd ../;
cp -f ./ios/myapp.ipa ./artifacts
deploy:
# Push to TestFairy.
curl https://app.testfairy.com/api/upload \
-F api_key='$(API_KEY)' \
-F "file=@./artifacts/myapp.apk"

This is a slightly shortened snippet, you can see a variety of working examples in the git repo:

github.com/dwmkerr/beautifully-simple-app-ci

The first sample in the above repo demonstrates using makefiles to handle key commands for a React Native app. In the example, CircleCI is used to handle automatic builds on code changes, and the apps themselves are distributed automatically to testers’ devices with TestFairy.

The nice feature is that the bulk of the logic is in the main repo source, in the makefile - the CI tool simply orchestrates it. Developers can run exactly the same commands on their local machine.

The README.md immediately draws attention to the makefile commands:

The makefiles do most of the work, that makes setting up CircleCI almost trivial. Here’s a snippet of its config:

# Tell Circle where we keep our artifacts.
general:
artifacts:
- ./artifacts
# When we test, we build the android app and test it.
test:
override:
- make build-android
- make test
# If there are any changes to the master branch, push a new version
# of the app.
deployment:
master:
branch: [master]
commands:
- make deploy-android

Our commands are android specific at this stage as Circle don’t support iOS builds on their free plan¹. Later samples which use other build systems demonstrate Android and iOS.

The CI automatically tests and builds whenever we have new code commits:

Also, if a commit is made to the master branch, our new app is automatically pushed to TestFairy, which can be configured to automatically update the test team:

Makefile syntax is close enough to shell scripting that simple operations are generally straightforward² to implement. The approach is also perfectly valid for server side code and almost any project.

Teams with many projects can build consistent patterns and syntax for building. Take a look at the image below:

This is from my article on Simple Continuous Integration for Docker Images - where exactly the same principles are applied.

In Summary

Makefiles allow you to provide an entrypoint for common app CI tasks which is framework and toolkit agnostic
Being able to run the individual steps of a CI build on a local machine makes it easier for developers to work with the pipeline
By having a CI platform only need to handle the orchestration of these simple steps, we are less tied to specific platforms and can reduce lock-in

We’ll see more interesting makefile recipes as we get into the other tips.

Tip 2 - Control Version Numbers with a ‘Touch’ command

iOS and Android apps have both a version number and a build number. We might have other files in our project with version numbers too (such as a package.json file).

It can be very useful to have a way of keeping these version numbers in sync. Again, we can use a makefile recipe:

make touch

This command will vary in implementation depending on your platform. For example, this would be all that is needed for a Cordova based project:

# The version in package.json is the 'master' version.
VERSION ?= $(shell cat package.json | jq --raw-output .version)
BUILD_NUM ?= 0
touch:
$(info "Touching to version $(VERSION) and build number $(BUILD_NUM).")
sed -i "" -e 's/android-versionCode=\"[0-9]*\"/android-versionCode=\"$(BUILD_NUM)\"/g' ./config.xml
sed -i "" -e 's/ios-CFBundleVersion=\"[0-9]*\"/ios-CFBundleVersion=\"$(BUILD_NUM)\"/g' ./config.xml
sed -i "" -e 's/version=\"[.0-9a-zA-Z]*\"/version=\"$(VERSION)"/g' ./config.xml

Notice we don’t really need complex tools for a job like this, sed[^3] is sufficient to quickly make changes to config files.

This works very nicely with build systems, many of which provide a build number as an environment variable. For example, we can add a build number with TravisCI like so:

env:
- BUILD_NUM=$TRAVIS_BUILD_NUMBER
script:
- make touch
- make test
- make build-android

To go into more detail, we’ll look at the second sample in the git repo, which is a Cordova App. This sample will always set the build number in both apps and the build version to whatever is present in the package.json file. That means you can do things like this:

$ npm version minor # Bump the version
v0.1.0
$ BUILD_NUM=3 make build && make deploy # Build and deploy the apps
...
done

And all of the version numbers and build numbers are updated and the apps are deployed. In this example project, they’re deployed to HockeyApp:

This build runs on TravisCI, so only builds the Android version. You can clone the code and build the iOS version (and deploy it) using the makefile.

In Summary

There will come a point in your project development where you’ll need to handle version numbers, having a command to explicitly deal with this adds rigour to this process
Build numbers are just as important as version numbers during development, ensuring your CI build number is baked into your artifacts is critical for troubleshooting and control

Tip 3 - Control App Icons with a ‘Label’ Command

When you are working in a larger team, it can be very useful to label your app icon so that team members know exactly what version of the app they are using. This is often the case if you are working in a team where features or bugfixes are being deployed rapidly.

You might label your icons with build numbers, SHAs, branch names, versions, tags, or even something custom such as ‘QA’ or ‘UAT’ for different versions of your app. Here are a few examples:

I’ve found this to be very useful, so created a command-line tool called ‘app-icon’ to help with the task:

github.com/dwmkerr/app-icon

This tool has a label command to add a label, and a generate command to generate icons of all different sizes. This means you can add recipes like this to your makefile:

VERSION ?= $(shell cat package.json | jq --raw-output .version)
BUILD_NUM ?= 0 # This might come from Circle, Travis or Whatever...
label:
$(info Labeling icon with '$(VERSION)' and '$(BUILD_NUM)'...)
app-icon label -i base-icon.png -o icon.png --top $(VERSION) --bottom $(BUILD_NUM)
app-icon generate -i icon.png

Each sample app labels its icon in a different way:

The React Native App puts the short Git SHA on the bottom of the icon.
The Ionic App puts the package.json version at the top of the icon.
The Native App puts an environment label at the top of the icon, and the build number at the bottom.
The Xamarin App includes the configurable app environment (this is detailed in the next tip) and build number

There are references to each sample and the associated code in the README.md at:

github.com/dwmkerr/beautifully-simple-app-ci

As a quick example, the Pure Native App runs this code prior to each build:

BUILD_NUM=BUDDYBUILD_BUILD_NUMBER make label

This app uses BuddyBuild as a build system, meaning we can just drop this line in the buddybuild_postclone.sh script. You can see the labeled icons directly in the BuddyBuild UI:

The Android build is currently having some issues due to fonts being accessible by the labelling tool (which uses ImageMagick under the hood), with any luck this issue will be fixed soon. This seems to be an issue with the BuddyBuild ImageMagick installation rather than the labelling code itself, which is running fine on all of the other builds!

In Summary

A little bit of time invested in managing your app icon can potentially save many hours if you are rapidly iterating on apps
The app-icon tool can help you quickly label and generate icons

Tip 4 - Support Configurable App Ids

Another trick I’ve found useful is to have a command which automatically updates your iOS Bundle ID or Android Application ID. This can be handy when you have multiple versions of an app (such as a QA build, dev build, UAT build or whatever).

If you have users who need to have different versions of your app on their phones then this is actually a necessary step (at least for iOS), as you cannot have multiple versions of an app with the same ID installed.

Often, I will aim to have a standard ‘base id’, such as:

com.dwmkerr.myapp

and then simply append whatever the ‘flavour’ of my app is to the end of the id:

com.dwmkerr.myapp_qa # The QA build...
com.dwmkerr.myapp_uat # The UAT build...

The base id is then reserved for the master build, which is what goes into production.

Just like with all of the other tricks, I tend to use a recipe in the makefile to do the heavy lifting, and then leave the build system to orchestrate the commands (we’ll see more of this later). Here’s how a recipe will typically look (this comes from the fourth sample, which is a Xamarin App):

ENV ?= production
# Set the app id, with the 'production' environment implying the unaltered 'base' id.
ifeq ($(ENV),production)
APP_ID=com.dwmkerr.xamarinapp
else
APP_ID=com.dwmkerr.xamarinapp_$(ENV)
endif
name:
$(info Naming app '$(APP_ID)'...)
sed -i.bak 's/com.dwmkerr.xamarinapp.*</$(APP_ID)</' iOS/Info.plist
sed -i.bak 's/com.dwmkerr.xamarinapp.*\"/$(APP_ID)\"/' Droid/Properties/AndroidManifest.xml

This small recipe can be very useful in combination with other techniques. Ensuring your build respects the ENV variable (or whatever you name your ‘flavour’) means that you can have different configurations for different environments, build multiple versions of the app, each with a distinct app icon, and distribute them to your team.

In the screenshots below, you can see how the presence of the ENV environment variable automatically updates the App ID (this is taken from the Xamarin Sample, which orchestrates builds with Bitrise²:

In Summary

Configurable App Ids allow you to maintain isolated builds of your app for specific environments, even on the same physical device
This tip must be used with caution, some features (such as iOS push notifications) will not work if the bundle id is changed (it can also cause issues if your provisioning profile does not use a wildcard)

Tip 5 - Document, Document, Document

Even teams which are great at documenting complex application code can sometimes be a bit lax when it comes to documenting build related code.

Unfortunately, build related code will often need more documentation than usual. Why is this?

It is often complex (spend any time working with the XCode commandline or provisioning profiles and you’ll likely agree)
It is rarely changed (often worked on heavily at the early stages of a project then not touched)
It is critical (when it breaks, teams are often blocked)

When something goes wrong with a build process, or needs to be changed, it is a real pain when only one person knows how the code works. Be rigorous with this code, make sure it is documented and reviewed, and share the knowledge around your team. I tend to like to have a table of commands as a quick index in the README.md file, and then heavily comment the code itself:

In Summary

Be rigorous with documentation, when things go wrong with CI code then people are often blocked

Conclusion

Most of these tips are fairly explicit, there are detailed examples in the sample project. Familiarity with these patterns and techniques can be useful, but perhaps the most valuable takeaway would be to embrace the following principles:

Developers should be able to run all of the key CI steps on their local machine, to be able to understand, adapt and improve the process
When building more complex features, we should create small, simple units of work which can be composed into larger pipelines
Complexity, if needed, should be in in code - not in ‘black box’ CI tools (such as esoteric features for specific CI providers or Jenkins plugins). For example, CircleCI offers a Git Short SHA environment variable - but you can grab a short SHA with git log -1 --format="%h", and the second approach works anywhere
Use CI platforms to orchestrate work, use makefiles and scripts to handle logic

I hope this article has been useful, any thoughts or comments are always welcome!

Footnotes

I have successfully used this approach to build Android and iOS from the same OSX build agent on their paid plan on a number of projects. The most straightforward way to do this is to have a single build run on OSX and create the Android app as well as the iOS app. ↩︎
Perhaps straightforward is an overstatement, but getting those who are familiar with shell scripting will have few difficulties. Those who are not will find a learning curve, but it is very useful to at least get the basics of shell scripting learnt. ↩︎ ↩︎

Moving from React + Redux to Angular 2

Mon, 25 Apr 2016 09:45:00 +0000

I’ve just finished working on a very large project written in React and Redux. The whole team were new to both and we loved them.

I’m going to share my experiences of experimenting in Angular 2 with you, from the point of view of someone who needs a pretty compelling reason to move away from my JSX and reducers.

The Journey So Far

Let me highlight a few key moments in my UI development experiences, to give a bit of context to my ramblings.

Reading about redux was a lightbulb moment for me - rather than a complex framework it’s a simply library to help apply a few common sense functional programming principles - state is immutable, functions apply predictable transformations to data to produce new data.

Learning React took a little bit of getting used to, but not too much, it was quite a bit more simple than Angular anyway.

Long story short, simple React components and rigorous state management has so far resulted in the most manageable and well written very large scale UIs I’ve worked on so far - can Angular 2 compete with this?

First Step with Angular 2 - Folder Structure, Typescript, Sublime Text

I checked out the pretty neat ‘Getting Started’ guide from Angular which promised to get me started in five minutes.

It didn’t take five minutes, there’s a few gotchas, so I’m going to give a condensed guide here.

Step 1: The Folder Structure

The first few steps of the angular guide creates the following folder structure:

|-- angular2-starter
|-- tsconfig.json
|-- typings.json
|-- package.json

This is the standard package.json with some scripts ready to go. We also have tsconfig.json to configure the typescript compiler and typings.json to provide info to the compiler on where to get type information.

You can check the code at this stage here:

https://github.com/dwmkerr/angular2-starter/tree/step1

Node & NPM Issues

At this stage the quickstart says you can run npm install and all will be well:

npm ERR! cb() never called!

Not so good! For the record I’m using NPM 3.7.3 installed via homebrew. This looks like a bug in Beta 15 (see Issue #8053).

I fixed this by using n to upgrade my node version:

$ node -v
v5.9.0
$ npm install -g n # install 'n' node version manager
$ sudo n latest
installed : v5.11.0
$ node -v
v5.11.0

Now it npm install runs OK.

Step 2: Adding Components and Configuring Sublime

The next steps of the walkthrough take us through adding an app component, a main.ts file to bootstrap the application and an index file. You can check the updates here:

https://github.com/dwmkerr/angular2-starter/tree/step2

Essentially we now have:

|-- angular2-starter
|-- tsconfig.json
|-- typings.json
|-- package.json
|-- index.html
|-- styles.css
|-- app
|-- main.ts
|-- app.component.ts

At this stage, running npm start gives us a browerserified app to play with:

Clear enough so far, although the code in Sublime is not looking so pretty:

Quickly installing the TypeScript plugin from Microsoft[^n] seems to do the trick:

If you need more details, here’s a gist with the full setup for Sublime 3, assuming you’ve got nothing installed.

https://gist.github.com/dwmkerr/04fa8b8c15d049d0381e7798a79bcc45

At this stage the app will run, we can see the basics of the Angular 2 syntax and start experimenting.

Step 3: Adding some components

At this stage the quick started guide starts going into more detail, guiding you through the process of creating multiple components. I decided to go off on my own here, with the rough plan of being able to write a set of goals for the day and turn it into a check-list[^n].

Within not much time I had the some basic components, input and output, bindings and so on. Some screenshots:

You can take a look at the code at this stage by checking out the ‘step3’ branch:

github.com/dwmkerr/angular2-starter/tree/step3

Thoughts so far

For now, that’s all I’ve got time for. I’ve had a chance to get a feel for Angular 2, I’m going to come back to this in a few weeks and integrate Redux, maybe swap out System.JS for Webpack and do some experimenting.

Opinions[^n] so far?

Not Sold on TypeScript

I’ve used TypeScript in my mess around, rather than plain ‘ol JavaScript, to keep the experience authentic to the angular team’s goals of using TypeScript to help.

So far, I’m not seeing an enormous benefit. Some of the extra information available to auto-completion in nice, but this is a tooling thing.

JavaScript is not a static language, the TypeScript annotations I find slowing me down a little.

There’s so much extra domain specific stuff in Angular 2 that people might be lost without it. But if your stuff is so complex you need to adapt the base language, is it too complex?

Explicit Component Surface Areas are a Nice Idea

When defining a component, you specify explicitly what comes in (data) and what goes out (events).

This means that the surface area of a component (i.e. the part you touch if you interact with it programmatically) is well defined. This is a good thing.

However, this is all handled with some pretty framework-specific stuff[^n]:

// e.g.
export class GoalsBoxComponent {
 // Event we fire when the goals change.
 @Output() goalsChanged: EventEmitter<Goal[]> = new EventEmitter();
}

// e.g.
export class GoalListComponent {
 // Input is a set of goals to render.
 @Input() goals: Goal[] = [];
}

In a nutshell…

Explicit component surface area is a cool idea.

React does this too with the optional propTypes, but it is not enforced. However, how this is done in Angular has already gone through a few radical changes with some lively debate.

Not ready for production… yet

There’s no standardised, documented way to test a component - nuff said. But things are evolving quickly.

Framework Fatigue

Comparing React to Angular is unfair, one is a view library, one is a framework. But it’s worth pointing out this is a pretty complex framework. There’s a lot of very domain specific stuff. See this documentation for an example:

<li *ngFor="#hero of heroes">

From the documentation:

The (*) prefix to ngFor indicates that the <li> element and its children constitute a master template.

…

The # prefix before “hero” identifies the hero as a local template variable. We can reference this variable within the template to access a hero’s properties.

You’ll get used to it (if you have to), but I think it’s harder to reason about than:

render () {
 return (
 <div>
 {this.props.goals.map((goal) => {
 return <li>{goal.title}</li>;
 }</div>);
}

OK fair enough, JSX is very specific, but the logic (mapping an iterable) is JavaScript.

Wrapping Up

That’s it, for now. Next steps are to experiment more, see if it will play nice with Redux and share the next set of opinions.

I’d love to hear what you think, so drop your comments below!

Footnotes

Getting Started with React & ES6

Mon, 07 Sep 2015 19:44:54 +0000

Feeling like having a go with Facebook’s hugely popular React framework but not sure where to start?

In this post I’m going to build a simple React application from scratch - using ECMAScript 6.

We’ll put together the bare minimum skeleton of a site and keep the folder structure free of noise and clutter so that you can focus on the app code and not the tooling!

The simple app we’ll build is at github.com/dwmkerr/react-es6-starter, or see it live.

Building the Code

Our goal will be to have a single index.html file which includes our Javascript files. We’re aiming for something like this:

But browsers don’t handle ES6 yet. So our loose files, which reference each other, are going to have to be transpiled into ES5 and bundled into a single file. We need a build process:

Webpack can handle all of this for us. Given an entrypoint file, webpack will traverse all of the require and import statements and build a single bundle file. It also allows us to configure ’loaders’, which let us pass these files through other tools:

We’ll need the following libraries:

Webpack - the tool that handles the build process.
Babel - an excellent ES6/ES7/JSX to ES5 transpiler.
Babel Loader - the component which integrates Babel into our Webpack build.
Html Webpack Plugin - a simple Webpack plugin which will copy our index file to our build folder and add a link to our Webpack bundle.

Let’s install these modules:

npm install --save webpack babel babel-loader html-webpack-plugin

We’ll also need a webpack config file. By default webpack expects a file named webpack.config.js to be in the root of the project. But every tool under the sun wants to stick its config file in the root of our project, and most of the time they’re just in the way.

So let’s put everything to do with our tooling in a tooling folder instead. Create the file webpack.config.js in a tooling folder in the root of the project:

var path = require('path');

module.exports = {

 // Defines the entrypoint of our application.
 entry: path.resolve(__dirname, '../src/app.js'),

 // Bundle to a ./build/public/bundle.js file.
 output: {
 path: path.resolve(__dirname, '../build/public'),
 filename: 'bundle.js'
 },

 // Use babel for anything that is *.js or *.jsx.
 module: {
 loaders: [
 {
 test: /\.jsx?$/,
 loader: 'babel-loader',
 include: path.resolve(__dirname, '../src')
 }
 ]
 }
};

First we define our entry point - the first file which will actually be run if we run the final bundled script. This is the app.js file we’ll create shortly. If app.js includes other modules, Webpack will pick them up, if those modules include other modules, they will be picked up and so on.

Next we specify that everything should be bundled into a ./build/public/bundle.js file (we’re going to use the convention that everything we can produce with our tools goes into ./build).

Finally, we specify that every file in src which matches the \.jsx?$ regex will go through the babel loader.

Using ES6!

We’ve actually got enough now to use ES6. Create a file in src called index.html:

<!DOCTYPE html>
<html>
<body>
</body>
</html>

Then create a src/app.js file:

const PI = 3.14;
let vals = [1, 2, 3].map(x => x*2);
document.body.innerText = "Pi is " + 3.14 + " and vals is " + vals;

Run the command ./node_modules/.bin/webpack --config ./tooling/webpack.config.js and our code is built, transpiled an moved to the build folder.

Now we could serve this folder using any basic webserver. We are already using webpack, so the webpack dev server will do the trick. It uses exactly the same config file as the webpack tool:

npm install --save-dev webpack-dev-server
./node_modules/.bin/webpack-dev-server --config ./tooling/webpack.config --inline

The inline reloads the page when the source changes. We don’t need to tell the server where the files are, it knows that from the webpack config.

Let’s stick these commands in our package.json for convenience:

{
 ...
"scripts": {
 "start": "webpack-dev-server --config ./tooling/webpack.config.js --inline --quiet",
 "webpack": "webpack --config tooling/webpack.config.js"
 ...
}

Now we can manually build with npm run webpack and start our dev server with npm start.

Adding some React

Let’s add a React component. Create a folder under app called home and add a home.js file:

import React from 'react';

export default class Home extends React.Component {
 render () {
 return <div>
 <h1>React ES6 Starter</h1>
 <p>Welcome to the React ES6 Starter home page!</p>
 </div>;
 }
}

This is our first react component, which does nothing more than render some basic markup. We’ll use this as the starting point for our application.

We can now take our app.js file and render our Home component into the div. Here’s app.js:

import React from 'react/addons';
import Home from './home/home';

React.render(<Home />, document.body);

That’s all there is to it! We’ve got a clean and simple starting point to begin playing with React. Before we look into things like state management and routing, let’s look into testing what we have so far.

Testing

Even the most simple app would be incomplete without looking into how we will deal with the testing.

Many will recommend the Jest framework to test React applications. However, it’s a bit more to learn and has some problems with NodeJS v0.12, so until we get Node v4 I’m going to keep things simple.

First, we’ll install Karma as a test runner. We’ll use Jasmine as as framework to write test cases and PhantomJS as a headless browser in which our tests will run. This means we’ll need to add some more dev dependencies:

npm install --save-dev karma jasmine karma-webpack karma-jasmine karma-phantomjs-launcher

We can now create a karma.config.js file in our tooling folder:

var path = require('path');

module.exports = function(config) {
 config.set({
 browsers: ['PhantomJS'],
 files: [
 // We need to polyfill as PhantomJS doesn't support 'bind'.
 '../node_modules/babel-core/browser-polyfill.js',
 '../**/*.spec.js'
 ],
 frameworks: ['jasmine'],
 preprocessors: {
 '../**/*.spec.js': ['webpack'],
 },
 reporters: ['progress'],
 singleRun: true,
 webpack: {
 module: {
 loaders: [
 {
 test: /\.jsx?$/,
 loader: 'babel-loader',
 include: path.resolve(__dirname, '../src')
 }
 ],
 }
 },
 webpackServer: {
 noInfo: true
 }
 });
};

So here we are:

Loading a polyfill from babel core (sorry guys, one more npm install --save-dev babel-core) which gives PhantomJS the bind function (along with some others). This is needed as some of the testing code in the browser needs these features.
Specifying that anything that ends in .spec.js should be loaded.
Running anything that ends in .spec.js through webpack.
Telling webpack to use babel.

Quite a bit of config, but we’re re-using the same webpack tooling as before. We run the code through webpack, which sends it through babel and builds ES5 we can test in the browser.

With this in place, we can write a spec. Add home.spec.js to the home folder:

import React from 'react';
import $ from 'jquery';
import Home from './home.js';

describe('Home', () => {

 it('should render to the DOM', function() {

 // Create the <Home /> react component.
 var component = React.render(<Home />, document.body);

 // Find the DOM element for the created component.
 var node = React.findDOMNode(component);

 // Check the DOM looks how we'd expect it to.
 expect($(node).children('h1').text()).toEqual("React Redux Starter");

 });

});

What’s going on here? We just ask React to render our Home component directly into the DOM. We get a component back from this call. We can then ask React to give us the DOM associatefd with the component and use familiar tools (jQuery!) to test the shape of the generated DOM.

All that’s missing is the last of the dev dependencies we’ve missed:

npm install --save-dev jquery phantomjs

We can run tests directly on a Mac or Unix with:

./node_modules/.bin/karma start ./tooling/karma.config.js

For Windows use:

node_modules\.bin\karma start tooling\karma.config.js

In fact, we’ll update our package.json scripts so that this is the test command:

"scripts": {
 "test": "./node_modules/.bin/karma start ./tooling/karma.config.js",
 ...

Done! This means we can run tests on any platform with NodeJS¹ using the same command - npm test.

We now have a very simple setup which allows us to run tests. You can build on this - perhaps adding Jest later or a more sophisticated or React specific set of tools.

Adding Code Coverage

You might want to add some code coverage information to your project. This can be a little tricky when using ES6, as we need to make sure we report coverage of the original ES6 code, rather than the actual transpiled code which is instrumented.

Fortunately, with the clean and simple setup we have built, adding code coverage is a snap.

Our test runner, Karma, is built to quickly integrate with the code coverage tool Istanbul, we just need to use the Karma Coverage plugin. Let’s install the two modules:

npm install --save-dev istanbul karma-coverage

Now with a small addition to our karma.config.js file we will get a nice HTML coverage report. We need to update our reporters config to include coverage and specify coverage options in the coverageReporter config.

 reporters: ['progress', 'coverage'],
 coverageReporter: {
 dir: '../build/coverage/',
 type: 'html'
 }

If you run npm test now, you’ll get an HTML coverage report generated. The only problem is that it is for the transpiled code, which makes it almost useless. A customer instrumenter called isparta will help us here. We use isparta to get a report of the coverage of the original ES6 code. Two more modules:

npm install --save-dev isparta isparta-instrumenter-loader

Then in our karma config we pass the orignal code through the insrtrumenter, before babel transpiles it:

webpack: {
 module: {
 preLoaders: [
 {
 test: /\.jsx?$/,
 exclude: [/node_modules/, /\.spec\.js/],
 loader: 'isparta-instrumenter-loader'
 },
 ],
 // everything else stays the same...

Anything that is not a spec or from node_modules gets instrumented. Now we have a ES6 code coverage report:

With this in place, you can go even further and integrate with other CI or publish to code quality systems (for example this repo integrates to coveralls.io). This is often used to show badges for repos:

Another use case is to gate checkins unless they maintain a certain code coverage threshhold.

Wrapping Up

This provides a very lean starting point for learning React. There’s no moving parts at the moment - no state management. We’ll get into that in later articles but right now you have a playground.

You can set up CI in a flash, just sign up for a Travis account and use a travis.yml like this:

language: node_js
node_js:
 - "0.12"

This repo is all ready to push to Heroku, no Procfile is needed. Check out react-es6-starter.herokuapp.com to see the code in action.

I hope you’ve found this article useful! Next time we’ll be getting into the details of managing state in React.

Please fork the repo and have a play, let me know of any suggestions or improvements!

github.com/dwmkerr/react-es6-starter

Glossary of Conventions

There are a few conventions that I personally use in most Javascript projects. The conventions used in this article which I think are valuable to consider using in many projects are:

Always support install/test/start

Everyone should always be able to checkout, install, test and run the code with the following commands:

npm install # installs everything needed
npm test # lets the user know the code works right on their system!
npm start # starts the code, lets the user know what to do next

Install should setup everything, and if code needs to be built to be testable, this should be a post-install hook.

Test should be run next, as a user should be able to verify that the code works as expected on their system.

Finally, when the user runs start, a dev server (as convention dictates we are in a dev mode by default (and production mode is set with a flag or environment variable) the server should start and a console message should show the user where to browse to.

Footnotes

IBM Mainframes anyone? ↩︎