test(ElementHandle.boxModel): remake test to make it more readable (#2287)

This patch:
- re-makes test for EH.boxModel to make it more readable
- slightly changes wording in the `docs/api.md`.

References #1357.

docs/api.md

@@ -2207,7 +2207,7 @@ This method returns the bounding box of the element (relative to the main frame)
   - width <[number]> Element's width.
   - height <[number]> Element's height.
 
-This method returns boxes of the element, or `null` if the element is not visible. Boxes are represented as an array of objects, {x, y} for each point, points clock-wise. See [getBoxModel](https://chromedevtools.github.io/devtools-protocol/tot/DOM#method-getBoxModel) for more details.
+This method returns boxes of the element, or `null` if the element is not visible. Boxes are represented as an array of points; each Point is an object `{x, y}`. Box points are sorted clock-wise.
 
 #### elementHandle.click([options])
 - `options` <[Object]>

test/assets/resetcss.html

@@ -0,0 +1,50 @@
+<style>
+/* http://meyerweb.com/eric/tools/css/reset/
+   v2.0 | 20110126
+   License: none (public domain)
+*/
+
+html, body, div, span, applet, object, iframe,
+h1, h2, h3, h4, h5, h6, p, blockquote, pre,
+a, abbr, acronym, address, big, cite, code,
+del, dfn, em, img, ins, kbd, q, s, samp,
+small, strike, strong, sub, sup, tt, var,
+b, u, i, center,
+dl, dt, dd, ol, ul, li,
+fieldset, form, label, legend,
+table, caption, tbody, tfoot, thead, tr, th, td,
+article, aside, canvas, details, embed,
+figure, figcaption, footer, header, hgroup,
+menu, nav, output, ruby, section, summary,
+time, mark, audio, video {
+	margin: 0;
+	padding: 0;
+	border: 0;
+	font-size: 100%;
+	font: inherit;
+	vertical-align: baseline;
+}
+/* HTML5 display-role reset for older browsers */
+article, aside, details, figcaption, figure,
+footer, header, hgroup, menu, nav, section {
+	display: block;
+}
+body {
+	line-height: 1;
+}
+ol, ul {
+	list-style: none;
+}
+blockquote, q {
+	quotes: none;
+}
+blockquote:before, blockquote:after,
+q:before, q:after {
+	content: '';
+	content: none;
+}
+table {
+	border-collapse: collapse;
+	border-spacing: 0;
+}
+</style>

test/elementhandle.spec.js

@@ -54,22 +54,58 @@ module.exports.addTests = function({testRunner, expect}) {
 
   describe('ElementHandle.boxModel', function() {
     it('should work', async({page, server}) => {
-      const leftTop = {x: 28, y: 260};
-      const rightTop = {x: 292, y: 260};
-      const rightBottom = {x: 292, y: 278};
-      const leftBottom = {x: 28, y: 278};
+      await page.goto(server.PREFIX + '/resetcss.html');
 
-      await page.setViewport({width: 500, height: 500});
-      await page.goto(server.PREFIX + '/frames/nested-frames.html');
-      const nestedFrame = page.frames()[1].childFrames()[1];
-      const elementHandle = await nestedFrame.$('div');
-      const box = await elementHandle.boxModel();
-      expect(box.content).toEqual([leftTop, rightTop, rightBottom, leftBottom]);
-      expect(box.padding).toEqual([leftTop, rightTop, rightBottom, leftBottom]);
-      expect(box.border).toEqual([leftTop, rightTop, rightBottom, leftBottom]);
-      expect(box.margin).toEqual([leftTop, rightTop, rightBottom, leftBottom]);
-      expect(box.height).toBe(18);
-      expect(box.width).toBe(264);
+      // Step 1: Add Frame and position it absolutely.
+      await utils.attachFrame(page, 'frame1', server.PREFIX + '/resetcss.html');
+      await page.evaluate(() => {
+        const frame = document.querySelector('#frame1');
+        frame.style = `
+          position: absolute;
+          left: 1px;
+          top: 2px;
+        `;
+      });
+
+      // Step 2: Add div and position it absolutely inside frame.
+      const frame = page.frames()[1];
+      const divHandle = (await frame.evaluateHandle(() => {
+        const div = document.createElement('div');
+        document.body.appendChild(div);
+        div.style = `
+          box-sizing: border-box;
+          position: absolute;
+          border-left: 1px solid black;
+          padding-left: 2px;
+          margin-left: 3px;
+          left: 4px;
+          top: 5px;
+          width: 6px;
+          height: 7px;
+        `;
+        return div;
+      })).asElement();
+
+      // Step 3: query div's boxModel and assert box values.
+      const box = await divHandle.boxModel();
+      expect(box.width).toBe(6);
+      expect(box.height).toBe(7);
+      expect(box.margin[0]).toEqual({
+        x: 1 + 4, // frame.left + div.left
+        y: 2 + 5,
+      });
+      expect(box.border[0]).toEqual({
+        x: 1 + 4 + 3, // frame.left + div.left + div.margin-left
+        y: 2 + 5,
+      });
+      expect(box.padding[0]).toEqual({
+        x: 1 + 4 + 3 + 1, // frame.left + div.left + div.marginLeft + div.borderLeft
+        y: 2 + 5,
+      });
+      expect(box.content[0]).toEqual({
+        x: 1 + 4 + 3 + 1 + 2, // frame.left + div.left + div.marginLeft + div.borderLeft + dif.paddingLeft
+        y: 2 + 5,
+      });
     });
 
     it('should return null for invisible elements', async({page, server}) => {