<commit_before># What is this?

Protractor_sync builds on protractor and provides:

* Synchronous-style test writing (using fibers, behind the scenes)
* Polling mechanisms for testing asynchronous apps (polledExpect, elementFinder.waitUntil & .waitUntilRemoved, browser.waitFor)
* JQuery methods such as "hasClass", "closest", and "is"
* Automatic stale element re-selection (if a stale element is encountered, try to re-select it based on its original selector)
* Automatic blocked click retrying
* Chaining (elementFinder.clear().sendKeys('text'))

# Installation

Pre-reqs:

* Protractor (or something like grunt-protractor-runner, which includes it)
* asyncblock (`npm install asyncblock`)
* jasmine (Comes with protractor. Other frameworks can be used, but some features only work with jasmine)

`npm install protractor_sync`

In your code:

var protractorSync = require('protractor_sync');

protractorSync.patch();
protractorSync.disallowMethods({ expect: true });

# Example

```
var settings = element.findVisible('.settings'); //Finds exactly one visible element with a class of "settings"
settings.findVisible('input.start-date').clear().sendKeys('1/1/2000');
settings.findVisible('.save').scrollIntoView().click();

settings.waitUntilRemoved();

polledExpect(function() { return element.findVisible('div.start-date').getText(); }).toEqual('1/1/2000');
//With ES6/Typescript: polledExpect(() => element.findVisible('div.start-date').getText()).toEqual('1/1/2000');
```

See test/protractor_sync_test.ts for more examples.

# API

## element

* **findVisible(locator | selector)** - Finds a single visible instance of an element within this element. If more than one visible element matches the selector,
  an error is thrown. If no visible elements match the selector, an error is thrown. Implicitly waits until there is exactly one
  visible element.
* **findVisibles(locator | selector)** - Finds multiple visible elements on the page. If no visible elements match the selector, an error is thrown.
  Implicitly waits until at least one visible element is found.
* **findElement(locator | selector)** - Finds a single element on the page. If no elements match the selector, an error is thrown.
  Implicitly waits until exactly one element is found.
* **findElements(locator | selector)** - Finds multiple elements on the page. If no elements match the selector, an error is thrown.
  Implicitly waits until at least one element is found.
* **assertElementDoesNotExist(locator | selector)** - Asserts that no elements matching the selector exist. Throws an error if
  a matching element is found. This method does an immediate check for the element, and does not wait.

## ElementFinder (instance methods on element)

* **findVisible(locator | selector)** - Finds a single visible instance of an element within this element. If more than one visible element matches the selector,
  an error is thrown. If no visible elements match the selector, an error is thrown. Implicitly waits until there is exactly one visible element.
* **findVisibles(locator | selector)** - Finds multiple visible elements within this element. If no visible elements match the selector, an error is thrown.
  Implicitly waits until at least one visible element is found.
* **findElement(locator | selector)** - Finds a single element within this element. If no elements match the selector, an error is thrown.
  Implicitly waits until exactly one element is found.
* **findElements(locator | selector)** - Finds multiple elements within this element. If no elements match the selector, an error is thrown.
  Implicitly waits until at least one element is found.
* **assertElementDoesNotExist(locator | selector)** - Asserts that no elements matching the selector exist. Throws an error if a matching element is found.
  This method does an immediate check for the element, and does not wait.
