Skip to content
Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
192 lines (117 sloc) 7.32 KB

Contributing to oil.js

Feel free to fork this project and open pull requests to the master branch. We do not accept pull requests to the source files without accompanying tests. Bug reports are welcome through the issues tab of the project.

Installation / Build

Setting up development environment

To begin with, fork the library and install dependencies. You need git and node; you might use nvm or nenv to install node.

Run these commands in order to create a local copy of the project:

git clone https://github.com/as-ideas/oil.git
cd oil
npm install

After install there is a post install step which automatically runs build.

Basic Usage

Start the app with this command:

npm start

You will now be able to view a local test server at http://localhost:8080/. The html files from src/demos are now accessible through http://localhost:8080/demos/direct-integration.html.

For development you want to run a local webpack-dev-server at http://localhost:3000/ with webpack auto-watching for changes to the source files:

npm run watch

This test server serves the html files from src/demos under the path webpack-dev-server. So if for instance you are going for a change in the small-design.html you want to open the URL http://localhost:3000/webpack-dev-server/demos/small-design.html

See the full list of available npm scripts here

window.AS_OIL

A successfully integrated oil.js puts an object into your window named AS_OIL which provides a range of methods you can call to mimic user behaviour. It also stores the configuration and the locale object.

// current configuration
window.AS_OIL.CONFIG;
// current locale configuration
window.AS_OIL.CONFIG.locale;

// functions
window.AS_OIL.status() 
window.AS_OIL.triggerOptIn() 
window.AS_OIL.triggerSoiOptIn() 
window.AS_OIL.triggerPoiOptIn() 
window.AS_OIL.triggerOptOut()
window.AS_OIL.getVendorConsents()
window.AS_OIL.getPublisherConsents()
window.AS_OIL.getConsentData()
window.AS_OIL.getVendorList()
window.AS_OIL.applyGDPR()

Dev-Kit

On some demo pages there's a little oil rig icon in the top right corner. Clicking it opens a menu where you can check the return values from the Oil instance as well as more options where you can opt-in, opt-out etc.

You can also run commands on the window.AS_OIL_DEV_KIT object, like:

window.AS_OIL_DEV_KIT.status() 
window.AS_OIL_DEV_KIT.triggerOptIn() 
window.AS_OIL_DEV_KIT.triggerSoiOptIn() 
window.AS_OIL_DEV_KIT.triggerPoiOptIn() 
window.AS_OIL_DEV_KIT.triggerOptOut()
window.AS_OIL_DEV_KIT.getVendorConsents()
window.AS_OIL_DEV_KIT.getPublisherConsents()
window.AS_OIL_DEV_KIT.getConsentData()
window.AS_OIL_DEV_KIT.getVendorList()

Tests

Running unit tests:

npm test

There are two kinds of unit tests: For the oil.js itself (npm run test:unit) and for the node server delivering all files (npm run test:node).

npm run test:unit
npm run test:node

E2E Tests

For local tests utilising Selenium Webdriver add the following DNS entries into your /etc/hosts file:

127.0.0.1 oilsite1
127.0.0.1 oilsite2
127.0.0.1 oilcdn

If you made changes to your files, run npm run build. Then start the app in one terminal window with:

npm start

and then in another terminal:

npm run e2e

If you want to run only one test, in this example only tests from the file test/e2e/direct_integration_test.js, do this:

./node_modules/.bin/nightwatch -c etc/nightwatch.local.conf.js -e chrome --test test/e2e/direct_integration_test.js

You can also run your local e2e tests with different browsers using Browserstack.

NPM scripts

Script Description
build generate a complete build in dist folder
build:docs compile documentation files into dist/docs folder
build:watch start webpack-dev-server on http://localhost:8080/ where files from the dist server are served and hotload on file change
watch start webpack-dev-server on http://localhost:3000/ and hotload on file change
eslint Do the linting thing
browserstack Run e2e tests with selected browser's against test installation at https://oil-integration-host1.herokuapp.com. For profiles used see file etc/runBrowserstackSeq.sh
browserstack:full Run e2e tests with selected browser's against test installation at https://oil-integration-host1.herokuapp.com. For profiles used see file etc/runFullBrowserstackSeq.sh
browserstack:remote-localhost Run e2e tests with selected browser's against your localhost. See details on this here
e2e Run E2E tests with Chrome Headless browser. Remember to run a webserver with npm start in another terminal window before starting this.
e2esafari Run E2E tests with Safari. Remember to run a webserver with npm start in another terminal window before starting this.
test:unit Run the unit tests
test:node Run the server tests
test:selenium Run the E2E tests against the integration CDN
test:watch Run the tests and re-run on file update

For an exhausting list just do npm run.

Browserstack integration

Browserstack build tests

You can run all E2E tests with different setups using Browserstack. Tests use our remote server at https://oil-integration-host1.herokuapp.com where the latest release is deployed to.

To run tests in batch there are two commands, the first one covering a limited but most relevant selection of browsers.

npm run browserstack
npm run browserstack:full

Both commands require you to have your Browserstack credentials ready. You can find them here.

To test with only a specific browser, do this:

ENV_USER=your-browserstack-user ENV_KEY=your-browserstack-key ./node_modules/.bin/nightwatch -c etc/nightwatch.remote.conf.js -e ff52

The -e parameter should contain the id of the test setting to launch with. In this case ff52. For all available test settings check the objects inside the file etc/nightwatch.remote.config.js

Browserstack dev tests

You can run the tests on your local http://localhost:8080/ in different browsers using BrowserStack. To do this, download BrowserStackLocal, install and run the application. Create a build with npm run build and start the server with npm start. Finally, get your browserstack credentials and run (for chrome57):

ENV_USER=your-browserstack-user ENV_KEY=your-browserstack-key ./node_modules/.bin/nightwatch -c etc/nightwatch.localhost-remote.conf.js -e chrome57

For possible test settings see above section.

To run tests in batch trigger this command:

npm run browserstack:remote-localhost

debug logging

NODE_DEBUG=oil-debug npm run ...

Creating and editing documentation

We are using AsciiDoc to create and edit the documentation. You can find the sources und docs/ and can create the HTML (dist/docs) with npm run build:docs.

Submitting a pull request

Before submission, run the tests:

npm run test

If they're all green, great! Go ahead and submit the PR.

You can’t perform that action at this time.