feat(fixture): support Page in within fixture (returns Screen)

Support `Page` in addition to `Locator` in `within()` fixture. When
a `Page` instance is passed to `within()`, a `Screen` instance will be
returned which includes the entire `Page` API in addition to the query
methods.

```ts
test('within page', async ({ page }) => {
  // Passing `page` to `within` returns a `Screen` instance
  const screen = within(page)

  await screen.goto(/* ... */)

  const form = screen.queryByRole('form', {name: 'User'})

  // Passing a `Locator` returns scoped queries
  const {queryByLabelText} = within(form)

  // ...
})
```

Author: jrolfs

lib/fixture/locator/fixtures.ts

@@ -1,5 +1,5 @@
 import type {Locator, PlaywrightTestArgs, TestFixture} from '@playwright/test'
-import {selectors} from '@playwright/test'
+import {Page, selectors} from '@playwright/test'
 
 import type {
   Config,
@@ -8,10 +8,11 @@ import type {
   SelectorEngine,
   SynchronousQuery,
   Within,
+  WithinReturn,
 } from '../types'
 
-import {buildTestingLibraryScript, includes, queryToSelector} from './helpers'
-import {allQueryNames, isAllQuery, queriesFor, synchronousQueryNames} from './queries'
+import {buildTestingLibraryScript, queryToSelector} from './helpers'
+import {isAllQuery, queriesFor, screenFor, synchronousQueryNames} from './queries'
 
 type TestArguments = PlaywrightTestArgs & Config
 
@@ -34,26 +35,21 @@ const screenFixture: TestFixture<Screen, TestArguments> = async (
   {page, asyncUtilExpectedState, asyncUtilTimeout},
   use,
 ) => {
-  const queries = queriesFor(page, {asyncUtilExpectedState, asyncUtilTimeout})
-  const revocable = Proxy.revocable(page, {
-    get(target, property, receiver) {
-      return includes(allQueryNames, property)
-        ? queries[property]
-        : Reflect.get(target, property, receiver)
-    },
-  })
-
-  await use(revocable.proxy as Screen)
-
-  revocable.revoke()
+  const {proxy, revoke} = screenFor(page, {asyncUtilExpectedState, asyncUtilTimeout})
+
+  await use(proxy)
+
+  revoke()
 }
 
 const withinFixture: TestFixture<Within, TestArguments> = async (
   {asyncUtilExpectedState, asyncUtilTimeout},
   use,
 ) =>
-  use(
-    (locator: Locator): Queries => queriesFor(locator, {asyncUtilExpectedState, asyncUtilTimeout}),
+  use(<Root extends Page | Locator>(root: Root) =>
+    'goto' in root
+      ? screenFor(root, {asyncUtilExpectedState, asyncUtilTimeout}).proxy
+      : (queriesFor(root, {asyncUtilExpectedState, asyncUtilTimeout}) as WithinReturn<Root>),
   )
 
 declare const queryName: SynchronousQuery

lib/fixture/locator/queries.ts

@@ -11,10 +11,11 @@ import type {
   LocatorQueries as Queries,
   Query,
   QueryQuery,
+  Screen,
   SynchronousQuery,
 } from '../types'
 
-import {queryToSelector} from './helpers'
+import {includes, queryToSelector} from './helpers'
 
 const isAllQuery = (query: Query): query is AllQuery => query.includes('All')
 
@@ -109,4 +110,13 @@ const queriesFor = (pageOrLocator: Page | Locator, config?: Partial<Config>) =>
     {} as Queries,
   )
 
-export {allQueryNames, isAllQuery, isNotFindQuery, queriesFor, synchronousQueryNames}
+const screenFor = (page: Page, config: Partial<Config>) =>
+  Proxy.revocable(page, {
+    get(target, property, receiver) {
+      return includes(allQueryNames, property)
+        ? queriesFor(page, config)[property]
+        : Reflect.get(target, property, receiver)
+    },
+  }) as {proxy: Screen; revoke: () => void}
+
+export {allQueryNames, isAllQuery, isNotFindQuery, queriesFor, screenFor, synchronousQueryNames}

lib/fixture/types.ts

@@ -52,8 +52,9 @@ type KebabCase<S> = S extends `${infer C}${infer T}`
 
 export type LocatorQueries = {[K in keyof Queries]: ConvertQuery<Queries[K]>}
 
-export type Within = (locator: Locator) => LocatorQueries
+export type WithinReturn<Root extends Locator | Page> = Root extends Page ? Screen : LocatorQueries
 export type Screen = LocatorQueries & Page
+export type Within = <Root extends Locator | Page>(locator: Root) => WithinReturn<Root>
 
 export type Query = keyof Queries
 

test/fixture/locators.test.ts

@@ -149,6 +149,25 @@ test.describe('lib/fixture.ts (locators)', () => {
       expect(await innerLocator.count()).toBe(1)
     })
 
+    test('when `Page` instance is provided, `within` returns a `Screen`', async ({
+      page,
+      within,
+    }) => {
+      const screen = within(page)
+
+      await screen.goto(`file://${path.join(__dirname, '../fixtures/page.html')}`)
+
+      const form = screen.queryByRole('form', {name: 'User'})
+
+      const {queryByLabelText} = within(form)
+
+      const outerLocator = queryByLabelText('Name')
+      const innerLocator = queryByLabelText('Username')
+
+      expect(await outerLocator.count()).toBe(0)
+      expect(await innerLocator.count()).toBe(1)
+    })
+
     test.describe('configuration', () => {
       test.describe('custom data-testid', () => {
         test.use({testIdAttribute: 'data-id'})