development.md

dropbox.js Development

Read this document if you want to build dropbox.js or modify its source code. If you want to write applications using dropbox.js, check out the Getting Started doc.

The library is written using CoffeeScript, built using cake, minified using uglify.js, tested using mocha and chai.js, and packaged using npm.

If you don't "speak" CoffeeScript, this document might address some of your concerns.

Dev Environment Setup

Install node.js to get npm (the node package manager), then use it to install the libraries required by the test suite.

git clone https://github.com/dropbox/dropbox-js.git
cd dropbox-js
npm install

Build

Run npm pack and ignore any deprecation warnings that might come up.

npm pack

The build output is in the lib/ directory. dropbox.js is the compiled library that ships in the npm package, and dropbox.min.js is a minified version, optimized for browser apps.

Documentation

Building the API documentation requires CoffeeScript installed globally.

npm install -g coffee-script

The following command builds the documentation.

cake doc

The documentation can be viewed in any modern browser.

open doc/index.html

By default, the generated documentation does not include private methods. Being able to browse through these methods can be helpful when writing new code.

cake devdoc

The documentation on dropbox.com/developers is generated by the command below. The output is in sitedoc/html.

cake sitedoc

Test

Install the CoffeeScript npm package globally, so you can type cake instead of node_modules/coffee-script/bin/cake.

npm install -g coffee-script

First, you will need to obtain a couple of Dropbox tokens that will be used by the automated tests.

cake tokens

Re-run the command above if the tests fail due to authentication errors.

Once you have Dropbox tokens, you can run the test suite in node.js, in your default browser, or as a Chrome application.

cake test
cake webtest
cake chrometest

The library is automatically re-built when running tests, so you don't need to run npm pack. Please run the tests in both node.js and a browser before submitting pull requests.

The tests store all their data in folders named along the lines of js tests.0.ac1n6lgs0e3lerk9. If tests fail, you might have to clean up these folders yourself.

Solving node.js Issues

If the node.js tests exit abruptly, the command below will help zoom in on the troublesome test.

LIST=1 cake test

Solving Browser Issues

An easy method to test a browser in a virtual machine is to skip the automated browser opening.

BROWSER=false cake webtest

A similar method can be used to launch a specific browser.

BROWSER=firefox cake webtest

When fighting a bug, it can be useful to keep the server process running after the test suite completes, so tests can be re-started with a browser refresh.

BROWSER=false NO_EXIT=1 cake webtest

Mocha's exclusive tests (it.only and describe.only) are very useful for quickly iterating while figuring out a bug.

Chrome Application / Extension Testing

The tests for Chrome apps / extensions require manual intervention right now.

The cake chrometest command will open a Google Chrome instance. The dropbox.js Test Suite application must be clicked.

Cordova Testing

The Cordova tests run against Android by default.

cake cordovatest

They can be customized to run against any platform.

CORDOVA_PLATFORM=ios cake cordovatest

Some platforms, such as Android, require that an emulator image be configured and started before running the tests.

Fully Automated Tests

The test suite opens up the Dropbox authorization page a few times, and also pops up a page that cannot close itself. dropbox.js ships with a Google Chrome extension that can fully automate the testing process on Chrome / Chromium.

The extension is written in CoffeeScript, so you will have to compile it.

cake extension

After compilation, have Chrome load the unpacked extension at test/chrome_extension and click on the scary-looking toolbar icon to activate the extension. The icon's color should turn red, to indicate that it is active.

The extension performs some checks to prevent against attacks. However, you should still disable the automation (by clicking on the extension icon) when you're not testing dropbox.js, just in case the extension code has bugs.

Custom Server

The test suite can be ran against a custom API server. This is only likely to be useful to Dropbox employees. The steps in this section document the process of pointing the test suite to a custom server.

First, create two applications on the custom server, configured as follows.

An "App folder" app:

• Type: Dropbox API App
• Store: Files and datastores
• Private folder: Yes
• Name: Automated Testing Keys

A "Full Dropbox" app:

• Type: Dropbox API App
• Store: Files and datastores
• Private folder: No
• Type of files: All files
• Name: Automated Testing Keys (Full Access)

Both applications should whitelist the following OAuth redirect URLs:

• Node tests: https://localhost:8912/oauth_callback
• Browser tests: https://localhost:8911/test/html/oauth_receiver.html
• Browser tests: https://localhost:8911/test/html/redirect_driver_test.html
• IE VM tests: https://10.0.2.2:8911/test/html/oauth_receiver.html
• IE VM tests: https://10.0.2.2:8911/test/html/redirect_driver_test.html
• Chrome tests: chrome-extension://nibiohflpcgopggnnboelamnhcnnpinm/test/html/chrome_oauth_receiver.html
• Chrome tests: https://nibiohflpcgopggnnboelamnhcnnpinm.chromiumapp.org/
• Cordova tests: https://www.dropbox.com/1/oauth2/redirect_receiver

Second, open test/config/api.json in a text editor. Plug in the "Full Dropbox" application's API key and secret into the "full" section, and the "App folder" application's API key and secret into the "sandbox" section. Change the server URLs to point to the custom server.

After changing the api.json file, it might be helpful to ask git to ignore the changes, so the custom configuration is not accidentally included in a pull request.

git update-index --assume-unchanged test/config/api.json

Third, obtain API tokens that point to the custom server.

API_CONFIG=test/config/api.json cake tokens

The custom server's URL is embedded in the API tokens, so all future tests will use the custom server. To get back to using the official Dropbox API server, re-generate the API tokens.

cake tokens

Release Process

1. Go to the master branch.

   git checkout master

2. At the very least, test in node.js and in a browser before releasing.

   cake test
   cake webtest

3. Bump the version in package.json.

4. Publish a new npm package.

   npm publish

5. Commit and tag the version bump on GitHub.

   git add package.json
   git commit -m "Release X.Y.Z."
   git tag -a -m "Release X.Y.Z" vX.Y.Z
   git push origin master
   git push origin --tags

6. Wait until the release shows up on the the cdn.js page for dropbox.js. The automated pull process is advertised to take 15 minutes or less. If you ever need to tweak the process, the configuration is here.

7. When the release is pulled into cdn.js, merge the master branch into the stable branch.

   cd ../dropbox-js
   git checkout stable
   git merge --ff-only master
   git push origin master