phantomjs使用說明

phantomjs實現了一個無界面的webkit瀏覽器。雖然沒有界面，但dom渲染、js運行、網絡訪問、canvas/svg繪製等功能都很完備，在頁面抓取、頁面輸出、自動化測試等方面有普遍的應用。

安裝

下載phantomjs（官方下載，下載失敗請訪問另外一個下載點）。解壓到任意目錄，並將包含phantomjs.exe的目錄添加到系統路徑。

若是要藉助phantomjs進行無頭測試，請參考各個測試框架的說明，或者參考phantomjs的官方文檔：http://phantomjs.org/headless-testing.html。

使用說明

簡單示例

JavaScript

1 2 3 4 5 6 7 8 9 10 11 12 13

// test.js var page = require ( 'webpage' ) . create ( ) ,      system = require ( 'system' ) ,      address ; if ( system . args . length === 1 ) {      phantom . exit ( 1 ) ; } else {      address = system . args [ 1 ] ;      page . open ( address , function ( status ) {          console . log ( page . content ) ;          phantom . exit ( ) ;      } ) ; }

運行：

Shell

1	phantomjs . / test .js http : / / baidu .com

這個例子簡單地展現了經過phantom訪問baidu.com，並輸入html內容。使用方式就像使用node運行js代碼同樣。在phantom運行時，它會向當前代碼運行環境注入phantom對象。如上面代碼中，經過phantom對象控制程序終結。示例中其餘代碼的含義以及更多深刻的用法，將在下文中展開。

---

window對象

在使用phantom時，我首先關注的是DOM和BOM接口。不過這不是一個問題，看了下面的代碼就能瞭解：

JavaScript

1 2 3

// test.js console . log ( window === this ) ; phantom . exit ( ) ;

運行：

Shell

1	phantomjs . / test .js

結果爲 true。也就是說，就像瀏覽器環境同樣，咱們的代碼運行在window環境下，能夠很方便地進行DOM方面的操做。

 注：若是使用web page模塊打開頁面，則請不要在此window對象下進行任何DOM相關的操做，由於這個window並非page對象內的window。若是想要執行dom相關操做，請參閱 page.evaluate()部分。

---

phantom對象

以前的例子中咱們已經初步認識了phantom對象。它的功能是定義和控制phantom運行環境的參數和流程。關鍵的API有：

1. phantom.args String[]
   獲取傳給本JS程序的參數，須要與 system.args進行區分（system模塊詳見下文），後者表示傳給phantomjs引擎的參數。例如 phantomjs ./test.js http://baidu.com這句語句，經過phantom.args，咱們能獲得的參數列表爲 ["http://baidu.com"]，而經過 system.args則獲得 ["./test.js", "http://baidu.com"]這樣的參數列表。差別就在因而否包含當前腳本名稱。不過 phantom.scriptName這個API提供了獲取腳本名稱的功能。
2. phantom.cookies Object[]
   獲取或設置cookies，不過對於設置建議使用其餘的API完成。同時相關的API還有:
   • phantom.addCookie(Object) Boolean：添加cookie值
   • phantom.deleteCookie(cookieName) Boolean：刪除指定Cookie值
   • phantom.clearCookies()：清空全部的cookie
   • phantom.cookiesEnabled Boolean：獲取或設置是否支持cookie
3. phantom.injectJs(fileName) Boolean:
   把指定的外部JS文件注入到當前環境。執行這個方法時，phantomjs首先會從當前目錄檢索此文件，若是找不到，則再到 phantom.libraryPath指定的路徑尋找。 phantom.libraryPath這個API基本上就是爲 phantom.injectJs()服務的。
