Have ideas to improve npm?Join in the discussion! »

    expect-puppeteer
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/expect-puppeteer package

    5.0.3 • Public • Published

    expect-puppeteer

    Build Status version MIT License

    Assertion library for Puppeteer.

    npm install expect-puppeteer
    

    Usage

    Without Jest:

    import expect from 'expect-puppeteer'
    ;(async () => {
      const browser = await puppeteer.launch()
      const page = await browser.newPage()
      await page.goto('https://google.com')
      await expect(page).toMatch('google')
      await browser.close()
    })()

    Use with Jest

    To use with Jest, just modify your configuration:

    {
      "setupFilesAfterEnv": ["expect-puppeteer"]
    }

    Why do I need it

    Writing integration test is very hard, especially when you are testing a Single Page Applications. Data are loaded asynchronously and it is difficult to know exactly when an element will be displayed in the page.

    Puppeteer API is great, but it is low level and not designed for integration testing.

    This API is designed for integration testing:

    • It will wait for element before running an action
    • It adds additional feature like matching an element using text

    Example

    // Does not work if button is not in page
    await page.click('button')
    
    // Will try for 500ms to click on "button"
    await page.toClick('button')
    
    // Will click the first button with a "My button" text inside
    await page.toClick('button', { text: 'My button' })

    The first element to match will be selected

    Example

    <div class="outer">
      <div class="inner">some text</div>
    </div>
    // Will match outer div
    await expect(page).toMatch('div', { text: 'some text' })
    
    // Will match inner div
    await expect(page).toMatch('div.inner', { text: 'some text' })

    API

    Table of Contents

    expect(instance).toClick(selector[, options])

    Expect an element to be in the page or element, then click on it.

    await expect(page).toClick('button', { text: 'Home' })
    await expect(page).toClick({ type: 'xpath', value: '\\a' }, { text: 'Click' })

    expect(page).toDisplayDialog(block)

    Expect block function to trigger a dialog and returns it.

    const dialog = await expect(page).toDisplayDialog(async () => {
      await expect(page).toClick('button', { text: 'Show dialog' })
    })

    expect(instance).toFill(selector, value[, options])

    Expect a control to be in the page or element, then fill it with text.

    await expect(page).toFill('input[name="firstName"]', 'James')

    expect(instance).toFillForm(selector, values[, options])

    Expect a form to be in the page or element, then fill its controls.

    await expect(page).toFillForm('form[name="myForm"]', {
      firstName: 'James',
      lastName: 'Bond',
    })

    expect(instance).toMatch(matcher[, options])

    Expect a text or a string RegExp to be present in the page or element.

    • instance <Page|ElementHandle> Context
    • matcher <string|RegExp> A text or a RegExp to match in page
    • options <Object> Optional parameters
      • polling <string|number> An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values:
        • raf - to constantly execute pageFunction in requestAnimationFrame callback. This is the tightest polling mode which is suitable to observe styling changes.
        • mutation - to execute pageFunction on every DOM mutation.
      • timeout <number> maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. The default value can be changed by using the page.setDefaultTimeout(timeout) method.
    // Matching using text
    await expect(page).toMatch('Lorem ipsum')
    // Matching using RegExp
    await expect(page).toMatch(/lo.*/)

    expect(instance).toMatchElement(selector[, options])

    Expect an element be present in the page or element.

    • instance <Page|ElementHandle> Context
    • selector <string> A selector to match element
    • options <Object> Optional parameters
      • polling <string|number> An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values:
        • raf - to constantly execute pageFunction in requestAnimationFrame callback. This is the tightest polling mode which is suitable to observe styling changes.
        • mutation - to execute pageFunction on every DOM mutation.
      • timeout <number> maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. The default value can be changed by using the page.setDefaultTimeout(timeout) method.
      • text <string|RegExp> A text or a RegExp to match in element textContent.
      • visible <boolean> wait for element to be present in DOM and to be visible, i.e. to not have display: none or visibility: hidden CSS properties. Defaults to false.
    // Select a row containing a text
    const row = await expect(page).toMatchElement('tr', { text: 'My row' })
    // Click on the third column link
    await expect(row).toClick('td:nth-child(3) a')

    expect(instance).toSelect(selector, valueOrText)

    Expect a select control to be present in the page or element, then select the specified option.

    await expect(page).toSelect('select[name="choices"]', 'Choice 1')

    expect(instance).toUploadFile(selector, filePath)

    Expect a input file control to be present in the page or element, then fill it with a local file.

    import path from 'path'
    
    await expect(page).toUploadFile(
      'input[type="file"]',
      path.join(__dirname, 'file.txt'),
    )

    {type: string, value: string}

    An object used as parameter in order to select an element.

    • type <"xpath"|"css"> The type of the selector
    • value <string> The value of the selector
    {type:'css', value:'form[name="myForm"]'}
    {type:'xpath', value:'.\\a'}

    Configure default options

    To configure default options like timeout, expect-puppeteer exposes two methods: getDefaultOptions and setDefaultOptions. You can find available options in Puppeteer page.waitForFunction documentation. Default options are set to: { timeout: 500 }.

    import { setDefaultOptions } from 'expect-puppeteer'
    
    setDefaultOptions({ timeout: 1000 })

    License

    MIT

    Install

    npm i expect-puppeteer

    DownloadsWeekly Downloads

    178,864

    Version

    5.0.3

    License

    MIT

    Unpacked Size

    44.2 kB

    Total Files

    18

    Last publish

    Collaborators

    • avatar
    • avatar