minimally extended puppeteer for clutter-free test files. unit-tests below.

readme.md

pptr.reset

A single-file, copy/pastable extension for ironing out puppeteers weird as fuck API.

used to extend pptr and for decluttering our test files;

• copy/paste this in your tests, no need to npm install
• extend with own methods, specific to your tests

@nicholaswmin

The MIT License,
SPDIX: MIT

• DOM API-like map/filter of page.$$ results, easy access to almost all DOM element props/methods w/o the clunky page.evaluate calls.
• run tests from local paths, avoid dev. servers for tests.
• collects console messages.
• minimal, simple & self-encapsulated; use it as basis for more page extensions.
• robust test skipping if puppeteer isn't installed.

Usage:

note: The "skipping test" pattern, is documented at the bottom of this file.

import { puppeteer, extend } from './pptr-ext.js'

const browser = await puppeteer.launch()
const page = await extend(await browser.newPage())
page.path('./foo-element.html')

const sections = page.$$$('p').map(el => el.textContent)
const warnings = page.console.logs.map(l => l.type() === 'warn')

console.log(sections, warnings)

pptr.mixin.test.js

/* 

** IMPORTANT: This is rather pointless. The Locator API does most of the work replicated here **

Browser unit-tests for: `pptr.mixin.js`      
> in chrome ~~& firefox~~

The following should have beeen installed on `npm install`:

```bash
$ npm i puppeteer --no-save
$ npx puppeteer browsers install chrome

# ignore firefox for now, it fails on launch
$ npx puppeteer browsers install firefox
```

```bash
# run
node --run test 

# all browsers (same as above):
BROWSERS=chrome,firefox node --test

# pick browser, e.g. chrome-only:
BROWSERS=chrome node --test 

Important:
  - autocreates 2 test files at `process.env.TMPDIR`
  - test file generators defined at bottom of page
*/

import test from 'node:test'
import { mkdir, writeFile, rm } from 'node:fs/promises'
import { join, basename } from 'node:path'
import { puppeteer, extend } from './pptr.reset.js'

const tempdir  = join(import.meta.dirname, '.tmp')
const squashed = text => text.trim().toLowerCase()
const browsers = process.env.BROWSERS 
  ? process.env.BROWSERS.split(',').map(squashed)
  : ['chrome', 'firefox'].map(squashed)
const  { pptr, skip } = await puppeteer()