* **waitUntil(condition)** - Waits until the condition is true (or times out if it doesn't become true before the implicit wait interval).
  The condition can be any JQuery selector, for example: ".ready", ":not(.ready)", ":focus", ":visible", ":enabled"
* **waitUntilRemoved()** - Waits until this element is removed from the DOM. If it is not removed from the DOM before the implicit wait interval,
  an error will occur.
* **closest(selector)** - Examines the current element and ancestor elements, and returns the first one which matches the selector.
* **hasClass(class)** - Determines whether the current element contains the specified class or not.
* **innerHeight()** - Get the computed inner height (including padding but not border) of the current element.
* **innerWidth()** - Get the computed inner width (including padding but not border) of the current element.
* **is(selector)** - Check the current element against a selector, return true if it matches the selector.
* **outerHeight()** - Get the computed height for the current element, including padding, border, and optionally margin.
* **outerWidth()** - Get the computed width for the current element, including padding, border, and optionally margin.
* **next(selector?)** - Get the immediately following sibling of the current element. If a selector is provided, it retrieves the next sibling only if it matches that selector.
* **offset()** - Get the coordinates of the current element relative to the document.
* **parent(selector?)** - Get the parent of the current element, optionally filtered by a selector.
* **parents(selector?)** - Get the ancestors of the current element, optionally filtered by a selector.
* **position()** - Get the coordinates of the current element, relative to the offset parent.
* **prev(selector?)** - Get the immediately preceding sibling of the current element, optionally filtered by a selector.
* **prop(name)** - Get the value of a property for the current element.
* **scrollLeft()** - Get the horizontal position of the scroll bar for the current element.
* **scrollTop()** - Get the vertical position of the scroll bar for the current element.
* **scrollIntoView()** - Scroll the page such that the top of the current element is at the top of the visible page.
* **getSelectionPath()** - Retrieves information about how the element was selected

## browser

* **waitFor(condition, waitTimeMS?)** - Waits for the condition function to return a truthy value. An exception will be raised if it times out.

## protractor_sync

* **IMPLICIT_WAIT_MS** - The amount of time to wait before timing out operations which wait implicitly. Note: An implicit wait
SHOULD NOT be set in selenium/protractor. Use this value instead. Default: 5 seconds.
* **RETRY_INTERVAL** - The amount of time to wait before retrying operations which wait. Default: 10ms.
* **CLICK_RETRY_INTERVAL** - The amount of time to wait before attempt to re-click a blocked element. Default: 200ms.
* **autoReselectStaleElements** - A boolean value indicating whether stale elements should be automatically re-selected or not.
* **autoRetryClick** - A boolean value indicating whether protractor_sync should attempt to automatically retry blocked clicks or not.
* **patch()** - Apply patches to protractor, allowing "synchronous-style" tests to be written. Should be called once before any tests have run.
* **disallowMethods(options)** - Restricts usage of underlying protractor methods, encouraging the use of protractor_sync and the Blackboard
  style of test writing. Pass { expect: true } to prevent the usage of "expect" (in favor of "polledExpect").
* **waitForNewWindow(action, waitTimeMs)** - Executes the action function, then waits for a new popup window to appear.
  The current window will be switched to the new window when it opens. Times out after waitTimeMs milliseconds.
* **polledExpect(func, waitTimeMs?)** - Works like jasmine's "expect", but retries the function until it passes or times out.
* **takeScreenshot(filename)** - Takes a screenshot and saves a .png file at the specified file path.
* **resizeViewport(size: { width?: number; height?: number; })** - Resize the viewport (not the window) to the specified size.

# Tips

* Do not set an implicit wait in protractor/selenium. Set protractorSync.IMPLICIT_WAIT_MS instead.
* Turn off protractor synchronization (browser.ignoreSynchronization = true;) for faster tests. You can also enable/disable it during portions of tests.
* Always use findVisible, except for special sitautions where you want to select a hidden element.
* If you must manually pass a waitTimeMS, set it as a multiple of the IMPLICIT_WAIT_TIME_MS so it will scale on slower machines.

# Grunt tasks

* `grunt develop` - Builds code and watches for changes
* `grunt tests` - Run the unit tests
* `grunt pre-commit` - Runs the linter and builds the code. Also copies the appropriate files into dist.
* `grunt update` - Gets the latest selenium webdriver and chromedriver

Note: tests/pre-commit task should be run only when protractor_sync is located outside node_modules folder. Otherwise
`disallow methods` tests will fail.

# How to update this project

* Make code changes (make sure you run `grunt pre-commit` to update the contents of "dist"), and create a PR / push changes
* Increment version # in package.json (use semantic versioning)
* Publish a tag with the version number (`git tag v0.0.1; git push --tags;`)
* (To use new version from another project, update reference in package.json to point to the new tag)
<commit_msg>make the update instructions more clear<commit_after># What is this?

Protractor_sync builds on protractor and provides:

* Synchronous-style test writing (using fibers, behind the scenes)
* Polling mechanisms for testing asynchronous apps (polledExpect, elementFinder.waitUntil & .waitUntilRemoved, browser.waitFor)
* JQuery methods such as "hasClass", "closest", and "is"
* Automatic stale element re-selection (if a stale element is encountered, try to re-select it based on its original selector)
* Automatic blocked click retrying
* Chaining (elementFinder.clear().sendKeys('text'))

# Installation

Pre-reqs:

* Protractor (or something like grunt-protractor-runner, which includes it)
* asyncblock (`npm install asyncblock`)
* jasmine (Comes with protractor. Other frameworks can be used, but some features only work with jasmine)

`npm install protractor_sync`

In your code:

var protractorSync = require('protractor_sync');

protractorSync.patch();
protractorSync.disallowMethods({ expect: true });

# Example

```
var settings = element.findVisible('.settings'); //Finds exactly one visible element with a class of "settings"
settings.findVisible('input.start-date').clear().sendKeys('1/1/2000');
settings.findVisible('.save').scrollIntoView().click();

settings.waitUntilRemoved();

polledExpect(function() { return element.findVisible('div.start-date').getText(); }).toEqual('1/1/2000');
//With ES6/Typescript: polledExpect(() => element.findVisible('div.start-date').getText()).toEqual('1/1/2000');
```

See test/protractor_sync_test.ts for more examples.

# API

## element

* **findVisible(locator | selector)** - Finds a single visible instance of an element within this element. If more than one visible element matches the selector,
  an error is thrown. If no visible elements match the selector, an error is thrown. Implicitly waits until there is exactly one
  visible element.
* **findVisibles(locator | selector)** - Finds multiple visible elements on the page. If no visible elements match the selector, an error is thrown.
  Implicitly waits until at least one visible element is found.
* **findElement(locator | selector)** - Finds a single element on the page. If no elements match the selector, an error is thrown.
  Implicitly waits until exactly one element is found.
* **findElements(locator | selector)** - Finds multiple elements on the page. If no elements match the selector, an error is thrown.
  Implicitly waits until at least one element is found.
* **assertElementDoesNotExist(locator | selector)** - Asserts that no elements matching the selector exist. Throws an error if
  a matching element is found. This method does an immediate check for the element, and does not wait.

## ElementFinder (instance methods on element)

* **findVisible(locator | selector)** - Finds a single visible instance of an element within this element. If more than one visible element matches the selector,
  an error is thrown. If no visible elements match the selector, an error is thrown. Implicitly waits until there is exactly one visible element.
* **findVisibles(locator | selector)** - Finds multiple visible elements within this element. If no visible elements match the selector, an error is thrown.
  Implicitly waits until at least one visible element is found.
* **findElement(locator | selector)** - Finds a single element within this element. If no elements match the selector, an error is thrown.
  Implicitly waits until exactly one element is found.
* **findElements(locator | selector)** - Finds multiple elements within this element. If no elements match the selector, an error is thrown.
  Implicitly waits until at least one element is found.
* **assertElementDoesNotExist(locator | selector)** - Asserts that no elements matching the selector exist. Throws an error if a matching element is found.
  This method does an immediate check for the element, and does not wait.
* **waitUntil(condition)** - Waits until the condition is true (or times out if it doesn't become true before the implicit wait interval).
  The condition can be any JQuery selector, for example: ".ready", ":not(.ready)", ":focus", ":visible", ":enabled"
* **waitUntilRemoved()** - Waits until this element is removed from the DOM. If it is not removed from the DOM before the implicit wait interval,
  an error will occur.
* **closest(selector)** - Examines the current element and ancestor elements, and returns the first one which matches the selector.
* **hasClass(class)** - Determines whether the current element contains the specified class or not.
* **innerHeight()** - Get the computed inner height (including padding but not border) of the current element.
* **innerWidth()** - Get the computed inner width (including padding but not border) of the current element.
* **is(selector)** - Check the current element against a selector, return true if it matches the selector.
* **outerHeight()** - Get the computed height for the current element, including padding, border, and optionally margin.
* **outerWidth()** - Get the computed width for the current element, including padding, border, and optionally margin.
* **next(selector?)** - Get the immediately following sibling of the current element. If a selector is provided, it retrieves the next sibling only if it matches that selector.
* **offset()** - Get the coordinates of the current element relative to the document.
* **parent(selector?)** - Get the parent of the current element, optionally filtered by a selector.
* **parents(selector?)** - Get the ancestors of the current element, optionally filtered by a selector.
* **position()** - Get the coordinates of the current element, relative to the offset parent.
* **prev(selector?)** - Get the immediately preceding sibling of the current element, optionally filtered by a selector.
* **prop(name)** - Get the value of a property for the current element.
* **scrollLeft()** - Get the horizontal position of the scroll bar for the current element.
* **scrollTop()** - Get the vertical position of the scroll bar for the current element.
* **scrollIntoView()** - Scroll the page such that the top of the current element is at the top of the visible page.
* **getSelectionPath()** - Retrieves information about how the element was selected

## browser

* **waitFor(condition, waitTimeMS?)** - Waits for the condition function to return a truthy value. An exception will be raised if it times out.

## protractor_sync

* **IMPLICIT_WAIT_MS** - The amount of time to wait before timing out operations which wait implicitly. Note: An implicit wait
SHOULD NOT be set in selenium/protractor. Use this value instead. Default: 5 seconds.
* **RETRY_INTERVAL** - The amount of time to wait before retrying operations which wait. Default: 10ms.
* **CLICK_RETRY_INTERVAL** - The amount of time to wait before attempt to re-click a blocked element. Default: 200ms.
* **autoReselectStaleElements** - A boolean value indicating whether stale elements should be automatically re-selected or not.
* **autoRetryClick** - A boolean value indicating whether protractor_sync should attempt to automatically retry blocked clicks or not.
* **patch()** - Apply patches to protractor, allowing "synchronous-style" tests to be written. Should be called once before any tests have run.
* **disallowMethods(options)** - Restricts usage of underlying protractor methods, encouraging the use of protractor_sync and the Blackboard
  style of test writing. Pass { expect: true } to prevent the usage of "expect" (in favor of "polledExpect").
* **waitForNewWindow(action, waitTimeMs)** - Executes the action function, then waits for a new popup window to appear.
  The current window will be switched to the new window when it opens. Times out after waitTimeMs milliseconds.
* **polledExpect(func, waitTimeMs?)** - Works like jasmine's "expect", but retries the function until it passes or times out.
* **takeScreenshot(filename)** - Takes a screenshot and saves a .png file at the specified file path.
* **resizeViewport(size: { width?: number; height?: number; })** - Resize the viewport (not the window) to the specified size.

# Tips

* Do not set an implicit wait in protractor/selenium. Set protractorSync.IMPLICIT_WAIT_MS instead.
* Turn off protractor synchronization (browser.ignoreSynchronization = true;) for faster tests. You can also enable/disable it during portions of tests.
* Always use findVisible, except for special sitautions where you want to select a hidden element.
* If you must manually pass a waitTimeMS, set it as a multiple of the IMPLICIT_WAIT_TIME_MS so it will scale on slower machines.

# Grunt tasks

* `grunt develop` - Builds code and watches for changes
* `grunt tests` - Run the unit tests
* `grunt pre-commit` - Runs the linter and builds the code. Also copies the appropriate files into dist.
* `grunt update` - Gets the latest selenium webdriver and chromedriver

Note: tests/pre-commit task should be run only when protractor_sync is located outside node_modules folder. Otherwise
`disallow methods` tests will fail.

# How to update this project

* Make code changes and run tests (`grunt tests`)
* Create a PR (make sure you run `grunt pre-commit` to update the contents of "dist", and include the updated dist files in your PR)
* Increment version # in package.json (use semantic versioning)
* After your PR is merged, publish a tag with the version number (E.g. `git tag v0.0.1; git push --tags;`)
* (To use the new version of protractor_sync in another project, update the protractor_sync reference in package.json to point to the new tag)

{'fraction_non_alphanumeric': 0.0846736045411542, 'fraction_numerical': 0.0029433406916850625, 'mean_word_length': 4.785041045910611, 'pattern_counts': {'":': 8, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2031720', 'n_tokens_mistral': 4908, 'n_tokens_neox': 4736, 'n_words': 2473}