From 0a1f77021449fe9f2ec1011c4dfb1b95ed2190ff Mon Sep 17 00:00:00 2001 From: Julie Ralph Date: Tue, 23 Dec 2014 17:28:20 -0800 Subject: [PATCH] docs(debugging): add information on using browser.pause Closes #1621 --- docs/debugging.md | 92 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 77 insertions(+), 15 deletions(-) diff --git a/docs/debugging.md b/docs/debugging.md index cc27c2994..7e886cf79 100644 --- a/docs/debugging.md +++ b/docs/debugging.md @@ -27,12 +27,78 @@ This test suite shows various types of failure: - Expectation Failure - Shows what a normal expectation failure looks like. + +Timeouts +-------- + +There are several ways that Protractor can time out. See the [Timeouts](/docs/timeouts.md) +reference for full documentation. + + Pausing to Debug ---------------- -Protractor allows you to pause your test at any point and interact with the -browser. To do this insert `browser.debugger();` into your test where you want -to break: +Protractor supports two methods for pausing to debug - `browser.pause()` and +`browser.debugger()`. You probably want to use `browser.pause()`, unless you +would like precise control over the node debugger. + +**Using pause** + +Insert `browser.pause()` into your test where you want to pause. + +```js +it('should fail to find a non-existent element', function() { + browser.get('app/index.html#/form'); + + browser.pause(); + + // This element doesn't exist, so this fails. + var nonExistant = element(by.binding('nopenopenope')).getText(); +}); +``` + +Run your tests normally. + +`protractor failureConf.js` + +The test will pause execution after the scheduled navigation to `app/index.html#/form` +but before trying to get text from the nonnexistant element. The terminal will +print instructions for continuing or inspecting the application and a list of the +currently pending tasks on the WebDriver control flow. + +``` +-- WebDriver control flow schedule + |- waiting for debugger to attach + |--- at [object Object]. (failure_spec.js:13:13) + |- Protractor.waitForAngular() + |--- at [object Object]. (failure_spec.js:16:59) +wd-debug> +``` + +Enter `c` to move the test forward by one task. +Enter `repl` to enter interactive mode. In interactive mode, you can send +WebDriver commands to your browser. The resulting value or error will +be reported to the terminal. + +``` +> element(by.binding('nopenopenope')).getText() +NoSuchElementError: No element found using locator: by.binding("nopenopenope") +> +> element(by.binding('user')).getText() +'Anon' +``` + +While the test is paused you may also interact with the browser. Note that +if you open the Chrome Dev Tools, you must close them before continuing +the test because ChromeDriver cannot operate when the Dev Tools are open. + +When you finish debugging, exit by pressing `Ctrl-C`. Your tests will continue +where they left off, using the same browser. + + +**Using debugger** + +Insert `browser.debugger();` into your test where you want to break: ```javascript it('should fail to find a non-existent element', function() { @@ -45,17 +111,17 @@ it('should fail to find a non-existent element', function() { browser.debugger(); // This element doesn't exist, so this fails. - var nonExistant = element(by.binding('nopenopenope')); + var nonExistant = element(by.binding('nopenopenope')).getText(); }); ``` -Then run the test in debug mode: +Then run the test _in debug mode_: ``` protractor debug debugging/failureConf.js ``` -This example uses the [node debugger](http://nodejs.org/api/debugger.html). Enter +This uses the [node debugger](http://nodejs.org/api/debugger.html). Enter `c` to start execution and continue after the breakpoint. We use `browser.debugger();` instead of node's `debugger;` statement so that @@ -127,12 +193,14 @@ To get a list of functions you can call, try: Typing tab at a blank prompt will fill in a suggestion for finding elements. + Taking Screenshots ------------------ -WebDriver can snap a screenshot with `browser.takeScreenshot()`. -This returns a promise which will resolve to the screenshot as a base-64 -encoded PNG. +WebDriver can snap a screenshot with `browser.takeScreenshot()`. This can be a +good way to help debug tests, especially for tests that run on a continuous integration +server. The method returns a promise which will resolve to the screenshot as a +base-64 encoded PNG. Sample usage: ``` javascript @@ -156,9 +224,3 @@ browser.takeScreenshot().then(function (png) { writeScreenShot(png, 'exception.png'); }); ``` - -Timeouts --------- - -There are several ways that Protractor can time out. See the [Timeouts](/docs/timeouts.md) -reference for full documentation.