test('pptr.tool', { skip }, async t => {
  await testfiles.write(tempdir)

  for (const browser of browsers.map(squashed))
    await t.test(`Browser: ${browser}`, async t => {
      let app, page
      
      t.after(async () => {
        await app.close()
        await rm(join(import.meta.dirname, '.tmp'), { 
          recursive: true, force: true 
        })
      })

      t.before(async () => {
        app = await pptr.launch({ headless: false, browser })
        page = extend(await app.newPage())
        
        await page.path(join(tempdir, 'test.html'))
        await page.waitForFunction('window.done = true')
      })
    
      await t.test('loads local HTML files', async t => {
        await t.test('finds expected element', async t => {
          t.assert.ok(await page.waitForSelector('p'))
        })
        
        await t.test('inline-scripts run ok', async t => {
          await page.waitForFunction('window.done = true');
        })
        
        await t.test('external-scripts run ok', { skip: 'flaky' }, async t => {
          await page.addScriptTag({ url: join(tempdir, 'test.js') })
          await page.waitForSelector('#samplejs')
        })
      })
      
    
      await t.test('stores console messages', async t => {
        t.beforeEach(t => t.logs = page.console.logs.map(o => o.text()))
    
        await t.test('has expected message count', async t => {
          t.assert.ok(t.logs.length >= 3)
        })
        
        await t.test('stores various log type', async t => {
          await t.test('a console.log', async t => {
            t.assert.ok(t.logs.includes('i am a console.log'))
          })
          
          await t.test('a console.info', async t => {
            t.assert.ok(t.logs.includes('i am a console.info'))
          })
          
          await t.test('a console.warn', async t => {
            t.assert.ok(t.logs.includes('i am a console.warn'))
          })
          
          await t.test('resets on page load', async t => {
            await page.reload() && 
              await page.waitForFunction('window.done = true')
            t.assert.strictEqual(page.console.logs.length, 3)
          })
        })
      })
      
    
      await t.test('ElementHandle array-like methods', async t => {
        await t.test('ElementHandles.map(fn)', async t => {
          await t.test('maps to DOM element properties', async t => {
            const vals = await page.$$$('button').map(e => e.textContent)
    
            await t.test('with correct values', t => {
              t.assert.strictEqual(vals.length, 3, 'did not find all buttons')
              t.assert.deepStrictEqual(vals, ['say 1', 'say 2', 'say 3'])
            })
          })
          
          await t.test('maps to DOM element method result', async t => {
            const vals = await page.$$$('button').map(e => e.getAttribute('title'))
            await t.test('to correct values', t => {
              t.assert.strictEqual(vals.length, 3, 'did not find all buttons')
              t.assert.deepStrictEqual(vals, ['button 1', 'button 2', 'button 3'])
            })
          })
        })
    
        await t.test('ElementHandles.filter(fn)', async t => {
          t.beforeEach(async t => {
            t.vals = await page.$$$('button')
              .filter(el => ['button 1', 'button 2']
                .includes(el.getAttribute('title')))
          })
    
          await t.test('returns expected result count', async t => {
            t.assert.strictEqual(t.vals.length, 2, 'wrong result count')
          })
          
          await t.test('each of type: ElementHandle', async t => {
            t.vals.forEach(el => t.assert.ok(el.$$, 'item missing $$ method'))
          })
          
          await t.test('each the correct element handle', async t => {
            await Promise.all(t.vals.map(el => el.click()))
            const logs = page.console.logs.map(log => log.text())
    
            t.assert.ok(logs.includes('1'), 'missing expected button 1 log: "1"')
            t.assert.ok(logs.includes('2'), 'missing expected button 2 log: "2"')
          })
        })
      })
    })
  })


// test data files:
// -  index HTML 
// - creates a 10 l
// - autocreated, but we dont cleanup/remove.
// - do not de-indent
  
const testfiles = {
  write: async dir => { 
    console.info('writing test files to:', dir)

    await mkdir(dir, { recursive: true })
    await writeFile(`${dir}/test.html`,
      `<!DOCTYPE html>
  <html lang="en">
    <meta charset=utf-8 lang="en">
    <title>verification sample</title>
    <body>
      <p>unit-test verification sample.</p>
      <button title="button 1" onclick="say('1')">say 1</button>
      <button title="button 2" onclick="say('2')">say 2</button>
      <button title="button 3" onclick="say('3')">say 3</button>
      <script>
        window.say = text => console.log(text)
      
        window.addEventListener('load', () => {
          console.log('i am a console.log')
          console.info('i am a console.info')
          console.warn('i am a console.warn')
          
          window.done = true  
        })
      </script>
    </body>
  </html>
    `)
      
    await writeFile(`${dir}/test.js`,
      `// - tests if local HTML can load external JS, if yes, a span is added:
  document.body.innerHTML += '<span id="samplejs">sample.js</span>'`
    )
    await writeFile(`${dir}/README.md`,
      `--- testfiles ---
  folder/files auto-created by unit-tests at: ${basename(import.meta.url)},  
  and should have been auto-deleted. If found, they are safe to delete.
  `
    )
  }
}

pptr.reset.js

/* 
- Copy/paste this in your own project 
- Delete or add extension methods as needed. 

@nicholaswmin  
MIT License

> minifies to < 60 lines ~950 bytes
*/
import { pathToFileURL } from 'node:url'

