Jump-starting Slack bot projects: bot-zero

At Wehkamp we believe in enabling teams to automate their work. Lately we’ve been experimenting with GitHub’s Hubot project to build chat-bots for Slack. It has been quite a ride! What did we build? A lot! Bots took control of our job engine and our $universe scheduling. We can view Grafana dashboards and PagerDuty schedules or create incident channels right from our Slack channels. And this is only the beginning…

Note from 2022

Hubot continues to be used at Wehkamp, but it is no longer the first framework of choice. Slack has evolved a lot, so it makes more sense to use the Bolt framework. We continue to update our bot-zero repo as long as we use it. The latest version is rewritten in Typescript (so we had to change the links in this article). I'll keep this article up as a reference.

Jump start

To give teams a jump start we’ve created the bot-zero open source project. It solves some setup and development problems. In this blog I’ll show how to get up and running in minutes and I’ll explain some choices we’ve made.

You can setup your own bot by running the Slack Developer Kit for Hubot.
Bot-zero is a de-cluttered version with some extras.

First time setup

Setup is easy. Hubot is written in Node.js, so make sure it is installed on your system. You also need an editor to code scripts. I use Visual Studio Code (the bot has been setup to do debugging with this IDE, but any IDE will work). If you have an editor and Node.js installed, do the following steps:

Fork the bot-zero project.
Clone your forked project to your pc.
Goto http://slackapi.github.io/hubot-slack/#getting-a-slack-token to read up on how to get a Slack token for your bot.
Add the token to your .env file
Open a terminal and navigate to your bot directory.
Enter npm install to install the NodeJs packages.
Start the bot using npm start.

Easy. Peasy.

The root of the project after running the NPM install.

Improving local development

We’ve added some features to make local development easier. The first improvement is the .env configuration file. Many Hubot packages require you to add environment variables to configure settings. In previous versions we ran into the problem of configuring them on different systems (Mac, Linux and Windows). That's why we added the .env file. The project will load the settings automatically when you start your bot. Note: you should not commit the file to GitHub as it contains your personal settings.

Writing is usually not the problem,
*maintenance* is.

Don’t like to use regular expressions to make Hubot listen? We’ve got you covered! We’ve added the Hubot Command Mapper so you can map commands using and API instead of those dreaded regexes. It also helps in speeding up the development of your scripts by providing a reload command, so you don’t have to restart the bot.

The project also enforces a JavaScript standard. As many people collaborate on bots, we believe it is great if there is some sort of automatic standard check. As most coding standards are pretty arbitrary, so is this one: JavaScript Standard. It will try to auto fix violations, but it can't do everything. A validation is triggered upon test, commit and push. You can validate your code by running npm run validate.

Developing new scripts is as easy as adding a new script to the /scripts/ directory.

Removed coffee examples, added ES6 examples

We love coffee… the drink that is! The default Slack bot installation comes with many (not so useful) coffee-script examples. We’ve removed all of them and added 3 JavaScript/ES6 examples. The bot will still load all .coffee and .js files it finds in the scripts directory.

Brian Donovan started the Decaffeinate Project
to turn .coffee files to ES6 JavaScript.

The first example is the ToDo list (scripts/todo.js) – it shows how to use the Hubot Command Mapper with parameters.

The second is the Norris example (scripts/norris.ts) – it shows how to use node-fetch for web service requests. It returns an ES6 Promise, making asynchronous operations easier. We think fetch provides a better API than the Hubot HTTP client, especially because the Hubot client is optimized for coffee-script.

The third example script is a progress message (scripts/progress.ts) - it leverages the Slack API to update a single message. It turns your Slack message into a powerful progress indicator. For more information, check Building an updatable Slack message.

Building a progress indicator is easier than you think. Just update the message through the Slack API. The effect is pretty neat.

Testing

So how about testing your scripts? We’ve stumbled upon the Hubot Pretend package that solves this problem. It will emulate Hubot and use an ES6 Promise to interact with the results. We use a combination of Mocka and Chai to do the actual testing. To make things easier to understand and implement we’ve added tests for the example scripts to the /tests/ directory.

~~One advantage of doing using Test Driven Development is that you have a shorter cycle – you don't have to start the Hubot and manually query it through Slack.~~

We've removed the testing feature from the latest version of the bot. Unit testing is very valuable, but as the bot contains many integrations, it is not feasible to use unit testing for this.