Skip to content

Latest commit

 

History

History
116 lines (90 loc) · 5.14 KB

CONTRIBUTING.md

File metadata and controls

116 lines (90 loc) · 5.14 KB

Spectrum Browser Testing

Testing this library against a spectrum of browsers involves several bits of infrastructure, which are each either very cheap or free for open source projects. You will need an Amazon Web Services (AWS) S3 account, for which you can expect to pay a couple bucks for annually. You will also need a SauceLabs account, which is free for open source projects.

You will need to populate an activate.sh script in the project root. Git has been directed to ignore this file to mitigate fears of accidentally sharing your credentials. This configuration file is used both for running browser tests during development and to generate the encrypted configuration for Travis CI (continuous integration).

export S3_USERNAME=
export S3_BUCKET=jasminum
export S3_REGION=Oregon
export S3_WEBSITE=http://jasminum.s3-website-us-west-2.amazonaws.com
export S3_ACCESS_KEY_ID=xxxxxxxxxxxxxxxxxxxx
export S3_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export SAUCE_USERNAME=montagejs-jasminum
export SAUCE_ACCESS_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

AWS S3

You will need an account for S3. Note your S3 user name under S3_USERNAMEin activate.sh. It is not your email address. It is not mine either.

Sign into the console. Click your name and follow the menu to “Security Credentials”. I was unable to figure out how to set up IAM users, but if you do, please come back and amend this document for posterity. Continue to your own security credentials. Expand the “Access Keys” section. Create an access key. Record the Access Key ID under S3_ACCESS_KEY_ID in activate.sh, and the key itself under S3_ACCESS_KEY. These access keys can be revoked if you lose control over them.

Create a bucket. Note the name of the bucket as S3_BUCKET in activate.sh. Open your bucket and select the “Properties” tab. Note the S3_REGION, which depends on which datacenter you chose for your bucket. Expand the “Static Website Hosting” section. Note the “Endpoint address” as S3_WEBSITE. The test suite will upload a built version of this project to S3 using the knox package from npm, and then will use Selenium WebDriver, wd in npm, to load the test page from the S3 website.

Sauce Labs

You will need an account with Sauce Labs. If the account will be used for continuous integration for an open source project, apply for an open source account for your project. Choose a user name like montagejs-jasminum. If you are just using Sauce Labs for testing during development or if you are developing a closed source project, you will need to purchase a plan. If you have a plan, you can create sub-accounts for individual projects.

Note your Sauce Labs user name in activate.sh under SAUCE_USERNAME.

Your Sauce Labs access key is visible in the left column of the dashboard. Make a note of it under SAUCE_ACCESS_KEY. The dashboard will show all of your Selenium WebDriver sessions. A link in the top left will take you to your “Open Sauce Profile”, a link you can share to show your project's build status.

Check your local copy

To test your working copy, use the command npm run test:sauce. This will read the environment variables in activate.sh and then run test/sauce.js, which will in turn orchestrate the creation of a build script, uploading that script to Amazon S3, and the execution of a Selenium WebDriver session on Sauce Labs for each of the sauce.configurations in package.json, and annotating the test results using the Sauce Labs API.

Travis Continuous Integration

You will probably not need to deal with this portion personally. This package is already set up with Travis, and a commit hook is installed on Github to automatically kick off jobs for any push to the main repository. However, you will need to do these steps if you intend to run tests from your own fork. Take care not to push changes to .travis.yml upstream.

We use .travis.yml to instruct Travis CI to run the Node.js tests and the spectrum of browser tests. The browser tests need the content of your activate.sh script, but that information has to be encrypted and appended to .travis.yml. To do this you will need the travis command line tool and Ruby. Version 2.1.0 of Ruby, installed with Homebrew was suffiient in my experience. Earlier versions of Ruby, particularly an earlier version packed with the operating system, were not. Gem did not cooperate the first time. It may require multiple attempts. If you find that your experience differs substantially, please ammend these notes for posterity.

gem install travis

The enclosed encrypt.sh script uses travis encrypt to append the encrypted environment variables to .travis.yml.

source encrypt.sh

The script is very small and not very clever, so before you run it again, you will need to manually remove the previous environment variables from the end of .travis.yml.

Obtain an account for Travis CI. From their web interface, under accounts, find your repository and enable continuous integration. Travis will install its commit hook in your repository on your behalf.