It seems this should be <[string]>|<[Array]<[string]>> according to args format here.

@vsemozhetbyt I wasn't sure and the doc linter didn't complain so I thought was okay. I'll push a fix, thanks.

On line 702 you throw if there's no element matching selector.
In order to be consistent, you should also throw if there's an element that is not a <select>.

let's convert options to array once to avoid the Array.prototype.call workaround:

const options = Array.from(element.options);
// ...

nit: the value is always an array; let's call it values to make it clear

This was how I first wrote, but since it can also be provided to the method as a string, I thought value was more appropriate in either case - but I'll change it. 👍

how is this selecting multiple options?

Bad wording, will clarify.

we usually do varargs to support both array and a single value. Check out ElementHandle.uploadFile

Regarding the matching against value / label, is this an innovation or it's already implemented in some other automation library?

Regarding the matching against value / label, first time I saw it was on CasperJS.
GhostJS also borrows the idea.

what does empty string mean as an argument?

A non-existent option, could be anything (that's not on the options). Will clarify.

nit: let's explicitly emit two events

element.dispatchEvent(new Event('change'));
element.dispatchEvent(new Event('input'));

in this case, the element handle will never be disposed (since the handle.dispose won't be reached).

If you use the this.$eval, this should be handled just fine. (and if it doesn't, then we should fix page.$eval)

Good to know, I'll fix that.

this if could be removed - values are always an array now since you switched to varargs

nit: could you please switch this branch with the following one. I mean:

if (element.multiple) {
  // ...
} else {
}

it's easier to read assertions rather then negations.

nit: let's use for-of

for (let option of options)
  option.selected = values.includes(option.value) || values.includes(option.label);

can we also cover the 'change' event? And since the asset is getting heavier, can we reuse single HTML asset to test both multiple and single selection? The select.html can always return an array, and the multiple attribute could be set from-inside the test:

await page.goto(PREFIX + '/input/select.html');
await page.$eval('select', select => select.setAttribute('multiple', true));

Aren't we mixing fixtures with the tests doing it this way? What guarantees do we have that select.setAttribute('multiple', true) will actually yield the expected result?

I'm concerned about falling back to the value of label. Depending on the combination of value and label attributes on every option, the matching will happen against either value, label or node's text content. The outcome is hard for me to predict.

Can we start with matching against values only? When/if there's a strong need to match against labels, I'd prefer it to be stated explicitly with options object.

@aslushnikov For me this is a important feature, in fact for my specific use case I would specialize it even more. Often times, the option values have little resemblance to the label(s) you're targeting.

Nightmare.js has a convenient action method that can be used to implement custom behaviors in a global browser scope without repeating code and, AFAIK, puppeteer only has exposeFunction on a page scope.

Your options suggestion would still be limiting, what are your thoughts on having a page.select(selector, callback) signature, where the callback is a resolver function that gets the option value, label, textContent, index as arguments and has to return true to have that option selected, false otherwise?

A few scenarios I'm facing that could benefit from this (maybe applies to others too), e.g.:

<select id="country">
	<option value="250">France</option>
	<option value="276">Deutschland</option>
	<option value="620">Portugal</option>
	<option value="724">España</option>
	<option value="840">United States of America</option>
</select>

You could select based on value directly:

page.select('#country', '724');

Or implement advanced "resolvers", for instance ISO 3166-1 numeric to Alpha 2:

page.select('#country', 'DE', (target, value, label, options) => {
  let resolved = null;

  switch (value) {
    case 250:
      resolved = 'FR';
    break;

    case 276:
      resolved = 'DE';
    break;

    case 620:
      resolved = 'PT';
    break;

    case 724:
      resolved = 'ES';
    break;

    case 840:
      resolved = 'US';
    break;
  }

  return target === resolved;
});

Or even go fuzzy if needed be:

page.select('#country', 'Spain', (target, value, label, options) => {
  /**
   * Get all `options`, and find the one with the lowest
   * string distance from either the `value` or the `label`.
   *
   * In this case, "Spain" would be resolved to the value of "España".
   */
});

Reading other issues, this could also be helpful to resolve implementation inconsistencies between in libraries and frameworks (ReactJS Virtual DOM was mentioned for instance).

Nightmare.js has a convenient action method that can be used to implement custom behaviors in a global browser scope without repeating code and, AFAIK, puppeteer only has exposeFunction on a page scope.

If I understand Nightmare's action correctly, the analogue in puppeteer would be adding new methods to the page prototype:

Page.prototype.size = function(done) {
  return this.evaluate(() => {
    const w = Math.max(document.documentElement.clientWidth, window.innerWidth || 0)
    const h = Math.max(document.documentElement.clientHeight, window.innerHeight || 0)
    return {
      height: h,
      width: w
    }
  });
})

It looks like it has nothing to do with page.exposeFunction.

what are your thoughts on having a page.select(selector, callback) signature, where the callback is a resolver function that gets the option value, label, textContent, index as arguments and has to return true to have that option selected, false otherwise?

I think it's not a simple API.

If you can select by values, then you can implement custom resolver with page.evaluate.
For example, selecting all options that contain letter 'e' in their label:

const values = await page.evaluate(() => {
  const options = Array.from(document.querySelectorAll('select > option'));
  const optionsWithE = options.filter(option => option.label.includes('e'));
  return optionsWithE.map(option => option.value);
  });
});
await page.select('select', ...values);

@aslushnikov Extending the Page prototype would actually be super useful to me!

But I'm not sure how to go about accessing the Page class, it appears that it's not exported?

@alixaxel ah right. You can "hack" it with a manual require:

const Page = require('puppeteer/lib/Page');

This is not safe of course, but this magic require should not change much over the time.

do we need to dispatch 'input'? Nightmare gets away without it

I think so, even listeners could only be listening to input, and I think those are also the events that the browser sends on a typical mouse-selection scenario.

input is fired on select changes. So it should be fired to best reflect what browsers do.

I'll keep dispatching change and input events, since that's what browsers do.

Why call toLowerCase here? Checking against 'SELECT' is just fine and saves extra work from happening.

@Garbee According to https://johnresig.com/blog/nodename-case-sensitivity/:

1. The node names of HTML elements are always uppercase, even if they’re explicitly created using lowercase characters. will result in a .nodeName === "HTML" (see the HTML 5 draft).
2. The node names of XML elements are always in the original case, as specified when they’re created. will result in a .nodeName === "data", will result in a .nodeName === "DATA".

I think it's not a big thing to leave toLowerCase just for the sake of reliability.

input is fired on select changes. So it should be fired to best reflect what browsers do.

no need for the array:

page.select('select#colors', 'red', 'green', 'blue');