4. phantom.onError
   當頁面存在js錯誤，且沒有被 page.onError處理，則會被此handler捕獲。下面是使用此API的一個例子。因爲phantom環境下代碼調試很困難，瞭解這些錯誤捕獲的API也許會對咱們的實際使用有所幫助。
   
   JavaScript

   1 2 3 4 5 6 7 8 9 10 11

   phantom . onError = function ( msg , trace ) {      var msgStack = [ 'PHANTOM ERROR: ' + msg ] ;      if ( trace & amp ; & amp ; trace . length ) {          msgStack . push ( 'TRACE:' ) ;          trace . forEach ( function ( t ) {              msgStack . push ( ' -> ' + ( t . file || t . sourceURL ) + ': ' + t . line + ( t . function ? ' (in function ' + t . function + ')' : '' ) ) ;          } ) ;      }      console . error ( msgStack . join ( '\n' ) ) ;      phantom . exit ( 1 ) ; } ;

5. phantom.exit(returnValue)
   這個API已經見過屢次了，它的做用是退出程序，能夠設置一個退出代碼，默認是0。

---

web page 模塊

web page模塊的功能是處理具體的頁面。使用時須要引入模塊，並建立實例：

JavaScript

1 2	var webPage = require ( 'webpage' ) ; var page = webPage . create ( ) ;

 本文中不經說明， page指代 require("webpage").create()的實例。

1. page.cookies Object[]
   與上文中的 phantom.cookies相似，表示本url下的cookie的讀取。一樣相似的API還有addCookie()、 deleteCookie()、 clearCookies()。
2. 頁面內容相關的API
   • page.content String：獲取或設置當前頁面的html。
   • page.plainText String：這是一個只讀屬性，獲取頁面去除html標記的文本（考慮$.text()）。
   • page.url String：只讀，獲取當前頁面的url。
   • page.setContent()：容許修改 page.content和 page.url內容，會觸發reload。
3. page.settings Object
   對於當前頁面的一些配置項。此API必須在 page.open()調用以前設置，不然不會起做用。如下是配置項：
   * javascriptEnabled 默認 true：是否執行頁面內的javascript
   • loadImages 默認 true：是否載入圖片
   • userAgent ：傳遞給服務器的userAgent字符串
   • userName ：用於http訪問受權的用戶名
   • password ：用於http訪問受權的密碼
   • XSSAuditingEnabled 默認 false：是否監控跨域請求
   • resourceTimeout 單位 ms：定義資源請求的超時時間。若是設置了此項，則頁面中若是有任何資源超過此時限未請求成功，則頁面其餘部分也會中止請求，並觸發onResourceTimeout()事件處理。
4. page.customHeaders Object
   phantom容許在請求時在http請求頭部添加額外信息，此設置項對這個page裏面全部的請求都生效（包含頁面和其餘資源的請求）。添加的信息並無限制，但若是設置 User-Agent的值，那麼這個值會覆蓋掉 page.settings裏的設置值。示例：
   
   JavaScript

   1 2 3 4

   page . customHeaders = {      "X-Test" : "foo" ,      "DNT" : "1" } ;

5. page.libraryPath String
   與 phantom.libraryPath相似，page對象也支持設置js文件路徑，同時能夠經過相應的page.injectJs()方法注入javascript文件。除了 page.injectJs()方法外，還有page.includeJs()也能夠加入javascript文件。它們的區別在於， page.injectJs()不強求此文件能訪問獲得，即便是一個不可訪問的資源也能夠。
6. page.navigationLocked Boolean 默認 fasle
   設置是否容許離開當前頁面，默認是容許。
7. page.open()
   此方法用於打開一個網頁，是一個很重要的API，它有三種調用形式：
   • open(url, callback)
   • open(url, method, callback)
   • open(url, method, data, callback)

   聯想一下 $.ajax()，能夠更好理解這個API。對於這些參數，須要單獨闡述的是 callback。callback()會在頁面載入完成後調用，由 page.onLoadFinished調用（時機晚於page.onLoadFinished）。這個 callback會接受一個參數 status，可能值爲 "success"和"fail"，指示頁面是否加載成功。示例能夠參考「簡單示例」一節的例子。

