You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`Within` narrows the execution context to a specific element or iframe on the page. All actions called inside a `Within` block are scoped to the matched element.
8
+
`within` narrows the execution context to a specific element or iframe on the page. All actions called inside a `within` block are scoped to the matched element.
9
9
10
10
```js
11
-
import { Within } from'codeceptjs/effects'
11
+
import { within } from'codeceptjs/effects'
12
12
```
13
13
14
-
## Begin / End Pattern
14
+
## Begin / Leave Pattern
15
15
16
-
The simplest way to use `Within` is the begin/end pattern. Call `Within` with a locator to start, perform actions, then call `Within()`with no arguments to end:
16
+
The simplest way to use `within` is the begin/leave pattern. Call `within` with a locator to start — it returns a context object. Call `.leave()`on it when done:
17
17
18
18
```js
19
-
Within('.signup-form')
19
+
constarea=within('.signup-form')
20
20
I.fillField('Email', 'user@example.com')
21
21
I.fillField('Password', 'secret')
22
22
I.click('Sign Up')
23
-
Within()
23
+
area.leave()
24
24
```
25
25
26
-
Steps between `Within('.signup-form')` and `Within()` are scoped to `.signup-form`. After `Within()`, the context resets to the full page.
26
+
Steps between `within('.signup-form')` and `area.leave()` are scoped to `.signup-form`. After `leave()`, the context resets to the full page.
27
+
28
+
You can also end a context by calling `within()` with no arguments:
29
+
30
+
```js
31
+
within('.signup-form')
32
+
I.fillField('Email', 'user@example.com')
33
+
within()
34
+
```
27
35
28
36
### Auto-end previous context
29
37
30
-
Starting a new `Within` automatically ends the previous one:
38
+
Starting a new `within` automatically ends the previous one:
If you forget to call `Within()` at the end, the context is automatically cleaned up when the test finishes. However, it is good practice to always close it explicitly.
51
+
If you forget to call `leave()` or `within()` at the end, the context is automatically cleaned up when the test finishes. However, it is good practice to always close it explicitly.
44
52
45
53
## Callback Pattern
46
54
47
55
The callback pattern wraps actions in a function. The context is automatically closed when the function returns:
48
56
49
57
```js
50
-
Within('.signup-form', () => {
58
+
within('.signup-form', () => {
51
59
I.fillField('Email', 'user@example.com')
52
60
I.fillField('Password', 'secret')
53
61
I.click('Sign Up')
@@ -57,41 +65,41 @@ I.see('Account created')
57
65
58
66
### Returning values
59
67
60
-
The callback pattern supports returning values. Use `await` on both the `Within` call and the inner action:
68
+
The callback pattern supports returning values. Use `await` on both the `within` call and the inner action:
61
69
62
70
```js
63
-
consttext=awaitWithin('#sidebar', async () => {
71
+
consttext=awaitwithin('#sidebar', async () => {
64
72
returnawaitI.grabTextFrom('h1')
65
73
})
66
74
I.fillField('Search', text)
67
75
```
68
76
69
77
## When to use `await`
70
78
71
-
**Begin/end pattern** does not need `await`:
79
+
**Begin/leave pattern** does not need `await`:
72
80
73
81
```js
74
-
Within('.form')
82
+
constarea=within('.form')
75
83
I.fillField('Name', 'John')
76
-
Within()
84
+
area.leave()
77
85
```
78
86
79
87
**Callback pattern** needs `await` when:
80
88
81
89
- The callback is `async`
82
-
- You need a return value from `Within`
90
+
- You need a return value from `within`
83
91
84
92
```js
85
93
// async callback — await required
86
-
awaitWithin('.form', async () => {
94
+
awaitwithin('.form', async () => {
87
95
awaitI.click('Submit')
88
96
awaitI.waitForText('Done')
89
97
})
90
98
```
91
99
92
100
```js
93
101
// sync callback — no await needed
94
-
Within('.form', () => {
102
+
within('.form', () => {
95
103
I.fillField('Name', 'John')
96
104
I.click('Submit')
97
105
})
@@ -102,14 +110,14 @@ Within('.form', () => {
102
110
Use the `frame` locator to scope actions inside an iframe:
Each selector in the array navigates one level deeper into the iframe hierarchy.
129
137
130
-
### switchTo auto-disables Within
138
+
### switchTo auto-disables within
131
139
132
-
If you call `I.switchTo()` while inside a `Within` context, the within context is automatically ended. This prevents conflicts between the two scoping mechanisms:
140
+
If you call `I.switchTo()` while inside a `within` context, the within context is automatically ended. This prevents conflicts between the two scoping mechanisms:
0 commit comments