Add more explanation for page.evaluateHandle() #1867

yelisaveta · 2018-01-21T16:56:36Z

No description provided.

…ge.evaluateHandle

…eHandle methods

googlebot · 2018-01-21T16:56:41Z

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed, please reply here (e.g. I signed it!) and we'll verify. Thanks.

If you've already signed a CLA, it's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.
If your company signed a CLA, they designated a Point of Contact who decides which employees are authorized to participate. You may need to contact the Point of Contact for your company and ask to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the project maintainer to go/cla#troubleshoot. The email used to register you as an authorized contributor must be the email used for the Git commit.
In order to pass this check, please resolve this problem and have the pull request author add another comment and the bot will run again. If the bot doesn't comment, it means it doesn't think anything has changed.

yelisaveta · 2018-01-21T16:59:32Z

I signed it!

googlebot · 2018-01-21T16:59:35Z

CLAs look good, thanks!

ebidel · 2018-01-23T04:24:35Z

docs/api.md

@@ -695,22 +695,21 @@ List of all available devices is available in the source code: [DeviceDescriptor
 #### page.evaluate(pageFunction, ...args)
 - `pageFunction` <[function]|[string]> Function to be evaluated in the page context
 - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[Serializable]>> Resolves to the return value of `pageFunction`
+- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction` as a javascript-object


JavaScript object.

ebidel · 2018-01-23T04:26:57Z

examples/element-html.js

+
+  // to show the difference between two methods
+  console.log(`jsObject is NOT equal to jsHandle: ${jsObject !== jsHandle}`); // prints true
+  console.log(`jsObject is equal to jsHandle.jsonValue(): ${jsObject === (await jsHandle.jsonValue())}`); // prints true


Not sure if this is the best result to show int the demo, but I can't think of anything better.

Alternatively, this example might just be part of the docs?

Yea. I'm also thinking we should just have these snippets and explanation as part of the docs. It's a less compelling standalone demo.

Droped element-html.js file from examples.

yelisaveta · 2018-01-23T22:12:12Z

@ebidel please take a look now: I've removed the example file and moved it to the api.md.

ebidel · 2018-01-23T23:48:11Z

docs/api.md


+The only difference between `page.evaluate` and `page.evaluateHandler` is that `page.evaluate` returns JSON representation of the object and `page.evaluateHandler` returns in-page object (JSHandle):


evaluateHandler -> evaluateHandle on both of these.

ebidel · 2018-01-23T23:48:56Z

docs/api.md

-const aWindowHandle = await page.evaluateHandle(() => Promise.resolve(window));
-aWindowHandle; // Handle for the window object.
-```
+// returns JavaScript object


"returns a JSON object" to be consistent with your description.

ebidel · 2018-01-23T23:49:15Z

docs/api.md


+The only difference between `page.evaluate` and `page.evaluateHandler` is that `page.evaluate` returns JSON representation of the object and `page.evaluateHandler` returns in-page object (JSHandle):


returns JSON representation -> returns a JSON representation

yelisaveta · 2018-01-24T21:38:46Z

@ebidel I've updated the PR, please take a look. Thanks!

yelisaveta · 2018-01-28T21:03:24Z

Hi @ebidel @JoelEinbinder this PR is ready to be reviewed again, very quick one. Thanks.

aslushnikov

Thanks for working on this.

aslushnikov · 2018-02-13T21:53:04Z

docs/api.md

@@ -729,19 +728,26 @@ Shortcut for [page.mainFrame().evaluate(pageFunction, ...args)](#frameevaluatepa
 #### page.evaluateHandle(pageFunction, ...args)
 - `pageFunction` <[function]|[string]> Function to be evaluated in the page context
 - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[JSHandle]>> Resolves to the return value of `pageFunction`
+- returns: <[Promise]<[JSHandle]>> Promise which resolves to the return value of `pageFunction` as in-page object (JSHandle)


There are many evaluateHandle calls: page.evaluateHandle, frame.evaluateHandle and elementHandle.evaluateHandle. We try to keep documentation consistent between them all; so all the changes has to be mirrored there as well.

Cool, I will update there as well.

aslushnikov · 2018-02-13T21:55:42Z

docs/api.md

+
+// both lines below print true
+console.log(`jsObject is NOT equal to jsHandle: ${jsObject !== jsHandle}`);
+console.log(`jsObject is equal to jsHandle.jsonValue(): ${jsObject === (await jsHandle.jsonValue())}`);


I don't think this is actually the case: triple-equals checks for identity equality, which is not the case.

But identity equality (aka strict equality) means that type and values are the same. In this case it shows that jsObject is the same type and value as jsHandle.jsonValue().

@yelisaveta in case of non-primitives, it means that two objects are the same by identity, not by value.

e.g.:

console.log({} === {}); // false let a = {}; let b = a; let c = a; console.log(b === c); // true

Sorry for a delay - I've now understood why I used strict equality check - initially I've created an example to demonstrate the difference between these two methods, see here: 53ae964

Examples were using pageFunction which returned element.innterHTML - which is a String. That's why strict equality worked correctly for me.

I see that having these snippets in the docs without the pageFunction definition looks confusing.

aslushnikov · 2018-02-13T21:56:46Z

docs/api.md

+const jsHandle = await page.evaluateHandle(pageFunction, elementHandle);
+
+// both lines below print true
+console.log(`jsObject is NOT equal to jsHandle: ${jsObject !== jsHandle}`);


I'd drop this console.log – even two consecutive page.evaluate will result in strict equality failing as well:

const jsObject1 = await page.evaluate(pageFunction, elementHandle); const jsObject2 = await page.evaluate(pageFunction, elementHandle); console.log(jsObject1 === jsObject2); // false, unless pageFunction returns primitives

Good point, agree.

Same as my comment above - it was working for me since I was using the pageFunction that returns element.innterHTML.

…eHandle. Synced updates for page, frame and context

yelisaveta · 2018-02-19T22:13:16Z

@aslushnikov PR has been updated, please take a look. Thank you.

yelisaveta added 4 commits January 21, 2018 16:38

docs(examples/element-html) add example that uses page.evalute and pa…

53ae964

…ge.evaluateHandle

docs(api.md) improve documentation for page.evaluate and page.evaluat…

62dc92e

…eHandle methods

fix(Page) fix jsdoc annotation for the evaluate method

6947ce2

docs(api.md) fix spelling mistake and revert minor formatting update

78d5b72

yelisaveta changed the title ~~Add more explanation for page.evaluateHandle() #1014~~ Add more explanation for page.evaluateHandle() Jan 21, 2018

yelisaveta mentioned this pull request Jan 21, 2018

Docs: more explanation for page.evaluateHandle() #1014

Closed

aslushnikov requested review from ebidel and JoelEinbinder January 23, 2018 00:12

ebidel suggested changes Jan 23, 2018

View reviewed changes

docs(api.md) add explanation on page.evaluate() vs page.evaluateHandle()

9dc7c54

Droped element-html.js file from examples.

ebidel suggested changes Jan 23, 2018

View reviewed changes

docs(api.md) fix spelling mistakes

15761e6

aslushnikov reviewed Feb 13, 2018

View reviewed changes

yelisaveta added 4 commits February 14, 2018 20:36

Merge branch 'master' of github.com:GoogleChrome/puppeteer

89b153e

docs(api.md) removed example comparing page.evaluate and page.evaluat…

e5616f7

…eHandle. Synced updates for page, frame and context

Merge branch 'master' of github.com:GoogleChrome/puppeteer

499236e

docs(api.md) minor syntax updates

fa77474

aslushnikov approved these changes Feb 22, 2018

View reviewed changes

aslushnikov merged commit 090590a into puppeteer:master Feb 22, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add more explanation for page.evaluateHandle() #1867

Add more explanation for page.evaluateHandle() #1867

yelisaveta commented Jan 21, 2018

googlebot commented Jan 21, 2018

yelisaveta commented Jan 21, 2018

googlebot commented Jan 21, 2018

ebidel Jan 23, 2018

ebidel Jan 23, 2018

yelisaveta Jan 23, 2018

ebidel Jan 23, 2018

yelisaveta commented Jan 23, 2018

ebidel Jan 23, 2018

ebidel Jan 23, 2018

ebidel Jan 23, 2018

yelisaveta commented Jan 24, 2018

yelisaveta commented Jan 28, 2018

aslushnikov left a comment

aslushnikov Feb 13, 2018

yelisaveta Feb 13, 2018

aslushnikov Feb 13, 2018

yelisaveta Feb 13, 2018

aslushnikov Feb 13, 2018

yelisaveta Feb 19, 2018

aslushnikov Feb 13, 2018

yelisaveta Feb 13, 2018

yelisaveta Feb 19, 2018

yelisaveta commented Feb 19, 2018


		The only difference between `page.evaluate` and `page.evaluateHandler` is that `page.evaluate` returns JSON representation of the object and `page.evaluateHandler` returns in-page object (JSHandle):

Add more explanation for page.evaluateHandle() #1867

Add more explanation for page.evaluateHandle() #1867

Conversation

yelisaveta commented Jan 21, 2018

googlebot commented Jan 21, 2018

yelisaveta commented Jan 21, 2018

googlebot commented Jan 21, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yelisaveta commented Jan 23, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yelisaveta commented Jan 24, 2018

yelisaveta commented Jan 28, 2018

aslushnikov left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yelisaveta commented Feb 19, 2018