8. page.close()
   與 page.open()對應，調用 page.close()以後，會釋放page所佔用的內存，咱們不能夠在此以後再調用page實例。在實際的操做中，調用此方法並不會完成清空所佔內存；javascript的垃圾回收機制也不會回收page實例。但在實際使用中，經常會遇到將一個page實例反覆open的狀況。在一個頁面用完後，記得必定要執行 page.close()，這樣在下一次open的時候，纔不會重複分配堆棧空間。
9. page.evaluate(fn, [param])
   對於page打開的頁面，每每須要與其進行一些交互。 page.evaluate()提供了在page打開頁面的上下文（下文直接用page上下文指代）執行function的功能（類比Chrome開發者工具的控制檯）。以下例：
   JavaScript

   1 2 3 4 5 6 7

   page . open ( 'http://m.bing.com' , function ( status ) {      var title = page . evaluate ( function ( s ) {          return document . querySelector ( s ) . innerText ;      } , 'title' ) ;      console . log ( title ) ;      phantom . exit ( ) ; } ) ;

   在這個例子中， page.evaluate()接受兩個參數，第一個是必需的，表示須要在page上下文運行的函數 fn；第二個是可選的，表示須要傳給 fn的參數 param。 fn容許有一個返回值return，而且此返回值最終做爲 page.evaluate()的返回值。這邊對於剛剛命名的 param和return有一些額外的說明和注意事項。對於整個phantom進程而言， page.evaluate()是跑在一個沙盒中， fn沒法訪問一切phantom域中的變量；一樣 page.evaluate()方法外部也不該該嘗試訪問page上下文中的內容。那麼若是兩個做用域須要交換一些數據，只能依靠 param和 return。不過限制很大， param和 return必須爲可以轉化爲JSON字符串，換言之，只能是基本數據類型或者簡單對象，像DOM 節點、$對象、function、閉包等就無能爲力了。
   這個方法是同步的，若是執行的內容對後續操做不具有前置性，能夠嘗試異步方法以提升性能：page.evaluateAsync()。

