feat: add support for async waitForTarget

[tmkx]

What kind of change does this PR introduce?

feature

Did you add tests for your changes?
yes
If relevant, did you update the documentation?
yes
Summary
sometimes we need to call waitForTarget in async:

const target = await browser.waitForTarget((target) =>
  target
    .page()
    .then((page) => page.title())
    .then((title) => title === 'expected')
);

Does this PR introduce a breaking change?
no

Other information

[OrKoN]

Does it make sense to use debugError instead of console.error?

[tmkx]

@OrKoN Hello, I do not understand, what does this have to do with debugError and console.error?

[OrKoN]

Apologies, ignore that, I intended to leave that comment on #7883

[OrKoN]

The timeout setting is not respected if the callback never resolves or takes a long time to resolve. Could you address that? also, the firefox-related failures probably require itFailsFirefox instead of it.

[tmkx]

Sorry, the test was copied from this one, so it should use itFailsFirefox also. Updated.

puppeteer/test/target.spec.ts

Lines 70 to 86 in 921e4e6

	itFailsFirefox(
	'should report when a new page is created and closed',
	async () => {
	const { page, server, context } = getTestState();
	const [otherPage] = await Promise.all([
	context
	.waitForTarget(
	(target) =>
	target.url() === server.CROSS_PROCESS_PREFIX + '/empty.html'
	)
	.then((target) => target.page()),
	page.evaluate(
	(url: string) => window.open(url),
	server.CROSS_PROCESS_PREFIX + '/empty.html'
	),
	]);

[OrKoN]

ugh, additional edge cases come to mind. WDYT about the following: we start waiting for a target and start checking existing targets one by one (and say there is a hundred of targets), then a matching target gets created and we resolve the waitForTarget with it. Although we resolved the inner promise continues executing and keeps checking the remaining targets one by one. I think that should be addressed by checking if the waitWithTimeout has been resolved and returning earlier.

[OrKoN]

I think let's leave this for a follow-up (seems to be rather an edge case)