{"id":22825604,"url":"https://github.com/wlsf82/protractor-helper","last_synced_at":"2025-06-13T05:35:23.419Z","repository":{"id":25239503,"uuid":"103528892","full_name":"wlsf82/protractor-helper","owner":"wlsf82","description":"Write robust and flakiness-free tests with Protractor.","archived":false,"fork":false,"pushed_at":"2022-12-08T01:06:06.000Z","size":666,"stargazers_count":44,"open_issues_count":12,"forks_count":14,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-23T08:13:35.314Z","etag":null,"topics":["automation","e2e-testing","protractor","protractor-helper","testing"],"latest_commit_sha":null,"homepage":"https://wlsf82.github.io/protractor-helper/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wlsf82.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-14T12:23:24.000Z","updated_at":"2024-03-11T13:55:58.000Z","dependencies_parsed_at":"2023-01-14T02:22:52.977Z","dependency_job_id":null,"html_url":"https://github.com/wlsf82/protractor-helper","commit_stats":null,"previous_names":[],"tags_count":83,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wlsf82%2Fprotractor-helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wlsf82%2Fprotractor-helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wlsf82%2Fprotractor-helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wlsf82%2Fprotractor-helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wlsf82","download_url":"https://codeload.github.com/wlsf82/protractor-helper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250395286,"owners_count":21423400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","e2e-testing","protractor","protractor-helper","testing"],"created_at":"2024-12-12T17:11:32.552Z","updated_at":"2025-04-23T08:13:41.330Z","avatar_url":"https://github.com/wlsf82.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# protractor-helper\n\n[![npm version](https://badge.fury.io/js/protractor-helper.svg)](https://www.npmjs.com/package/protractor-helper) [![npm weekly downloads](https://img.shields.io/npm/dw/protractor-helper.svg)](https://www.npmjs.com/package/protractor-helper) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier) [![Build Status](https://github.com/wlsf82/protractor-helper/workflows/Continuous%20Integration/badge.svg)](https://github.com/wlsf82/protractor-helper/actions) [![license](https://img.shields.io/github/license/DAVFoundation/captain-n3m0.svg?style=flat-square)](./LICENSE) [![BCH compliance](https://bettercodehub.com/edge/badge/wlsf82/protractor-helper?branch=master)](https://bettercodehub.com/) [![Known Vulnerabilities](https://snyk.io/test/npm/protractor-helper/4.1.12/badge.svg)](https://snyk.io/test/npm/protractor-helper/4.1.12)\n\n\u003c/div\u003e\n\n🌏 [Portuguese](docs/PT-BR/README.md)\n\n---\n\nThis library contains helper functions that can be used together with Protractor for creating robust end-to-end tests.\n\nMany of the helper functions on this library uses `protractor.ExpectedConditions` to ensure that the elements we want to interact with are in the correct state before interacting with them or running expectations on them. This helps on avoiding trying to interact with elements when they are still not ready for it, which helps on avoiding test flakiness.\n\n## Summary\n\n- [Basic example](#basic-example)\n  - [Example without using the protractor-helper module](#example-without-using-the-protractor-helper-module)\n  - [Example using the protractor-helper module](#example-using-the-protractor-helper-module)\n- [Installation](#installation)\n- [How to use and examples](#how-to-use-and-examples)\n- [Available helpers](#available-helpers)\n\n  \u003cdetails\u003e\u003cp\u003e\u003csummary\u003eOpen to see all available helpers\u003c/summary\u003e\n\n  - [`setTimeout`](#settimeout)\n  - [`isCurrentUrlDifferentFromBaseUrl`](#iscurrenturldifferentfrombaseurl)\n  - [`waitForAlertToBePresent`](#waitforalerttobepresent)\n  - [`waitForElementPresence`](#waitforelementpresence)\n  - [`waitForElementNotToBePresent`](#waitforelementnottobepresent)\n  - [`waitForElementVisibility`](#waitforelementvisibility)\n  - [`waitForElementNotToBeVisible`](#waitforelementnottobevisible)\n  - [`click`](#click)\n  - [`hoverAndClick`](#hoverAndClick)\n  - [`fillFieldWithText`](#fillfieldwithtext)\n  - [`fillFieldWithTextAndPressEnter`](#fillfieldwithtextandpressenter)\n  - [`uploadFileIntoInputField`](#uploadfileintoinputfield)\n  - [`clear`](#clear)\n  - [`clearFieldAndFillItWithText`](#clearfieldandfillitwithtext)\n  - [`tap`](#tap)\n  - [`waitForTextToBePresentInElement`](#waitfortexttobepresentinelement)\n  - [`waitForTextNotToBePresentInElement`](#waitfortextnottobepresentinelement)\n  - [`waitForUrlToBeEqualToExpectedUrl`](#waitforurltobeequaltoexpectedurl)\n  - [`waitForUrlNotToBeEqualToExpectedUrl`](#waitforurlnottobeequaltoexpectedurl)\n  - [`waitForUrlToContainString`](#waitforurltocontainstring)\n  - [`waitForUrlNotToContainString`](#waitforurlnottocontainstring)\n  - [`scrollToElement`](#scrolltoelement)\n\n\u003c/p\u003e \u003c/details\u003e\n\n- [Using methods that start with 'wait' as test expectations (or test assertions)](#using-methods-that-start-with-wait-as-test-expectations-or-test-assertions)\n\n  - [Example of a test failure when using such methods as expectations](#example-of-a-test-failure-when-using-such-methods-as-expectations)\n\n- [External resources](#external-resources)\n- [Contributing](#contributing)\n- [Code of conduct](#code-of-conduct)\n- [Credits](#credits)\n- [License](/LICENSE)\n\n## Basic example\n\nLet's say you want to create a test for the sign in happy path of an example application.\n\n### Example without using the protractor-helper module\n\nWithout this library the test could be written as something like this:\n\n```js\nconst EC = protractor.ExpectedConditions;\nconst DEFAULT_TIMEOUT_IN_MS = 5000;\n\ndescribe(\"Sign in page\", () =\u003e {\n  it(\"successful sign in\", () =\u003e {\n    browser.get(\"https://example.com/sign-in\");\n\n    const emailField = element(by.id(\"email\"));\n    const passwordField = element(by.id(\"password\"));\n    const signinButton = element(by.id(\"signin\"));\n\n    browser.wait(EC.visibilityOf(emailField), DEFAULT_TIMEOUT_IN_MS);\n    browser.wait(EC.visibilityOf(passwordField), DEFAULT_TIMEOUT_IN_MS);\n    browser.wait(EC.elementToBeClickable(signinButton), DEFAULT_TIMEOUT_IN_MS);\n    emailField.sendKeys(\"valid@email.com\");\n    passwordField.sendKeys(\"validpassword\");\n    signinButton.click();\n\n    const avatar = element(by.id(\"avatar\"));\n\n    browser.wait(EC.visibilityOf(avatar), DEFAULT_TIMEOUT_IN_MS);\n\n    expect(avatar.isDisplayed()).toBe(true);\n  });\n});\n```\n\n### Example using the protractor-helper module\n\nThe same test could be written as below, using the protractor-helper library.\n\n```js\nconst protractorHelper = require(\"protractor-helper\");\n\ndescribe(\"Sign in page\", () =\u003e {\n  it(\"successful sign in\", () =\u003e {\n    browser.get(\"https://example.com/sign-in\");\n\n    const emailField = element(by.id(\"email\"));\n    const passwordField = element(by.id(\"password\"));\n    const signinButton = element(by.id(\"signin\"));\n\n    protractorHelper.fillFieldWithText(emailField, \"valid@email.com\");\n    protractorHelper.fillFieldWithText(passwordField, \"validpassword\");\n    protractorHelper.click(signinButton);\n\n    const avatar = element(by.id(\"avatar\"));\n\n    protractorHelper.waitForElementVisibility(avatar);\n  });\n});\n```\n\nAs you can see, by using the protractor-helper library the code is easier to read. Also, there is no need of unnecessary complexity.\n\n## Installation\n\nBelow it is described the process of Installation of such module.\n\nRun `npm install protractor-helper --save-dev` to install the library as a dev dependency of your project.\n\n## How to use and examples\n\nAfter installing the library you will need to require it in your test file (see below).\n\n```js\n// foobar.spec.js\n\nconst protractorHelper = require(\"protractor-helper\");\n```\n\nAs soon as you have the library required in your test file you can start using its helper methods.\n\n[Here you'll find examples of usage of each of the available helper methods.](docs/EXAMPLES.md#examples)\n(Important: read the notes on the top)\n\n## Available helpers\n\nBelow is the list of all available helpers in this library with your respective example:\n\n### `setTimeout`\n\nThis method allows to change the timeout duration of all `protractor-helper` methods called below `setTimeout`.\n\nThe `timeoutInMilliseconds` default is 5000 milliseconds\n\nIf called without passing an argument the timeout will be set to the default one.\n\n\u003e An example of using this method is the need to ensure the screen loads within up to XX seconds, due to the request of the product management. This commonly occurs in ecommerce systems on special dates, such as Black Friday.\n\n[Example](docs/EXAMPLES.md#settimeout)\n\n### `isCurrentUrlDifferentFromBaseUrl`\n\nThis method returns a boolean depending if the current url is different from the base url. No argument needed.\n[Example](docs/EXAMPLES.md#iscurrenturldifferentfrombaseurl)\n\n### `waitForAlertToBePresent`\n\nThis method waits for an alert to be present on the page.\n[Example](docs/EXAMPLES.md#waitforalerttobepresent)\n\n### `waitForElementPresence`\n\nThis method waits for an element to be present in the DOM.\n\n\u003e Note: An element may be present but not displayed. If you want to wait for the element to be displayed use the method `waitForElementVisibility`.\n\n[Example](docs/EXAMPLES.md#waitforelementpresence)\n\n### `waitForElementNotToBePresent`\n\nThis method is the opposite of the previous one, so, it waits for an element not to be present in the DOM.\n[Example](docs/EXAMPLES.md#waitforelementnottobepresent)\n\n### `waitForElementVisibility`\n\nThis method waits for an element to be visible in the page. Being displayed means not only that the element is present in the DOM, but also that is has a height and width that is greater than 0.\n[Example](docs/EXAMPLES.md#waitforelementvisibility)\n\n### `waitForElementNotToBeVisible`\n\nThis method is the opposite of the previous one, so, it waits for an element not to be visible in the page. By saying not being displayed means that the element may be in the DOM, but not visible.\n[Example](docs/EXAMPLES.md#waitforelementnottobevisible)\n\n### `click`\n\nThis method is used to click in an element as soon as it is in a clickable state. This means that the element is visible and enabled for clicking.\n[Example](docs/EXAMPLES.md#click)\n\n### `hoverAndClick`\n\nThis method is used to hover over an element as soon as it is present in the DOM, and then click on it.\n[Example](docs/EXAMPLES.md#hoverAndClick)\n\n### `fillFieldWithText`\n\nThis method fills an input field with a text as soon as such field is visible.\n[Example](docs/EXAMPLES.md#fillFieldWithText)\n\n### `fillFieldWithTextAndPressEnter`\n\nThis method fills an input field with a text as soon as such field is visible and then it simulates pressing the ENTER key from the keyboard. This method is useful in cases such as when doing a search and pressing the ENTER key, instead of having to fill the input field and clicking the search button, for example.\n[Example](docs/EXAMPLES.md#fillFieldWithTextAndPressEnter)\n\n### `uploadFileIntoInputField`\n\nThis method uploads a file in a file input field as soon as the file input field is present in the DOM.\n[Example](docs/EXAMPLES.md#uploadFileIntoInputField)\n\n### `clear`\n\nThis method clears a text input field as soon as such field is visible.\n[Example](docs/EXAMPLES.md#clear)\n\n### `clearFieldAndFillItWithText`\n\nThis method clears a text input field as soon as such field is visible, and then it fills it with a text.\n[Example](docs/EXAMPLES.md#clearFieldAndFillItWithText)\n\n### `tap`\n\nThis method performs a tap action on a clickable/tappable HTML element as soon as it is in a clickable/tappable state. This method is used when performing web mobile testing in mobile emulators, for example.\n[Example](docs/EXAMPLES.md#tap)\n\n### `waitForTextToBePresentInElement`\n\nThis method waits for a specific text to be present in a specific HTML element.\n[Example](docs/EXAMPLES.md#waitfortexttobepresentinelement)\n\n### `waitForTextNotToBePresentInElement`\n\nThis method is the opposite of the previous one, so, it waits for a specific text not to be present in a specific HTML element.\n[Example](docs/EXAMPLES.md#waitfortextnottobepresentinelement)\n\n### `waitForUrlToBeEqualToExpectedUrl`\n\nThis method waits for the URL to be equal to an expected URL. Such method is useful when you want to continue performing actions on elements only when in the correct URL.\n[Example](docs/EXAMPLES.md#waitforurltobeequaltoexpectedurl)\n\n### `waitForUrlNotToBeEqualToExpectedUrl`\n\nThis method waits for the URL not to be equal to an expected URL. Such method is useful when you want to continue performing actions on elements only when not in a specific URL.\n[Example](docs/EXAMPLES.md#waitforurlnottobeequaltoexpectedurl)\n\n### `waitForUrlToContainString`\n\nThis method waits for the URL to contain an expected string. Such method is useful when you want to perform verifications based on the current URL.\n[Example](docs/EXAMPLES.md#waitforurltocontainstring)\n\n### `waitForUrlNotToContainString`\n\nThis method waits for the URL not to contain an expected string. Such method is useful when you want to perform verifications based on the current URL.\n[Example](docs/EXAMPLES.md#waitforurlnottocontainstring)\n\n### `scrollToElement`\n\nThis method is used to scroll up to an element on the page as soon as the element is visible in the DOM.\n[Example](docs/EXAMPLES.md#scrollToElement)\n\n## Using methods that start with 'wait' as test expectations (or test assertions)\n\nSome of the available methods in this library can be used as test expectations, meaning that when using them you don't necessarily need to add an explicit expectation, such as something like this: `expect(avatar.isDisplayed()).toBe(true);`.\n\nBy using the `protractor-helper` library this could be implicit, like this: `protractorHelper.waitForElementVisibility(avatar);`. Here, implicit means that if the function `waitForElementVisibility(avatar)` has passed, it means that the element is visible, in other words, the element is displayed.\n\nBelow you can find the list of methods that can be used as expectations:\n\n- `waitForElementPresence(element)`\n- `waitForElementNotToBePresent(element)`\n- `waitForElementVisibility(element)`\n- `waitForElementNotToBeVisible(element)`\n- `waitForTextToBePresentInElement(element, text)`\n- `waitForTextNotToBePresentInElement(element, text)`\n- `waitForUrlToBeEqualToExpectedUrl(expectedUrl)`\n- `waitForUrlNotToBeEqualToExpectedUrl(expectedUrl)`\n- `waitForUrlToContainString(string)`\n- `waitForUrlNotToContainString(string)`\n\n\u003e Note: if you use such methods as expectations they will not count as expectations, in a test report, for example, but if they fail a clear message will be shown to ease understanding why the test has failed. In the end, test reports are usually useful in cases where tests have failed and we need to understand why. If all tests are green there is nothing to worry about, at least not if they were well implemented.\n\n### Example of a test failure when using such methods as expectations\n\nLet's look how a failure would looks like when using some of this methods as expectations.\n\n- Failure when using `waitForElementPresence` as expectation:\n\n```sh\nFailed: element with locator 'By(css selector, *[id=\"foo\"])' is not present.\n```\n\n- Failure when using `waitForElementVisibility` as expectation:\n\n```sh\nFailed: element with locator 'By(css selector, *[id=\"foo\"])' is not visible.\n```\n\n- Failure when using `waitForTextToBePresentInElement` as expectation:\n\n```sh\nFailed: text 'foo' not present on element with locator 'By(css selector, h1)'.\n```\n\n\u003e As you can see, the messages are clear and tell you exactly why the test has failed, such as in the previous example, where a specific text ('foo') is not present in a heading element (an element with css selector 'h1').\n\n## External resources\n\nHere we list some external resources such as blog posts that mention (or use) the protractor-helper library.\n\n- [Launch of protractor-helper v4 - Breaking changes](https://medium.com/@walmyrlimaesilv/launch-of-protractor-helper-v4-d038bcc18560)\n- [Release of protractor-helper version 4.1.1 - Types definitions in the functions’ signatures](https://medium.com/p/release-of-protractor-helper-version-4-1-1-f770bbf362ff?source=email-375212fd9a4a--writer.postDistributed\u0026sk=8e49d93b3ab575a9476ef94fecc2984f)\n- [Why you shouldn't use sleeps in automated tests](https://talkingabouttesting.com/2017/11/20/por-que-nao-se-deve-utilizar-sleeps-em-testes-automatizados/) (PT-BR)\n- [A simplified version of Page Objects for your Protractor tests](https://dev.to/walmyrlimaesilv/a-simplified-version-of-page-objects-for-your-protractor-tests-31ed)\n\n## Contributing\n\nSee [contribution guidelines](docs/CONTRIBUTING.md).\n\n## Code of conduct\n\nCheckout the [code of conduct](./CODE_OF_CONDUCT.md).\n\n## Credits\n\nThe **protractor-helper** library was created by [Walmyr Filho](https://walmyr.dev) and is kept together with [Paulo Gonçalves](https://www.linkedin.com/in/paulo-goncalves/).\n\nFollow them on Twitter ([@walmyrlimaesilv](https://twitter.com/walmyrlimaesilv) and [@paulorgoncalves](https://twitter.com/paulorgoncalves).)\n\nThanks also to [Lucas Amaral](https://www.linkedin.com/in/lopesdoamaral/), [Michiel Cuijpers](https://github.com/MichielCuijpers), [Ghazi Khan](https://codewithghazi.com/), [Pedro Hyvo](https://www.linkedin.com/in/pedrohyvo/), [Urvi Koladiya](https://github.com/cp-urvi-k), and [Zidrex Andag](https://www.linkedin.com/in/john-zidrex-andag-3285b31a7/) for contributing to the project.\n\n---\n\n[MIT License](/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwlsf82%2Fprotractor-helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwlsf82%2Fprotractor-helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwlsf82%2Fprotractor-helper/lists"}