From de1f9a0aadd30a2e2f524e516f4c0a0a9519d87e Mon Sep 17 00:00:00 2001 From: Laura Cressman Date: Tue, 10 Mar 2020 12:28:34 -0600 Subject: [PATCH] Update Add Assertions guide --- docs/docs/add_assertions.md | 86 ++++++++++++++----------------------- 1 file changed, 32 insertions(+), 54 deletions(-) diff --git a/docs/docs/add_assertions.md b/docs/docs/add_assertions.md index b5e6f2583..e96de7693 100644 --- a/docs/docs/add_assertions.md +++ b/docs/docs/add_assertions.md @@ -7,89 +7,67 @@ In this guide we show you how to add assertions to your tests. We assume that yo ## TL;DR -- [Use QA Wolf helpers](#use-qa-wolf-helpers) to create assertions: - -```js -it("can click input", async () => { - await browser.click(selectors[2]); - - // custom code starts - // verify that "Clear completed" text appears - const hasClearCompletedText = await browser.hasText("Clear completed"); - expect(hasClearCompletedText).toBe(true); - // custom code ends -}); -``` - - [Use the Playwright API](#use-the-playwright-api) to create assertions: ```js -it('can click "Clear completed" button', async () => { - await browser.click(selectors[3]); - - // custom code starts - // get current Playwright Page instance - const page = await browser.page(); - // wait until no more todo items appear - await page.waitFor(() => !document.querySelector(".todo-list li")); - // custom code ends +await page.waitFor(() => { + return document.body.innerText.includes('Clear completed'); }); ``` - The [interactive REPL](use_the_repl) lets you try out assertions while creating tests -## Use QA Wolf helpers +## Use the Playwright API In this guide, we'll add assertions to a test on [TodoMVC](http://todomvc.com/examples/react). You can add assertions as you create your test, since the [test code is generated](create_a_test#review-test-code) as you use your application. The [interactive REPL](use_the_repl) can be helpful in trying out code. -The first assertion we will add is to check that the text `"Clear completed"` appears after we complete our todo. +The first assertion we will add is to check that the text `"Clear completed"` appears after we complete our todo. We'll do this using Playwright's [`page.waitFor` method](https://github.com/microsoft/playwright/blob/master/docs/api.md#framewaitforselectororfunctionortimeout-options-args), which waits for the specified function to return `true`. Specifically, we will pass it a function that waits until the text `"Clear completed"` appears. -We'll use QA Wolf's [`browser.hasText` method](api/browser_context/has_text) to verify that the text appears. This method automatically waits for the given text to appear on the page. It returns `true` if the text is found, and `false` if the text does not appear before timing out. - -In our test code, let's update the following step where we click to complete the todo. We'll call `browser.hasText("Clear completed")`, assign the result to a variable called `hasClearCompletedText`, and assert that `hasClearCompletedText` is `true`. See [Jest documentation](https://jestjs.io/docs/en/expect) to learn more about assertions. +In our test code, let's call `page.waitFor`, passing it a function that returns whether the [`document.body`](https://developer.mozilla.org/en-US/docs/Web/API/Document/body)'s [`innerText`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText) includes `"Clear completed"`. Our test will wait until this funciton returns `true`. If the function never returns `true` before timing out, the test will fail. ```js -it("can click input", async () => { - await browser.click(selectors[2]); - +test('myFirstTest', async () => { + await qawolf.repl({ selectors }); + await page.goto('http://todomvc.com/examples/react'); + await page.click(selectors['0_what_needs_to_b_input']); + await page.type(selectors['1_what_needs_to_b_input'], 'create test!'); + await page.press(selectors['2_what_needs_to_b_input'], 'Enter'); + await page.click(selectors['3_input']); // custom code starts - // verify that "Clear completed" text appears - const hasClearCompletedText = await browser.hasText("Clear completed"); - expect(hasClearCompletedText).toBe(true); + await page.waitFor(() => { + return document.body.innerText.includes('Clear completed'); + }); // custom code ends + await page.click(selectors['4_button']); }); ``` If you run the test again (`npx qawolf test myTestName`), you'll see that it still passes. -See our [API documentation](api/table_of_contents) for a full list of QA Wolf helpers. - -## Use the Playwright API - -In addition to QA Wolf helpers, you also have full access to the [Playwright API](https://github.com/microsoft/playwright/blob/master/docs/api.md) and the [Jest API](https://jestjs.io/docs/en/expect) in your test code. - Next we'll add an assertion that our todo is no longer visible after we clear completed todos. In terms of the [DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model), this means that there should be no todo `li` elements under the todo `ul` with the [class](https://developer.mozilla.org/en-US/docs/Web/CSS/Class_selectors) `"todo-list"`. -The Playwright API provides a [method called `page.waitFor`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagewaitforselectororfunctionortimeout-options-args) that takes a predicate function and waits until the function returns `true`. We'll call this method, passing it a function to check that there are no todo items left on the page. +We'll call `page.waitFor`, passing it a function that returns `true` when no elements match the [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) `".todo-list li"`. We use the [`document.querySelector` method](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector) to check if an element matches our selector. -Putting it all together, after our test clicks the "Clear completed" button to clear completed todos, we will verify that the todos disappear from the page. We'll do this by: - -1. Calling [`browser.page`](api/browser_context/page) to get the current Playwright `Page` instance -2. Calling [`page.waitFor`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagewaitforselectororfunctionortimeout-options-args), passing it a function that checks to see that there are no elements that match the [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) `.todo-list li`. - -The last step of our test code now looks like this: +Our test now looks like this: ```js -it('can click "Clear completed" button', async () => { - await browser.click(selectors[3]); - +test('myFirstTest', async () => { + await qawolf.repl({ selectors }); + await page.goto('http://todomvc.com/examples/react'); + await page.click(selectors['0_what_needs_to_b_input']); + await page.type(selectors['1_what_needs_to_b_input'], 'create test!'); + await page.press(selectors['2_what_needs_to_b_input'], 'Enter'); + await page.click(selectors['3_input']); + // custom code starts + await page.waitFor(() => { + return document.body.innerText.includes('Clear completed'); + }); + // custom code ends + await page.click(selectors['4_button']); // custom code starts - // get current Playwright Page instance - const page = await browser.page(); - // wait until no more todo items appear - await page.waitFor(() => !document.querySelector(".todo-list li")); + await page.waitFor(() => !document.querySelector('.todo-list li')); // custom code ends }); ```