cantest: avoid regression in HTML5 canvas rendering code
In a project we are working on we have quite a lot of code that eventually draws on an HTML5 canvas. Since we work in a team and have multiple layers of code involved in generating the final result, there’s always a chance for regression (like in any other codebase).
This is applicable to any codebase that generates visual elements on an HTML5
As an initial step, we needed a very basic tool that can simply run a canvas drawing function and compare the result to a predefined expectation PNG. This way, we can create a set of tests that protect us against regressions. In the future we might extend this tool to support testing regression of dynamic scenes as well.
node-cantest is a simple library/tool that runs test functions (exported by a node.js module) and compares the rendered result to a pre-existing expectation PNG file. If the results differ, it optionally pops up a browser window with the two PNGs.
Let’s run through a simple example.
Create a drawing function
Create a directory for our hello world example:
$ mkdir hello-cantest $ cd hello-cantest
Create a test
First, install node-canvas so that the test can create a
$ npm install canvas
Now, let’s create the test
Run for the first time to generate output
First, install node-cantest globally (might require
$ npm install -g cantest
Now, run it:
$ cantest hello-test.js [hello-test.js] hello-test.png created
This test basically failed (returned exit code
1). It failed because it could not find
hello-test.png which is the default name for an expectation file. Since this is a common use case, cantest simply created this file for you.
Let’s verify that the result is what we wanted. Open
hello-test.png and it should look like this:
This looks exactly like we expected, so I’m feeling okay keeping it as the expectation file. In case this is not what you wanted, this is where you iterate on your rendering code and make it look awesome.
If we run cantest again, the test will succeed:
$ cantest hello-test.js --verbose [hello-test.js] Test passed
So our project now consists of the following files:
hello.js- That’s our rendering function. All it does is export a
function(ctx)which, when called, draws those nasty looking rectangles on the canvas. You can use onejs or node-browserify to bundle CommonJS modules for client side consumption so exporting a function for client use makes a lot of sense for us.
hello-test.js- That’s the test. Basically, it calls the rendering function, passing in a node-canvas
hello-test.png- That’s the expectation file. It was conveniently generated by node-cantest and should be kept alongside
hello-test.jsso that cantest can compare the rendering result to it.
The next step will be to make some change in our
hello.js function and rerun the test to make sure we didn’t break anything:
…and run cantest:
$ cantest hello-test.js [hello-test.js] Test failed. See actual output in .actual.hello-test.png
Your browser window should pop up and show something like this (
--no-browse will disable this behavior):
Oh, yeah… Now we can see that the inner blue rectangle changed it’s height. Obviously this is a stupid example, but you get the point. In more complex rendering systems, there are multiple layers of rendering and if something changes in lower layers you would want to know if it has any affect on higher layers.
At this point we could:
- Decide that this is a good output and overwrite our expectation file by overwriting
.actual.hello-test.png(this file is created by node-cantest and not deleted in case the test fails).
- Figure out that we found a bug and fix it by editing
Static only for now
In this initial version node-cantest is good only for static rendering. It’s good enough for us for now, but we do understand that we might need to provide some support for changing scenes. This is basically just recording the rendered results and storing it as expectation.
Fonts on multiple platforms
If you run the tests on multiple platforms (e.g. locally on your Mac and in a build server like travis-ci, you should be aware that text is rendered differently on different platforms. There’s a different variety of fonts and the results are not always the same.
This essentially might cause your tests to break because the resulting PNG will be different from the expectation PNG. To work around this, use common fonts that exist on most platforms (or make sure you are using a single platform to run your tests).
See the cantest README file for more details on the command line interface and the library API.
cantest is open source under the MIT license. Contributions/issues/pull requests/feedback/remarks are very welcome and appreciated.
Elad Ben-Israel @emeshbi
Your Own Little node.js PaaS - Part 1
PaaS (platform-as-a-service) services are blooming these days (Heroku, Nodejitsu, nodester, cloudcontrol and many more). All offer some awesome features. I set out to try and set up a very simple node.js PaaS for myself within an Amazon EC2 Ubuntu instance. It obviously lacks many of the features in commercial PaaS services but it’s a lot of fun and also gives you complete control over the runtime environment. For me, I needed some non-node Linux services running alongside my app (e.g. SMTP, squid, sshd).
This post will walk through:
- Creating a simple “hello world” repository and pushing it into github.
- Launching an EC2 instance and deploying this repository on it.
- Setting up a github post-receive hook to automatically redeploy the
#masterbranch whenever changes are committed.
In a future post I will use connect-girror to host multiple apps on a single EC2 instance.
Creating the root repository
The first step is to create a git repository that will serve as the root of your PaaS:
Create a new github repository.
Clone this repo to your local box:
Create an initial
This is the canonical node.js “Hello, world”. Notice that the port we are listening to is defined in
process.env.port. This will be set later in the Ubuntu upstart script that keeps this app alive on the production server. Port 5000 is used as fallback for the development environment.
Now commit the changes and push them into github:
Launch an Amazon EC2 instance
The next step is to launch an Amazon EC2 instance. I’m using Ubuntu here but you could use any other *nix machine. Details will vary, especially around setup and the init scripts (upstart in Ubuntu).
A list of available stock Ubuntu instances is available here. I have been successfully using a 64-bit ebs-backed instance. Note that an non-ebs root store might not have enough space for the stuff we need on this box.
When launching your instance, paste the gist below in the
userdata field of the instance, altering the
REPO variable to point to your newly created github repository.
In case this is a private repository, you can use the
https://USER:PASSWORD@github.com/account/repo scheme, or install a github private key on your server and use the github ssh endpoint (firstname.lastname@example.org/account/repo.git).
This script basically does the following:
- Installs nodejs, npm, git, gnu make and gcc compiler for c++. The latter two are required for compiling native modules in case you will use any.
- Installs girror, which is a node.js module/utility I created that facilitates in syncing clean mirrors of git repositories to a local directory.
/etc/init/paas.confwhich is an Ubuntu upstart script invoked during system initialization. When
start paasis called (or the system is initialized), this script will fetch any changes from the app’s git repository, call
npm install(in case there’s a
package.jsonfile in the app’s working directory and then start
node app.jsfrom the app’s directory (setting
- Starts the
paasservice we just created.
In the firewall settings, open up at least port 22 (SSH) and port 80 (HTTP).
After you hit Launch, EC2 will spin up the new instance for you and will run the userdata script you specified. Note that the initial boot might take a few minutes (about 5) since we are installing a few things.
If everything goes well (see the System Log in the AWS console for debugging), at this point your app should be running and you should be able to hit it via HTTP (replace with your own Amazon instance DNS):
How cool is this man?
Tailing logs from your server
Logs are appended into
/var/log/paas.log, so tailing them should be quite easy:
I like to keep an open iTerm frame with this command running at all times so I can see what’s up with my apps.
Set up a GitHub hook
The next step is to add a hook handler to our app and set up a github post-commit hook which will send an HTTP POST to your instance whenever changes are committed into the master branch.
app.js and add the following code:
The mechanism for handling post-commit triggers is simply to exit the app using
process.exit(1). This will trigger a
respawn by the upstart script which will call
girror $REPO $WORKDIR which will fetch any changes from
$REPO. This is very preliminary and not very sophisticated but actually works… One thing you would need for a more advanced workflow is only respond to changes within the
#master branch (or any other branch that you wish deployed). This way, you could control exactly which changes affect your production environment.
Security notice: since the root app contains the super secret deployment endpoint, you should probably make it a private repository and not public.
Commit and push the changes to github:
Now, you will need to redeploy your app manually by invoking upstart’s
restart command. You can do this remotely using ssh:
In the logs, you should see something like this:
Starting app from https://github.com/eladb/mylittlepaas 16:26:27 - TRACE - done My little PaaS (v2) started on port 80
Did you notice
The next step is to setup a github post receive hook.
In your repository’s administration page, under Service Hooks (!https://github.com/account/repo/admin/hooks), add a WebHook URL that points to your secret deployment endpoint. In our case it is http://ec2xxx.compute.amazonaws.com/mysupersecretdeploymentendpoint:
Click Update Settings and then Test Hook while monitoring your tailed logs. You should see deployment activity going:
Post-receive trigger. Exiting in 1 second Starting app from https://github.com/eladb/mylittlepaas 16:53:14 - TRACE - done My little PaaS (v2) started on port 80
Now we are getting somewhere…
GET /, you will see the new version deployed:
Installing npm packages
paas.conf upstart script executes
npm install before starting your app. This means that any npm packages you specify under the
dependencies field of your app’s
package.json file will be installed automatically before the app starts. One disadvantage of this approach is that sometimes modules use wildcard semver versioning when specifying dependencies, which can potentially cause app breakage if some module misbehaved and did not adhere to npm’s versioning guidelines. npm provides a mechanism called shrinkwrapping which allows you to fix the versions of all the modules and submodules you are using. This is the best practice for bundling app dependencies.
Another approach is to commit all dependent modules directly into your repository’s
node_modules directory. This will work only if you are not using modules with native parts which must be compiled on the target architecture.
Let’s install the asciimo module and emit some ascii art.
Edit your app’s
package.json and add
email@example.com under the
Now, install and shrinkwrap:
Commit and push:
Code should be now be deployed automatically (and npm installed), so
GET / should yield:
So, at this point we have:
- A running ec2 instance hosting the node.js app under a github hosted repository.
- Any changes to the master branch of this repository will be automatically fetched and the app will be restarted.
- Logs can be tailed via ssh using
tail -f /var/log/paas.log
In the next post I will extend this app to host apps from multiple repositories using connect-girror.
Any comments/feedback/ideas/contributions/flaming are very welcome!
Setting up a squid proxy on AWS
1. Launch a micro Ubuntu EC2 instance
If you don’t have an Amazon AWS account, you can sign up for one here.
2. SSH into your new instance and install squid
$ sudo apt-get update $ sudo apt-get install squid3
3. Update squid configuration
/etc/squid3/squid.conf as root:
$ sudo nano /etc/squid3/squid.conf acl all src all acl SSL_ports port 443 acl CONNECT method CONNECT http_access allow all http_port 3128 hierarchy_stoplist cgi-bin ? coredump_dir /var/spool/squid3
Please note that this configuration is not very secure. See squid configuration wiki for more information.
Restart squid for configuration to be reloaded:
$ sudo restart squid
4. Add inbound port 3128 to the instance security group
Instances are usually launched on the default security group (unless you specify otherwise).
- Access the security groups section in the EC2 console
- Add a custom TCP inbound rule for port 3128 and apply the change.
5. Configure your browser to use the proxy server
Depending on your OS/browser, you should configure the system to access the Internet via the proxy for both HTTP and HTTPS (e.g. ec1-11-11-11-11.compute-2.amazonaws.com:3128).