fix!: represent locator as an object instead of a string (#10212) · vitest-dev/vitest@80f07ed (original) (raw)
`` @@ -1051,19 +1051,70 @@ Internally, this method calls .elements and wraps every element using [`page.e
``
1051
1051
``
1052
1052
``
1053
1053
``
``
1054
`+
serialize
`
``
1055
+
``
1056
```ts
``
1057
`+
function serialize(): SerializedLocator
`
``
1058
```
``
1059
+
``
1060
`+
Returns a JSON-serializable representation of the locator. The returned object has two fields:
`
``
1061
+
``
1062
`` +
selector: the provider-specific selector string used to query the element at runtime.
``
``
1063
`` +
locator: a human-readable description of the locator (e.g.getByRole('button')), used for error messages and tracing. Equivalent to callingasLocator().
``
``
1064
+
``
1065
`` +
This is primarily intended for forwarding a locator to a browser command, which runs in Node and cannot receive a live Locator instance:
``
``
1066
+
``
1067
```ts
``
1068
`+
import { commands, page } from 'vitest/browser'
`
``
1069
+
``
1070
`+
await commands.myCommand(page.getByRole('button').serialize())
`
``
1071
```
``
1072
+
``
1073
`+
::: tip
`
``
1074
`` +
Vitest automatically serializes any Locator argument passed to a command, so calling serialize() explicitly is rarely necessary. You can also use JSON.stringify(locator) (it calls toJSON internally), which produces the same result.
``
``
1075
`+
:::
`
``
1076
+
``
1077
`+
toJSON
`
``
1078
+
``
1079
```ts
``
1080
`+
function toJSON(): SerializedLocator
`
``
1081
```
``
1082
+
``
1083
`` +
Alias of serialize. Defined so that JSON.stringify(locator) and structured-clone-based transports return a SerializedLocator object.
``
``
1084
+
``
1085
`+
asLocator
`
``
1086
+
``
1087
```ts
``
1088
`+
function asLocator(): string
`
``
1089
```
``
1090
+
``
1091
`` +
Returns a human-readable description of the locator using the JavaScript locator syntax (e.g. getByRole('button', { name: 'Submit' })). This is the same string exposed as the locator field of serialize() and is used in error messages and traces.
``
``
1092
+
``
1093
```ts
``
1094
`+
import { page } from 'vitest/browser'
`
``
1095
+
``
1096
`+
const button = page.getByRole('button', { name: 'Submit' })
`
``
1097
`+
button.asLocator() // "getByRole('button', { name: 'Submit' })"
`
``
1098
```
``
1099
+
``
1100
`+
::: tip
`
``
1101
`` +
Use selector when you need the provider-specific string to forward to a browser command. Use asLocator() only for diagnostic output. The returned string is not meant to be re-used to query elements.
``
``
1102
`+
:::
`
``
1103
+
1054
1104
`## Properties
`
1055
1105
``
1056
1106
`### selector
`
1057
1107
``
1058
``
`` -
The selector is a string that will be used to locate the element by the browser provider. Playwright will use a playwright locator syntax while preview and webdriverio will use CSS.
``
``
1108
`` +
The selector is a string that will be used to locate the element by the browser provider. Playwright will use a playwright locator syntax, and preview and webdriverio will use CSS.
``
1059
1109
``
1060
1110
`::: danger
`
1061
1111
`` You should not use this string in your test code. The selector string should only be used when working with the Commands API:
``
1062
1112
``
1063
1113
```` ```ts [commands.ts]
`1064`
`1114`
`import type { BrowserCommand } from 'vitest/node'
`
``
`1115`
`+
import type { SerializedLocator } from '@vitest/browser'
`
`1065`
`1116`
``
`1066`
``
`-
const test: BrowserCommand<string> = function test(context, selector) {
`
``
`1117`
`+
const test: BrowserCommand<SerializedLocator> = function test(context, { selector }) {
`
`1067`
`1118`
` // playwright
`
`1068`
`1119`
` await context.iframe.locator(selector).click()
`
`1069`
`1120`
` // webdriverio
`
`@@ -1076,8 +1127,8 @@ import { test } from 'vitest'
`
`1076`
`1127`
`import { commands, page } from 'vitest/browser'
`
`1077`
`1128`
``
`1078`
`1129`
`test('works correctly', async () => {
`
`1079`
``
`-
await commands.test(page.getByText('Hello').selector) // ✅
`
`1080`
``
`-
// vitest will automatically unwrap it to a string
`
``
`1130`
`+
await commands.test(page.getByText('Hello').serialize()) // ✅
`
``
`1131`
`+
// vitest will automatically unwrap it to a SerializedLocator
`
`1081`
`1132`
` await commands.test(page.getByText('Hello')) // ✅
`
`1082`
`1133`
`})
`
`1083`
`1134`
```` ```