X-Git-Url: http://www.aleph1.co.uk/gitweb/?p=yaffs-website;a=blobdiff_plain;f=node_modules%2Fphantomjs-prebuilt%2FREADME.md;fp=node_modules%2Fphantomjs-prebuilt%2FREADME.md;h=04e2d952f8b5d8d1d1e8680124a304b617822b2f;hp=0000000000000000000000000000000000000000;hb=a2bd1bf0c2c1f1a17d188f4dc0726a45494cefae;hpb=57c063afa3f66b07c4bbddc2d6129a96d90f0aad diff --git a/node_modules/phantomjs-prebuilt/README.md b/node_modules/phantomjs-prebuilt/README.md new file mode 100644 index 000000000..04e2d952f --- /dev/null +++ b/node_modules/phantomjs-prebuilt/README.md @@ -0,0 +1,308 @@ +phantomjs-prebuilt +================== + +An NPM installer for [PhantomJS](http://phantomjs.org/), headless webkit with JS API. + +[![Build Status](https://travis-ci.org/Medium/phantomjs.svg?branch=master)](https://travis-ci.org/Medium/phantomjs) + +Building and Installing +----------------------- + +```shell +npm install phantomjs-prebuilt +``` + +Or grab the source and + +```shell +node ./install.js +``` + +What this installer is really doing is just grabbing a particular "blessed" (by +this module) version of Phantom. As new versions of Phantom are released +and vetted, this module will be updated accordingly. + +Running +------- + +```shell +bin/phantomjs [phantom arguments] +``` + +And npm will install a link to the binary in `node_modules/.bin` as +it is wont to do. + +Running via node +---------------- + +The package exports a `path` string that contains the path to the +phantomjs binary/executable. + +Below is an example of using this package via node. + +```javascript +var path = require('path') +var childProcess = require('child_process') +var phantomjs = require('phantomjs-prebuilt') +var binPath = phantomjs.path + +var childArgs = [ + path.join(__dirname, 'phantomjs-script.js'), + 'some other argument (passed to phantomjs script)' +] + +childProcess.execFile(binPath, childArgs, function(err, stdout, stderr) { + // handle results +}) + +``` + +Or `exec()` method is also provided for convenience: + +```javascript +var phantomjs = require('phantomjs-prebuilt') +var program = phantomjs.exec('phantomjs-script.js', 'arg1', 'arg2') +program.stdout.pipe(process.stdout) +program.stderr.pipe(process.stderr) +program.on('exit', code => { + // do something on end +}) +``` + +Note: [childProcess.spawn()](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) is called inside `exec()`. + +Running with WebDriver +---------------------- + +`run()` method detects when PhantomJS gets ready. It's handy to use with WebDriver (Selenium). + +```javascript +var phantomjs = require('phantomjs-prebuilt') +var webdriverio = require('webdriverio') +var wdOpts = { desiredCapabilities: { browserName: 'phantomjs' } } + +phantomjs.run('--webdriver=4444').then(program => { + webdriverio.remote(wdOpts).init() + .url('https://developer.mozilla.org/en-US/') + .getTitle().then(title => { + console.log(title) // 'Mozilla Developer Network' + program.kill() // quits PhantomJS + }) +}) +``` + +Versioning +---------- + +The major and minor number tracks the version of PhantomJS that will be +installed. The patch number is incremented when there is either an installer +update or a patch build of the phantom binary. + +Pre-2.0, this package was published to NPM as [phantomjs](https://www.npmjs.com/package/phantomjs). +We changed the name to [phantomjs-prebuilt](https://www.npmjs.com/package/phantomjs-prebuilt) at +the request of PhantomJS team. + +Continuous Integration +---------------------- + +Please **do not** download PhantomJS for every CI job because it can quickly +overload our CDNs. Instead take advantage of CI caching. + +In [Travis-CI](https://travis-ci.org/) add the following to your `.travis.yml` +to [enable caching](https://docs.travis-ci.com/user/caching/) & avoid repeated +downloads of PhantomJS. + +#### .travis.yml +```yml +cache: + directories: + - travis_phantomjs + +before_install: + # Upgrade PhantomJS to v2.1.1. + - "export PHANTOMJS_VERSION=2.1.1" + - "export PATH=$PWD/travis_phantomjs/phantomjs-$PHANTOMJS_VERSION-linux-x86_64/bin:$PATH" + - "if [ $(phantomjs --version) != $PHANTOMJS_VERSION ]; then rm -rf $PWD/travis_phantomjs; mkdir -p $PWD/travis_phantomjs; fi" + - "if [ $(phantomjs --version) != $PHANTOMJS_VERSION ]; then wget https://github.com/Medium/phantomjs/releases/download/v$PHANTOMJS_VERSION/phantomjs-$PHANTOMJS_VERSION-linux-x86_64.tar.bz2 -O $PWD/travis_phantomjs/phantomjs-$PHANTOMJS_VERSION-linux-x86_64.tar.bz2; fi" + - "if [ $(phantomjs --version) != $PHANTOMJS_VERSION ]; then tar -xvf $PWD/travis_phantomjs/phantomjs-$PHANTOMJS_VERSION-linux-x86_64.tar.bz2 -C $PWD/travis_phantomjs; fi" + - "phantomjs --version" +``` + +Deciding Where To Get PhantomJS +------------------------------- + +By default, this package will download phantomjs from our [releases](https://github.com/Medium/phantomjs/releases/). +This should work fine for most people. + +##### Downloading from a custom URL + +If github is down, or the Great Firewall is blocking github, you may need to use +a different download mirror. To set a mirror, set npm config property `phantomjs_cdnurl`. + +Alternatives include `https://bitbucket.org/ariya/phantomjs/downloads` (the official download site) +and `http://cnpmjs.org/downloads`. + +```Shell +npm install phantomjs-prebuilt --phantomjs_cdnurl=https://bitbucket.org/ariya/phantomjs/downloads +``` + +Or add property into your `.npmrc` file (https://www.npmjs.org/doc/files/npmrc.html) + +``` +phantomjs_cdnurl=https://bitbucket.org/ariya/phantomjs/downloads +``` + +Another option is to use PATH variable `PHANTOMJS_CDNURL`. +```shell +PHANTOMJS_CDNURL=https://bitbucket.org/ariya/phantomjs/downloads npm install phantomjs +``` + +##### Using PhantomJS from disk + +If you plan to install phantomjs many times on a single machine, you can +install the `phantomjs` binary on PATH. The installer will automatically detect +and use that for non-global installs. + +Cross-Platform Repositories +--------------------------- + +PhantomJS needs to be compiled separately for each platform. This installer +finds a prebuilt binary for your operating system, and downloads it. + +If you check your dependencies into git, and work on a cross-platform +team, then you need to tell NPM to rebuild any platform-specific dependencies. Run + +```shell +npm rebuild +``` + +as part of your build process. This problem is not specific to PhantomJS, and this +solution will work for any NodeJS package with native or platform-specific code. + +If you know in advance that you want to install PhantomJS for a specific architecture, +you can set the environment variables: `PHANTOMJS_PLATFORM` +(to set target platform) and `PHANTOMJS_ARCH` (to set target +arch), where `platform` and `arch` are valid values for +[process.platform and process.arch](https://nodejs.org/api/process.html). + +A Note on PhantomJS +------------------- + +PhantomJS is not a library for NodeJS. It's a separate environment and code +written for node is unlikely to be compatible. In particular PhantomJS does +not expose a Common JS package loader. + +This is an _NPM wrapper_ and can be used to conveniently make Phantom available. +It is not a Node JS wrapper. + +I have had reasonable experiences writing standalone Phantom scripts which I +then drive from within a node program by spawning phantom in a child process. + +Read the PhantomJS FAQ for more details: http://phantomjs.org/faq.html + +### Linux Note + +An extra note on Linux usage, from the PhantomJS download page: + + > There is no requirement to install Qt, WebKit, or any other libraries. It + > however still relies on Fontconfig (the package fontconfig or libfontconfig, + > depending on the distribution). + +Troubleshooting +--------------- + +##### Installation fails with `spawn ENOENT` + +This is NPM's way of telling you that it was not able to start a process. It usually means: + +- `node` is not on your PATH, or otherwise not correctly installed. +- `tar` is not on your PATH. This package expects `tar` on your PATH on Linux-based platforms. +- `bzip2` is not on your PATH. + +Check your specific error message for more information. + +##### Installation fails with `Error: EPERM` or `operation not permitted` or `permission denied` + +This error means that NPM was not able to install phantomjs to the file system. There are three +major reasons why this could happen: + +- You don't have write access to the installation directory. +- The permissions in the NPM cache got messed up, and you need to run `npm cache clean` to fix them. +- You have over-zealous anti-virus software installed, and it's blocking file system writes. + +##### Installation fails with `Error: read ECONNRESET` or `Error: connect ETIMEDOUT` + +This error means that something went wrong with your internet connection, and the installer +was not able to download the PhantomJS binary for your platform. Please try again. + +##### I tried again, but I get `ECONNRESET` or `ETIMEDOUT` consistently. + +Do you live in China, or a country with an authoritarian government? We've seen problems where +the GFW or local ISP blocks github, preventing the installer from downloading the binary. + +Try visiting [the download page](https://bitbucket.org/ariya/phantomjs/downloads) manually. +If that page is blocked, you can try using a different CDN with the `PHANTOMJS_CDNURL` +env variable described above. + +##### I am behind a corporate proxy that uses self-signed SSL certificates to intercept encrypted traffic. + +You can tell NPM and the PhantomJS installer to skip validation of ssl keys with NPM's +[strict-ssl](https://www.npmjs.org/doc/misc/npm-config.html#strict-ssl) setting: + +``` +npm set strict-ssl false +``` + +WARNING: Turning off `strict-ssl` leaves you vulnerable to attackers reading +your encrypted traffic, so run this at your own risk! + +##### I tried everything, but my network is b0rked. What do I do? + +If you install PhantomJS manually, and put it on PATH, the installer will try to +use the manually-installed binaries. + +##### I'm on Debian or Ubuntu, and the installer failed because it couldn't find `node` + +Some Linux distros tried to rename `node` to `nodejs` due to a package +conflict. This is a non-portable change, and we do not try to support this. The +[official documentation](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager#ubuntu-mint-elementary-os) +recommends that you run `apt-get install nodejs-legacy` to symlink `node` to `nodejs` +on those platforms, or many NodeJS programs won't work properly. + +##### I'm using an unsupported version of Linux or an ARM processor. I get errors about "Unexpected platform or architecture". What do I do? + +We only have binaries available for common OS / processor configurations. Sorry. + +You may be able to get a PhantomJS binary from your operating system's package +manager. Or you can build your own from source. If you put that binary on PATH, +this installer will use it (see "Deciding Where to Get PhantomJS" above). + + +Contributing +------------ + +Questions, comments, bug reports, and pull requests are all welcome. Submit them at +[the project on GitHub](https://github.com/Medium/phantomjs/). If you haven't contributed to an +[Medium](http://github.com/Medium/) project before please head over to the +[Open Source Project](https://github.com/Medium/open-source#note-to-external-contributors) and fill +out an OCLA (it should be pretty painless). + +Bug reports that include steps-to-reproduce (including code) are the +best. Even better, make them in the form of pull requests. + +Author +------ + +[Dan Pupius](https://github.com/dpup) +([personal website](http://pupius.co.uk)) and +[Nick Santos](https://github.com/nicks), supported by +[A Medium Corporation](http://medium.com/). + +License +------- + +Copyright 2012 [A Medium Corporation](http://medium.com/). + +Licensed under the Apache License, Version 2.0. +See the top-level file `LICENSE.txt` and +(http://www.apache.org/licenses/LICENSE-2.0).