10. page.render(filename)
    page.render()可以把當前頁面渲染成圖片並輸出到指定文件中。輸出的文件格式由傳入的文件擴展名決定，目前支持 PNG、 JPEG、 GIF、 PDF。
    JavaScript

    1 2 3 4 5

    var page = require ( 'webpage' ) . create ( ) ; page . open ( 'http://github.com/' , function ( ) {      page . render ( 'github.png' ) ;      phantom . exit ( ) ; } ) ;

    還有其餘一些API會對 page.render()產生影響，如：

    • page.zoomFactor Number： 設置縮放比率
    • page.clipRect Object：設置輸出的矩形區域，例如：
      
      JavaScript

      1 2 3 4 5 6

      page . clipRect = {      top : 14 ,      left : 3 ,      width : 400 ,      height : 300 } ;

      還有一些頁面設置參數，若是紙張大小，側邊距等，在此不詳述。web page也支持輸出圖片base64格式的字符串，API爲 page.renderBase64()，也再也不詳述。

    • page.sendEvent()
      爲了交互的須要（測試的須要），phantom容許經過代碼模擬一些交互事件（注意與DOM事件的區分）。
      • 鼠標事件：
        API： sendEvent(mouseEventType[, mouseX, mouseY, button='left'])
        mouseEventtype可能的取值爲： 'mouseup'、 'mousedown'、 'mousemove'、'doubleclick'和 'click'，這個參數爲必須的。
        後兩個參數爲鼠標事件的座標位置。最後一個參數爲鼠標按鍵，只對須要按鍵的事件有效，默認爲 'left'，可能值爲 'right'、 'left'、 'middle'。
      • 鍵盤事件：
        API： sendEvent(keyboardEventType, keyOrKeys, [null, null, modifier])
        keyboardEventType可能的取值爲 'keyup'、 'keydown'、 'keypress'，第2個參數傳入一個鍵值或一個字符串。鍵值能夠經過 page.event.key來查詢調用。第三和第四個參數無效，第五個參數表示同時按下的修飾鍵。取值狀況以下：
        • 0: 未使用修飾鍵
        • 0x02000000: Shift鍵被按下
        • 0x04000000: Ctrl鍵被按下
        • 0x08000000: Alt鍵被按下

      看一個示例：

      JavaScript

      1	page . sendEvent ( 'keypress' , page . event . key . A , null , null , 0x02000000 | 0x08000000 ) ;

    • page.switchToFrame(frameName/framePosition)
      默認page對應的是frame，若是一個頁面中還有其餘frame，則能夠經過此方法切換page對應的frame。其餘相似的方法還有 switchToChildFrame()、 switchToParentFrame()、switchToFocusedFrame()、 switchToMainFrame()等，再也不贅述。
    • page.uploadFile(selector, file)
      頁面中經常會有上傳文件的操做，但phantom沒有界面，於是也就沒有辦法選擇文件上傳，經過此方法能夠模擬文件上傳操做。示例以下：
      JavaScript

      1	page . uploadFile ( 'input[name=image]' , '/path/to/some/photo.jpg' ) ;

    • 一些事件處理接口
      • page.onAlert：phantom沒有界面，因此也就不能處理alert窗口，但能夠經過此接口捕獲到alert。
      • page.onPrompt：相似的，phantom不能處理prompt窗口，經過這個接口能夠捕獲prompt。
      • page.onConfirm：相似的，phantom不能處理confirm窗口，經過這個接口能夠捕獲confirm。
      • page.onConsoleMessage：相似的，phantom不能顯示console窗口，經過這個接口能夠捕獲console消息。
        JavaScript

        1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

        var webPage = require ( 'webpage' ) ; var page = webPage . create ( ) ; page . onAlert = function ( msg ) {      console . log ( 'ALERT: ' + msg ) ; } ; page . onPrompt = function ( msg , defaultVal ) {      if ( msg === "What's your name?" ) {          return 'PhantomJS' ;      }      // 返回值就是prompt獲得的值      return defaultVal ; } ; page . onConfirm = function ( msg ) {      console . log ( 'CONFIRM: ' + msg ) ;      // 返回true至關於點擊「肯定」，返回false至關於點擊「取消」      return true ; } ; page . onConsoleMessage = function ( msg , lineNum , sourceId ) {      console . log ( 'CONSOLE: ' + msg + ' (from line #' + lineNum + ' in "' + sourceId + '")' ) ; } ;

      • page.onInitialized：在page建立後觸發。
      • page.onUrlChanged：在url發生變化時觸發。它接受新的url做爲參數。首次加載頁面，page.onUrlChanged是在 page.onInitialized以後觸發。
      • page.onNavigationRequested：若是在 page.navigationLocked中容許頁面跳轉，此接口才會有意義（參見 page.navigationLocked）。它接受4個參數，先看示例：
        JavaScript

        1 2 3 4 5 6

        page . onNavigationRequested = function ( url , type , willNavigate , main ) {        console . log ( 'Trying to navigate to: ' + url ) ;        console . log ( 'Caused by: ' + type ) ;        console . log ( 'Will actually navigate: ' + willNavigate ) ;        console . log ( 'Sent from the page\'s main frame: ' + main ) ; }

        • url表示要跳轉到的url
        • type表示產生跳轉的緣由，可能值有 'Undefined'、 'LinkClicked'、'FormSubmitted'、 'BackOrForward'、 'Reload'、 'FormResubmitted'、'Other'
        • willNavigate表示是否會跳轉，由 page.navigationLocked控制
        • main表示發生跳轉的是不是主frame，若是是主frame則爲true，若是爲其餘frame則爲false
      • page.onLoadStarted：在開始載入資源時觸發。
      • page.onLoadFinished：頁面全部資源載入完成後觸發。其實與 page.open()的回調函數等價。它接受一個參數 status，表示加載是否成功。參見 page.open()。
      • page.onClosing：當在phantom域調用 page.close()或page上下文調用window.close()時觸發。
      • page.onError： 此接口捕獲全部page上下文發生的javascript錯誤。參數是錯誤信息和調用堆棧，參見 phantom.onError。若是page不處理錯誤，那麼這些錯誤會冒泡到phantom的onError處理器。
      • page.onCreate：當page建立子窗口時觸發，例如在page上下文中使用window.open，可是子窗口再建立子窗口不會觸發此事件。
      • page.onResourceRequested：當頁面請求一個資源時觸發的事件，它接受兩個參數，第一個參數是 requestData對象，它有以下屬性：
        • id : 資源請求編號
        • method : http請求方法，get/post等
        • url：請求的URL
        • time : 一個Date object，包含響應接收的時間
        • headers : http頭部的信息列表

        第二個參數是 networkRequest實例，它包含3個方法：

        • abort()：中斷當前的請求。這樣作會觸發onResourceError
        • changeUrl(url)：改變當前請求的目標url
        • setHeader(key, value)：修改/添加http頭部信息
      • page.onResourceReceived：當一個資源請求的響應接收到後觸發此事件，它接受一個response對象，這個對象有以下屬性：
        • id : 資源請求編號
        • url：請求的URL
        • time : 一個Date object，包含響應接收的時間
        • headers : http頭部的信息列表
        • bodySize : 已接收到的數據大小（所有數據或已接收的部分數據）
        • contentType : 指定的內容類型
        • redirectURL : 若是是一個重定向響應，那麼此處是重定向到的url
        • stage : 「start」/ 「end」
        • status : http狀態碼，如：200
        • statusText : http狀態描述，如：OK
      • page.onResourceError：當資源加載失敗時，觸發此事件。它接收一個 resourceError對象，這個對象有以下屬性：
        • id：資源請求的編號
        • url：請求的URL
        • errorCode：錯誤代碼
        • errorString：錯誤信息

      可參考以下示例：

      JavaScript

      1 2 3 4

      page . onResourceError = function ( resourceError ) {      console . log ( 'Unable to load resource (#' + resourceError . id + 'URL:' + resourceError . url + ')' ) ;      console . log ( 'Error code: ' + resourceError . errorCode + '. Description: ' + resourceError . errorString ) ; } ;

      • page.onResourceTimeout：在講 page.settings時曾經提到過這個事件。若是設置了page.settings.resourceTimeout，而且資源在這個時間內沒有載入完成，則會觸發此事件，它接受一個 request對象，這個對象包含以下屬性：
        • id : 資源請求編號
        • method : http請求方法，get/post等
        • url：請求的URL
        • time : 一個Date object，包含響應接收的時間
        • headers : http頭部的信息列表
        • errorCode：錯誤代碼
        • errorString：錯誤信息

---

Child Process模塊

經過Child Process模塊，咱們能建立子進程，藉助 stdin、 stdout、 stderr來實現進程間通訊（很C++）。使用子進程可以作不少事情，如打印、發郵件、調用腳本或其餘程序（不侷限於javascript）。

要使用Child Process模塊，咱們須要在代碼中添加 require("child_process")。

 如下內容缺少文檔支持，並未通過充分測試，可能存在必定的理解誤差。這部分功能是極有用的，但願在項目中使用的時候注意測試。

 Child Process模塊自己應該也並徹底開發徹底。 spawn()、 execFile()可用， exec()和 fork()還沒有實現。

1. spawn(command, [args], [options])
   最基本的建立進程的方法。前兩個參數比較重要，例如如今想從phantom進程中運行一段nodejs腳本，腳本路徑爲 「main.js」，這個腳本接受一個參數，假定爲 「helloworld」，那麼若是想獲得這段腳本的運行結果應該怎麼作呢？參考下面的腳本：
   
   JavaScript

   1 2 3 4 5 6 7 8 9 10 11 12 13 14

   var spawn = require ( "child_process" ) . spawn ; child = spawn ( 'node' , [ 'main.js' , 'helloworld' ] ) ; child . stdout . on ( "data" , function ( data ) {      console . log ( "spawnSTDOUT:" , JSON . stringify ( data ) ) } ) ; child . stderr . on ( "data" , function ( data ) {      console . log ( "spawnSTDERR:" , JSON . stringify ( data ) ) } ) ; child . on ( "exit" , function ( code ) {      console . log ( "spawnEXIT:" , code ) } ) ; setTimeout ( function ( ) {      phantom . exit ( 0 ) } , 2000 ) ;

   
   其實 spawn()方法沒什麼神祕的，它就是運行第一個參數表示的命令，第二個參數就是這個命令的參數列表。因此若是要開啓一個新的phantom進程，第一個參數爲 phantom就行。一樣的道理，指定好程序的路徑或者是腳本語言解釋器的路徑，經過這個方法能夠作的事情不少。
   比較不方便的是，進程間的通訊只能經過 stdin、 stdout、 stderr來完成，調用 spawn()方法後，還須要對這些交互信息進行監聽，上面的例子中演示了監聽 stdout和 stderr的方法。
2. execFile(cmd, args, opts, cb)
   就像剛剛說的， spawn()方法稍微感受有點麻煩，使用 execFile()可以稍稍簡化上面的代碼。 execFile()的前三個參數與 spawn()的三個參數徹底同樣，不一樣的是它多了一個 cb回調函數，看一個例子就知道這個回調函數有什麼用了：
   
   JavaScript

   1 2 3 4 5 6 7 8 9

   var execFile = require ( "child_process" ) . execFile ; child = execFile ( 'node' , [ 'main.js' , 'helloworld' ] , null ,      function ( err , stdout , stderr ) {          console . log ( "execFileSTDOUT:" , JSON . stringify ( stdout ) )          console . log ( "execFileSTDERR:" , JSON . stringify ( stderr ) )      } ) ; setTimeout ( function ( ) {      phantom . exit ( 0 ) } , 2000 ) ;

   
   在 execFile()中，對 stdout、 stderr的監聽作了封裝，簡化了咱們的代碼，不過功能上與spawn()並沒有區別。

---

file system模塊

雖然與node.js中文件系統模塊名稱和調用方法（ require("fs")）同樣，但不得不說，phantom的文件系統模塊整體是比較簡單的，API很少但夠用，API也不一樣於node.js的異步回調風格，而是採用stream+同步的風格，濃濃的C++風味。在使用的時間請必定要注意與node.js的文件系統模塊作區分。

1. fs.open(path, mode/opts) File
   open()方法接受兩個參數，第一個參數是要打開的文件路徑，第二個參數後面還會見到，這裏統一說明。若是是字符串，則表明文件打開的模式，可選的有 'r'、 'w'、 'a/+'、'b'（read時僅支持 'b'）；若是是一個對象，則表示配置項，一共有兩個配置項，分別是mode和 charset， mode就是剛剛提到的打開模式， charset表示文件的編碼類型。參閱下面的示例：
   
   JavaScript

   1 2 3 4 5 6 7 8 9 10

   var fs = require ( "fs" ) ; var file = fs . open ( "main.js" , 'r' ) ; console . log ( file . read ( ) ) ; file . close ( ) ; file = fs . open ( "main.js" , 'a' ) ; file . write ( "123" ) ; file . close ( ) ; setTimeout ( function ( ) {      phantom . exit ( 0 ) } , 2000 ) ;

   
   對打開的文件，咱們能夠進行讀寫操做（具體使用與打開模式有關）。若是對一個文件執行了open，請別忘了在文件使用完成後，再對其執行close。
2. fs.read(path, mode/opts) String
   fs.read()方法對文件讀取作了封裝，沒必要關心文件的打開關閉，返回值爲文件內容。
3. fs.write(path, content, mode/opts)
   fs.write()方法對文件寫入作了封裝，沒必要關心文件的打開關閉。
4. 其餘API:
   • fs.size(path) Number：獲取文件大小
   • fs.copy(source, destination)：複製文件
   • fs.copyTree(source, destination)：複製目錄樹
   • fs.