Add separate README.md to phantom_shim (#252)

The PhantomShim specific readme should be a better explanation of
what phantom shim is and is not.
This commit is contained in:
Andrey Lushnikov 2017-08-14 10:13:48 -07:00 committed by GitHub
parent 13e0965407
commit 5154d72342
2 changed files with 21 additions and 8 deletions

View File

@ -131,14 +131,6 @@ Yes. Puppeteer runs Chromium in [headless mode](https://developers.google.com/we
Since Puppeteer's code is run by Node, it exists out-of-process to the controlled Chromium instance. This requires most of the API calls to be asynchronous to allow the necessary roundtrips to the browser. Since Puppeteer's code is run by Node, it exists out-of-process to the controlled Chromium instance. This requires most of the API calls to be asynchronous to allow the necessary roundtrips to the browser.
#### Q: What is the "Phantom Shim"?
To make sure Puppeteer's API is comprehensive, we built [PhantomShim](https://github.com/GoogleChrome/puppeteer/tree/master/phantom_shim) - a lightweight phantomJS script runner built atop of Puppeteer API. We run phantomJS tests against PhantomShim with an ultimate goal to pass them all.
To emulate PhantomJS which runs automation scripts in-process to the automated page, PhantomShim spawns [nested event loops](https://github.com/abbr/deasync). On practice, this might result in unpredictable side-effects and makes the shim unreliable, but this works pretty good for testing goals.
> **NOTE** It is strictly **not recommended** to use PhantomShim out in the wild.
#### Q: What is the difference between Puppeteer and Selenium / WebDriver? #### Q: What is the difference between Puppeteer and Selenium / WebDriver?
Selenium / WebDriver is a well-established cross-browser API that is useful for testing cross-browser support. Selenium / WebDriver is a well-established cross-browser API that is useful for testing cross-browser support.

21
phantom_shim/README.md Normal file
View File

@ -0,0 +1,21 @@
# PhantomShim
PhantomShim is a phantomJS script runner built atop of Puppeteer API.
### Q: Can I use PhantomShim to run my scripts?
No.
PhantomShim aims to pass PhantomJS tests rather then to be a valid PhantomJS script runner:
- PhantomShim shortcuts a lot of corners (e.g. [handling only a few keys](https://github.com/GoogleChrome/puppeteer/blob/4269f6a1bb0c2d1cc27a9ed1132017669c33a259/phantom_shim/WebPage.js#L75) that are necessary to pass tests).
- PhantomShim spawns [nested event loops](https://github.com/abbr/deasync) to emulate PhantomJS execution model. This might result in unpredictable side-effects, e.g. in [unexpected reenterability](https://github.com/GoogleChrome/puppeteer/blob/4269f6a1bb0c2d1cc27a9ed1132017669c33a259/phantom_shim/WebPage.js#L694).
### Q: What's the purpose of PhantomShim?
The goal is to prove comprehensiveness of Puppeteer API.
PhantomShim is built atop of Puppeteer API and is used to run PhantomJS tests.
Whenever PhantomShim can't implement certain capability to pass phantomJS test, Puppeteer API is improved to make it possible.
### Q: Are there plans to evolve PhantomShim into a real PhantomJS script runner?
No.
On the contrary, PhantomShim is likely to be removed from the Puppeteer repository as it passes all interesting PhantomJS tests.