BlueGit

blue-star danique-bot

Files

danique-bot / node_modules / phantomjs-prebuilt / README.md

README.md

Import template
timfa Tim · pushed by timfa · 4 years ago
c788ad20 History
README.md 11.0 KiB Download Raw

phantomjs-prebuilt ==================

An NPM installer for PhantomJS, headless webkit with JS API.

Build Status

Building and Installing -----------------------

npm install phantomjs-prebuilt

Or grab the source and

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 -------

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.

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:

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() is called inside exec().

Running with WebDriver ----------------------

run() method detects when PhantomJS gets ready. It's handy to use with WebDriver (Selenium).

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. We changed the name to 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 add the following to your .travis.yml to enable caching & avoid repeated downloads of PhantomJS.

.travis.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. 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.

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.

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

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.

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 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 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 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. If you haven't contributed to an Medium project before please head over to the Open Source Project 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 (personal website) and Nick Santos, supported by A Medium Corporation.

License -------

Copyright 2012 A Medium Corporation.

Licensed under the Apache License, Version 2.0. See the top-level file LICENSE.txt and (http://www.apache.org/licenses/LICENSE-2.0).

Source
1phantomjs-prebuilt
2==================
3
4An NPM installer for [PhantomJS](http://phantomjs.org/), headless webkit with JS API.
5
6[![Build Status](https://travis-ci.org/Medium/phantomjs.svg?branch=master)](https://travis-ci.org/Medium/phantomjs)
7
8Building and Installing
9-----------------------
10
11```shell
12npm install phantomjs-prebuilt
13```
14
15Or grab the source and
16
17```shell
18node ./install.js
19```
20
21What this installer is really doing is just grabbing a particular "blessed" (by
22this module) version of Phantom. As new versions of Phantom are released
23and vetted, this module will be updated accordingly.
24
25Running
26-------
27
28```shell
29bin/phantomjs [phantom arguments]
30```
31
32And npm will install a link to the binary in `node_modules/.bin` as
33it is wont to do.
34
35Running via node
36----------------
37
38The package exports a `path` string that contains the path to the
39phantomjs binary/executable.
40
41Below is an example of using this package via node.
42
43```javascript
44var path = require('path')
45var childProcess = require('child_process')
46var phantomjs = require('phantomjs-prebuilt')
47var binPath = phantomjs.path
48
49var childArgs = [
50 path.join(__dirname, 'phantomjs-script.js'),
51 'some other argument (passed to phantomjs script)'
52]
53
54childProcess.execFile(binPath, childArgs, function(err, stdout, stderr) {
55 // handle results
56})
57
58```
59
60Or `exec()` method is also provided for convenience:
61
62```javascript
63var phantomjs = require('phantomjs-prebuilt')
64var program = phantomjs.exec('phantomjs-script.js', 'arg1', 'arg2')
65program.stdout.pipe(process.stdout)
66program.stderr.pipe(process.stderr)
67program.on('exit', code => {
68 // do something on end
69})
70```
71
72Note: [childProcess.spawn()](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) is called inside `exec()`.
73
74Running with WebDriver
75----------------------
76
77`run()` method detects when PhantomJS gets ready. It's handy to use with WebDriver (Selenium).
78
79```javascript
80var phantomjs = require('phantomjs-prebuilt')
81var webdriverio = require('webdriverio')
82var wdOpts = { desiredCapabilities: { browserName: 'phantomjs' } }
83
84phantomjs.run('--webdriver=4444').then(program => {
85 webdriverio.remote(wdOpts).init()
86 .url('https://developer.mozilla.org/en-US/')
87 .getTitle().then(title => {
88 console.log(title) // 'Mozilla Developer Network'
89 program.kill() // quits PhantomJS
90 })
91})
92```
93
94Versioning
95----------
96
97The major and minor number tracks the version of PhantomJS that will be
98installed. The patch number is incremented when there is either an installer
99update or a patch build of the phantom binary.
100
101Pre-2.0, this package was published to NPM as [phantomjs](https://www.npmjs.com/package/phantomjs).
102We changed the name to [phantomjs-prebuilt](https://www.npmjs.com/package/phantomjs-prebuilt) at
103the request of PhantomJS team.
104
105Continuous Integration
106----------------------
107
108Please **do not** download PhantomJS for every CI job because it can quickly
109overload our CDNs. Instead take advantage of CI caching.
110
111In [Travis-CI](https://travis-ci.org/) add the following to your `.travis.yml`
112to [enable caching](https://docs.travis-ci.com/user/caching/) & avoid repeated
113downloads of PhantomJS.
114
115#### .travis.yml
116```yml
117cache:
118 directories:
119 - travis_phantomjs
120
121before_install:
122 # Upgrade PhantomJS to v2.1.1.
123 - "export PHANTOMJS_VERSION=2.1.1"
124 - "export PATH=$PWD/travis_phantomjs/phantomjs-$PHANTOMJS_VERSION-linux-x86_64/bin:$PATH"
125 - "if [ $(phantomjs --version) != $PHANTOMJS_VERSION ]; then rm -rf $PWD/travis_phantomjs; mkdir -p $PWD/travis_phantomjs; fi"
126 - "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"
127 - "if [ $(phantomjs --version) != $PHANTOMJS_VERSION ]; then tar -xvf $PWD/travis_phantomjs/phantomjs-$PHANTOMJS_VERSION-linux-x86_64.tar.bz2 -C $PWD/travis_phantomjs; fi"
128 - "phantomjs --version"
129```
130
131Deciding Where To Get PhantomJS
132-------------------------------
133
134By default, this package will download phantomjs from our [releases](https://github.com/Medium/phantomjs/releases/).
135This should work fine for most people.
136
137##### Downloading from a custom URL
138
139If github is down, or the Great Firewall is blocking github, you may need to use
140a different download mirror. To set a mirror, set npm config property `phantomjs_cdnurl`.
141
142Alternatives include `https://bitbucket.org/ariya/phantomjs/downloads` (the official download site)
143and `http://cnpmjs.org/downloads`.
144
145```Shell
146npm install phantomjs-prebuilt --phantomjs_cdnurl=https://bitbucket.org/ariya/phantomjs/downloads
147```
148
149Or add property into your `.npmrc` file (https://www.npmjs.org/doc/files/npmrc.html)
150
151```
152phantomjs_cdnurl=https://bitbucket.org/ariya/phantomjs/downloads
153```
154
155Another option is to use PATH variable `PHANTOMJS_CDNURL`.
156```shell
157PHANTOMJS_CDNURL=https://bitbucket.org/ariya/phantomjs/downloads npm install phantomjs
158```
159
160##### Using PhantomJS from disk
161
162If you plan to install phantomjs many times on a single machine, you can
163install the `phantomjs` binary on PATH. The installer will automatically detect
164and use that for non-global installs.
165
166Cross-Platform Repositories
167---------------------------
168
169PhantomJS needs to be compiled separately for each platform. This installer
170finds a prebuilt binary for your operating system, and downloads it.
171
172If you check your dependencies into git, and work on a cross-platform
173team, then you need to tell NPM to rebuild any platform-specific dependencies. Run
174
175```shell
176npm rebuild
177```
178
179as part of your build process. This problem is not specific to PhantomJS, and this
180solution will work for any NodeJS package with native or platform-specific code.
181
182If you know in advance that you want to install PhantomJS for a specific architecture,
183you can set the environment variables: `PHANTOMJS_PLATFORM`
184(to set target platform) and `PHANTOMJS_ARCH` (to set target
185arch), where `platform` and `arch` are valid values for
186[process.platform and process.arch](https://nodejs.org/api/process.html).
187
188A Note on PhantomJS
189-------------------
190
191PhantomJS is not a library for NodeJS. It's a separate environment and code
192written for node is unlikely to be compatible. In particular PhantomJS does
193not expose a Common JS package loader.
194
195This is an _NPM wrapper_ and can be used to conveniently make Phantom available.
196It is not a Node JS wrapper.
197
198I have had reasonable experiences writing standalone Phantom scripts which I
199then drive from within a node program by spawning phantom in a child process.
200
201Read the PhantomJS FAQ for more details: http://phantomjs.org/faq.html
202
203### Linux Note
204
205An extra note on Linux usage, from the PhantomJS download page:
206
207 > There is no requirement to install Qt, WebKit, or any other libraries. It
208 > however still relies on Fontconfig (the package fontconfig or libfontconfig,
209 > depending on the distribution).
210
211Troubleshooting
212---------------
213
214##### Installation fails with `spawn ENOENT`
215
216This is NPM's way of telling you that it was not able to start a process. It usually means:
217
218- `node` is not on your PATH, or otherwise not correctly installed.
219- `tar` is not on your PATH. This package expects `tar` on your PATH on Linux-based platforms.
220- `bzip2` is not on your PATH.
221
222Check your specific error message for more information.
223
224##### Installation fails with `Error: EPERM` or `operation not permitted` or `permission denied`
225
226This error means that NPM was not able to install phantomjs to the file system. There are three
227major reasons why this could happen:
228
229- You don't have write access to the installation directory.
230- The permissions in the NPM cache got messed up, and you need to run `npm cache clean` to fix them.
231- You have over-zealous anti-virus software installed, and it's blocking file system writes.
232
233##### Installation fails with `Error: read ECONNRESET` or `Error: connect ETIMEDOUT`
234
235This error means that something went wrong with your internet connection, and the installer
236was not able to download the PhantomJS binary for your platform. Please try again.
237
238##### I tried again, but I get `ECONNRESET` or `ETIMEDOUT` consistently.
239
240Do you live in China, or a country with an authoritarian government? We've seen problems where
241the GFW or local ISP blocks github, preventing the installer from downloading the binary.
242
243Try visiting [the download page](https://bitbucket.org/ariya/phantomjs/downloads) manually.
244If that page is blocked, you can try using a different CDN with the `PHANTOMJS_CDNURL`
245env variable described above.
246
247##### I am behind a corporate proxy that uses self-signed SSL certificates to intercept encrypted traffic.
248
249You can tell NPM and the PhantomJS installer to skip validation of ssl keys with NPM's
250[strict-ssl](https://www.npmjs.org/doc/misc/npm-config.html#strict-ssl) setting:
251
252```
253npm set strict-ssl false
254```
255
256WARNING: Turning off `strict-ssl` leaves you vulnerable to attackers reading
257your encrypted traffic, so run this at your own risk!
258
259##### I tried everything, but my network is b0rked. What do I do?
260
261If you install PhantomJS manually, and put it on PATH, the installer will try to
262use the manually-installed binaries.
263
264##### I'm on Debian or Ubuntu, and the installer failed because it couldn't find `node`
265
266Some Linux distros tried to rename `node` to `nodejs` due to a package
267conflict. This is a non-portable change, and we do not try to support this. The
268[official documentation](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager#ubuntu-mint-elementary-os)
269recommends that you run `apt-get install nodejs-legacy` to symlink `node` to `nodejs`
270on those platforms, or many NodeJS programs won't work properly.
271
272##### I'm using an unsupported version of Linux or an ARM processor. I get errors about "Unexpected platform or architecture". What do I do?
273
274We only have binaries available for common OS / processor configurations. Sorry.
275
276You may be able to get a PhantomJS binary from your operating system's package
277manager. Or you can build your own from source. If you put that binary on PATH,
278this installer will use it (see "Deciding Where to Get PhantomJS" above).
279
280
281Contributing
282------------
283
284Questions, comments, bug reports, and pull requests are all welcome. Submit them at
285[the project on GitHub](https://github.com/Medium/phantomjs/). If you haven't contributed to an
286[Medium](http://github.com/Medium/) project before please head over to the
287[Open Source Project](https://github.com/Medium/open-source#note-to-external-contributors) and fill
288out an OCLA (it should be pretty painless).
289
290Bug reports that include steps-to-reproduce (including code) are the
291best. Even better, make them in the form of pull requests.
292
293Author
294------
295
296[Dan Pupius](https://github.com/dpup)
297([personal website](http://pupius.co.uk)) and
298[Nick Santos](https://github.com/nicks), supported by
299[A Medium Corporation](http://medium.com/).
300
301License
302-------
303
304Copyright 2012 [A Medium Corporation](http://medium.com/).
305
306Licensed under the Apache License, Version 2.0.
307See the top-level file `LICENSE.txt` and
308(http://www.apache.org/licenses/LICENSE-2.0).