Testing with npm

This article shows how to get three.js into a node.js environment so that you can execute automated tests. Tests can be run on the command line, or by automated CI tools like Travis.

The short version

If you're comfortable with node and npm,

1. $ npm install three --save-dev, and
2. Add var THREE = require('three'); to your test.

Create a testable project from scratch

If you're not familiar with these tools, here's a quick guide.

Basic setup

1. Install npm and nodejs. The shortest path typically looks something like

   $ sudo apt-get install -y npm nodejs-legacy
   # fix any problems with SSL in the default registry URL
   $ npm config set registry http://registry.npmjs.org/
   

2. Make a new project directory, $ mkdir test-example; cd test-example

3. Ask npm to create a new project file for you: $ npm init and accept all defaults by hitting Enter on all the prompts. This will create package.json.

4. Try and start the test feature with $ npm test. This will fail, which is expected. If you look in the package.json, the definition of the test script is "test": "echo \"Error: no test specified\" && exit 1"

Add mocha

We're going to use mocha.

1. Install mocha with $ npm install mocha --save-dev. Notice that node_modules/ is created and your dependencies appear in there. Also notice that your package.json has been updated: the property devDependencies is added and updated by the use of --save-dev.

2. Edit package.json to use mocha for testing. When test is invoked, we just want to run mocha and specify a verbose reporter. By default this will run anything in test/.

   "test": "mocha --reporter list"
   

3. Rerun the test with $ npm test. This should now succeed, reporting 0 passing (1ms) or similar.

Add three.js

1. Let's pull in our three.js dependency with $ npm install three --save-dev

2. If you need a different three version, use $ npm show three versions to see what's available. To tell npm the right one, use $ npm install three@0.55.0 --save-dev (0.55.0 in this example).

3. I'm assuming three is a dev dependency here. Use --save if not. More docs on this here.

4. Mocha will look for tests in test/, so let's $ mkdir test.

5. Finally we actually need a JS test to run. Let's add a simple test that will verify that the THREE object is available and working. Create test/verify-three.js containing:

   var THREE = require('three');
   var assert = require("assert");
   
   describe('The THREE object', function() {
     it('should have a defined BasicShadowMap constant', function() {
       assert.notEqual('undefined', THREE.BasicShadowMap);
     }),
   
     it('should be able to construct a Vector3 with default of x=0', function() {
       var vec3 = new THREE.Vector3();
       assert.equal(0, vec3.x);
     })
   })
   

6. Finally let's test again with $ npm test. This should run the tests above and succeed, showing something like:

   # should succeed and show THREE details:
     ․ The THREE object should have a defined BasicShadowMap constant: 0ms
     ․ The THREE object should be able to construct a Vector3 with default of x=0: 0ms
     2 passing (8ms)