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.
3
+
`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.
4
4
5
5
```js
6
-
import { Within } from'codeceptjs/effects'
6
+
import { within } from'codeceptjs/effects'
7
7
```
8
8
9
-
## Begin / End Pattern
9
+
## Begin / Leave Pattern
10
10
11
-
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:
11
+
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:
12
12
13
13
```js
14
-
Within('.signup-form')
14
+
constarea=within('.signup-form')
15
15
I.fillField('Email', 'user@example.com')
16
16
I.fillField('Password', 'secret')
17
17
I.click('Sign Up')
18
-
Within()
18
+
area.leave()
19
19
```
20
20
21
-
Steps between `Within('.signup-form')` and `Within()` are scoped to `.signup-form`. After `Within()`, the context resets to the full page.
21
+
Steps between `within('.signup-form')` and `area.leave()` are scoped to `.signup-form`. After `leave()`, the context resets to the full page.
22
+
23
+
You can also end a context by calling `within()` with no arguments:
24
+
25
+
```js
26
+
within('.signup-form')
27
+
I.fillField('Email', 'user@example.com')
28
+
within()
29
+
```
22
30
23
31
### Auto-end previous context
24
32
25
-
Starting a new `Within` automatically ends the previous one:
33
+
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.
46
+
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.
39
47
40
48
## Callback Pattern
41
49
42
50
The callback pattern wraps actions in a function. The context is automatically closed when the function returns:
43
51
44
52
```js
45
-
Within('.signup-form', () => {
53
+
within('.signup-form', () => {
46
54
I.fillField('Email', 'user@example.com')
47
55
I.fillField('Password', 'secret')
48
56
I.click('Sign Up')
@@ -52,41 +60,41 @@ I.see('Account created')
52
60
53
61
### Returning values
54
62
55
-
The callback pattern supports returning values. Use `await` on both the `Within` call and the inner action:
63
+
The callback pattern supports returning values. Use `await` on both the `within` call and the inner action:
56
64
57
65
```js
58
-
consttext=awaitWithin('#sidebar', async () => {
66
+
consttext=awaitwithin('#sidebar', async () => {
59
67
returnawaitI.grabTextFrom('h1')
60
68
})
61
69
I.fillField('Search', text)
62
70
```
63
71
64
72
## When to use `await`
65
73
66
-
**Begin/end pattern** does not need `await`:
74
+
**Begin/leave pattern** does not need `await`:
67
75
68
76
```js
69
-
Within('.form')
77
+
constarea=within('.form')
70
78
I.fillField('Name', 'John')
71
-
Within()
79
+
area.leave()
72
80
```
73
81
74
82
**Callback pattern** needs `await` when:
75
83
76
84
- The callback is `async`
77
-
- You need a return value from `Within`
85
+
- You need a return value from `within`
78
86
79
87
```js
80
88
// async callback — await required
81
-
awaitWithin('.form', async () => {
89
+
awaitwithin('.form', async () => {
82
90
awaitI.click('Submit')
83
91
awaitI.waitForText('Done')
84
92
})
85
93
```
86
94
87
95
```js
88
96
// sync callback — no await needed
89
-
Within('.form', () => {
97
+
within('.form', () => {
90
98
I.fillField('Name', 'John')
91
99
I.click('Submit')
92
100
})
@@ -97,14 +105,14 @@ Within('.form', () => {
97
105
Use the `frame` locator to scope actions inside an iframe:
Each selector in the array navigates one level deeper into the iframe hierarchy.
124
132
125
-
### switchTo auto-disables Within
133
+
### switchTo auto-disables within
126
134
127
-
If you call `I.switchTo()` while inside a `Within` context, the within context is automatically ended. This prevents conflicts between the two scoping mechanisms:
135
+
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