const extend = page => Object.assign(page, {
  /* 
  all console messages are collected here:   
  saved in raw format, needs must `.map(l => l.text())` for test.
  (inc. warnings, errors etc.) 

  Usage:  
  - `console.log(page.console.logs.map(l => l.text()))`
  */
  console: { logs: [] },
  /* 
  Constructor-like, add more initializations here,   
  if needed 
  */  
  init: function() {
    this.on('domcontentloaded', () => this.console.logs = [])
    this.on('console', message => 
      this.console.logs.push(message))

    return this
  },
  /* 
  Like `page.goto(url)` but also works with local paths.   
  
  Make sure:  
  - path is an absolute path.  
  - you launched pptr with options: 
    `args: ['--allow-file-access-from-files']`
  */
  path: async function(url) {
    return await this.goto(url.startsWith('/') 
      ? pathToFileURL(url) : url)
  },
  
  _$: function(sel) {
  // @TODO add same ergonomics as `$$$` below
  // @REVIEW might be unencessary, the Locator API looks ok?
  },
  /* 
  Idiomatic element mapping/filtering.   
  i.e: `$$$('div p').map(o => o.getAttribute("style"))`

  - Same ergonomics as in-browser DOM API
  - For `map`/`filter` el handles to DOM props, **only**. 
    Otherwise use regular `$$`.
  - Caveat: No chaining. Can `.map`/`filter` once.
  */
  $$$: function(sel) {
    // ignore, utilities. 
    const elements = sel => this.$$(sel)
    const ridFalsy = arr => arr.filter(Boolean)
    const toValues = fn => el => this.evaluate(fn, el)
    const ifTruthy = fn => el => toValues(fn)(el).then(v => v ? el : false)
    return {
     /* Map handles to DOM properties/method results.
       - Can use as a `forEach` as well,
         - i.e: to `dispatchEvent` on all element handles.
       
       Usage:
       `await page.$$$('div p').filter(o => o.textContent)`
       or:
       `await page.$$$('div p').filter(o => o.getAttribute("style"))`*/
      map: async function(fn) {
        return Promise.all((await elements(sel))
          .map(toValues(fn), fn))
      },
      /*
      Returns filtered handles, not mapped properties.
        - To filter and also return mapped properties, use `.map` above
        and simply `filter` out in userland.
        Usage:
        `await page.$$$('div p').filter(o => o.getAttribute('style'))`
       */
      filter: async function(fn) {
        return Promise.all((await elements(sel))
          .map(ifTruthy(fn), fn))
          .then(ridFalsy)
      }
      
      // FlatMap?  `.map` from above and `filter` in your script. Same thing.
    }
  },
  // Add more extensions here...
}).init()

/*
Conditional test loader.  
A pattern for straightforward, robust & lightweight test runs.
Works with Node Test Runner (but easily integrates with anything else.)

NodeJS docs: See: https:*nodejs.org/api/test.html#skipping-tests

This loader can be used to conditionally run tests if puppeteer is 
installed. Otherwise the tests are *skipped*, instead of erroring-out,
with a relevant skip message.
Allows running rest of entire test suite, even non-browser tests with a 
simple `node --test`.

Usage:

Run this test file with `node --test foo.test.js`.  
- If puppeteer is not installed, it just skips the tests, oterwise
  it skips them.
- It passes `skip` to `test(title, skip...)`

```js
* foo.test.js
import test from 'node:test'
import { puppeteer, extend } from './pptr-ext.js'

const { pptr, skip } = await puppeteer()

test('these tests only run if pptr is installed', { skip }, async t => {
* -----------------------------------→ * set this -->|↑
  const browser = await pptr.launch()
  const page = await extend(await browser.newPage())
  
  t.after(() => browser.close())

  await t.test('foo test', t => {
    t.assert.ok('foo')
  })
  
  await t.test('bar test', t => {
    t.assert.ok('bar')
  })
  
  // ommited for brevity ...
})
```
*/
const puppeteer = async () => {
  try { 
    return { 
      pptr: await import('puppeteer'), skip: false 
    } 
  } catch(err) {
    if (!err.code.includes('MODULE_NOT_FOUND')) 
      throw err
    else console.warn(err.message) // avoid total swallow.

    return { 
      skip: 'missing dep. "puppeteer". Run: "$ npm i" and try again.' 
    }
  }
}

export { puppeteer, extend }