hackingonstuff

cantest: avoid regression in HTML5 canvas rendering code

Wed, 04 Jul 2012 12:46:00 +0300

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 <canvas>.

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 hello.js:

https://gist.github.com/3046190

Create a test

First, install node-canvas so that the test can create a CanvasRenderingContext2D:

$ npm install canvas

Note that node-canvas uses Cairo for rendering, so see any notes under the node-canvas github page for details on installing it on various platforms.

Now, let’s create the test hello-test.js:

https://gist.github.com/3046222

Run for the first time to generate output

First, install node-cantest globally (might require sudo):

$ 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 CanvasRenderingContext2D context.
hello-test.png - That’s the expectation file. It was conveniently generated by node-cantest and should be kept alongside hello-test.js so 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:

https://gist.github.com/3046303

…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 hello-test.png with .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 hello.js.

Some caveats

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).

Follow up

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

Sun, 24 Jun 2012 01:33:00 +0300

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 #master branch whenever changes are committed.

In a future post I will use connect-girror to host multiple apps on a single EC2 instance.

Some background:

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:

https://gist.github.com/2979066

Create an initial app.js and package.json:

https://gist.github.com/2978873

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:

https://gist.github.com/2979049

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.

https://gist.github.com/2980597

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 (git@github.com/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.
Creates /etc/init/paas.conf which is an Ubuntu upstart script invoked during system initialization. When start paas is 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.json file in the app’s working directory and then start node app.js from the app’s directory (setting port to 80).
Starts the paas service 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):

https://gist.github.com/2979054

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:

https://gist.github.com/2979056

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.

Edit your app.js and add the following code:

https://gist.github.com/2978879

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:

https://gist.github.com/2979574

Now, you will need to redeploy your app manually by invoking upstart’s restart command. You can do this remotely using ssh:

https://gist.github.com/2979059

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 v2? Yeah!!

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…

If you GET /, you will see the new version deployed:

https://gist.github.com/2979060

Installing npm packages

The 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 asciimo@0.3.1 under the dependencies field:

https://gist.github.com/2979605

Now, install and shrinkwrap:

https://gist.github.com/2980212

Edit app.js:

https://gist.github.com/2980218

Commit and push:

https://gist.github.com/2980228

Code should be now be deployed automatically (and npm installed), so GET / should yield:

https://gist.github.com/2980244

Recap

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

Mon, 28 May 2012 17:42:00 +0300

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

Edit /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).