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.
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.
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
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()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()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
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.
| 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.
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
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
NODE_DEBUG=oil-debug npm run ...
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.
Before submission, run the tests:
npm run test
If they're all green, great! Go ahead and submit the PR.