Skip to content

Commit b116fb7

Browse files
DavertMikclaude
DavertMik
and
claude
committed
feat: refactor within to Within with begin/end pattern
Add Within() function with three signatures: - Within(locator) to begin scoped context - Within() to end current context - Within(locator, fn) callback pattern (existing behavior) Lowercase within() kept as deprecated alias with one-time warning. switchTo() in helpers auto-ends any active Within context. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 2f8bc5c commit b116fb7

9 files changed

Lines changed: 374 additions & 98 deletions

File tree

‎docs/effects.md‎

Lines changed: 18 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,7 @@ Effects are functions that can modify scenario flow. They provide ways to handle
1212
Effects can be imported directly from CodeceptJS:
1313

1414
```js
15-
// ESM
16-
import { tryTo, retryTo, within } from 'codeceptjs/effects'
17-
18-
// CommonJS
19-
const { tryTo, retryTo, within } = require('codeceptjs/effects')
15+
import { tryTo, retryTo, Within } from 'codeceptjs/effects'
2016
```
2117

2218
> 📝 Note: Prior to v3.7, `tryTo` and `retryTo` were available globally via plugins. This behavior is deprecated and will be removed in v4.0.
@@ -80,71 +76,38 @@ await retryTo(tries => {
8076
}, 3)
8177
```
8278

83-
## within
79+
## Within
8480

85-
The `within` effect scopes all actions inside it to a specific element on the page — useful when working with repeated UI components or narrowing interaction to a specific section.
81+
The `Within` effect scopes actions to a specific element or iframe. It supports both a begin/end pattern and a callback pattern:
8682

8783
```js
88-
import { within } from 'codeceptjs/effects'
89-
90-
// inside a test...
91-
await within('.js-signup-form', () => {
92-
I.fillField('user[login]', 'User')
93-
I.fillField('user[email]', 'user@user.com')
94-
I.fillField('user[password]', 'user@user.com')
95-
I.click('button')
84+
import { Within } from 'codeceptjs/effects'
85+
86+
// Begin/end pattern
87+
Within('.modal')
88+
I.see('Modal title')
89+
I.click('Close')
90+
Within()
91+
92+
// Callback pattern
93+
Within('.modal', () => {
94+
I.see('Modal title')
95+
I.click('Close')
9696
})
97-
I.see('There were problems creating your account.')
9897
```
9998

100-
> ⚠ `within` can cause problems when used incorrectly. If you see unexpected behavior, refactor to use the context parameter on individual actions instead (e.g. `I.click('Login', '.nav')`). Keep `within` for the simplest cases.
101-
102-
> ⚠ Since `within` returns a Promise, always `await` it when you need its return value.
103-
104-
### IFrames
105-
106-
Use a `frame` locator to scope actions inside an iframe:
99+
See the full [Within documentation](/within) for details on iframes, page objects, and `await` usage.
107100

108-
```js
109-
await within({ frame: '#editor' }, () => {
110-
I.see('Page')
111-
I.fillField('Body', 'Hello world')
112-
})
113-
```
114-
115-
Nested iframes _(WebDriver & Puppeteer only)_:
116-
117-
```js
118-
await within({ frame: ['.content', '#editor'] }, () => {
119-
I.see('Page')
120-
})
121-
```
122-
123-
> ℹ IFrames can also be accessed via `I.switchTo` command.
124-
125-
### Returning Values
126-
127-
`within` can return a value for use in the scenario:
128-
129-
```js
130-
const val = await within('#sidebar', () => {
131-
return I.grabTextFrom({ css: 'h1' })
132-
})
133-
I.fillField('Description', val)
134-
```
135-
136-
When running steps inside a `within` block, they will be shown indented in the output.
101+
> The lowercase `within()` is deprecated. Use `Within` instead.
137102
138103
## Usage with TypeScript
139104

140105
Effects are fully typed and work well with TypeScript:
141106

142107
```ts
143-
import { tryTo, retryTo, within } from 'codeceptjs/effects'
108+
import { tryTo, retryTo, Within } from 'codeceptjs/effects'
144109

145110
const success = await tryTo(async () => {
146111
await I.see('Element')
147112
})
148113
```
149-
150-
This documentation covers the main effects functionality while providing practical examples and important notes about deprecation and future changes. Let me know if you'd like me to expand any section or add more examples!

‎docs/within.md‎

Lines changed: 196 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -5,51 +5,223 @@ title: Within
55

66
# Within
77

8-
`within` scopes all actions inside it to a specific element on the page — useful when working with repeated UI components or narrowing interaction to a specific section.
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.
99

1010
```js
11-
within('.js-signup-form', () => {
12-
I.fillField('user[login]', 'User')
13-
I.fillField('user[email]', 'user@user.com')
14-
I.fillField('user[password]', 'user@user.com')
15-
I.click('button')
11+
import { Within } from 'codeceptjs/effects'
12+
```
13+
14+
## Begin / End Pattern
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:
17+
18+
```js
19+
Within('.signup-form')
20+
I.fillField('Email', 'user@example.com')
21+
I.fillField('Password', 'secret')
22+
I.click('Sign Up')
23+
Within()
24+
```
25+
26+
Steps between `Within('.signup-form')` and `Within()` are scoped to `.signup-form`. After `Within()`, the context resets to the full page.
27+
28+
### Auto-end previous context
29+
30+
Starting a new `Within` automatically ends the previous one:
31+
32+
```js
33+
Within('.sidebar')
34+
I.click('Dashboard')
35+
36+
Within('.main-content') // ends .sidebar, begins .main-content
37+
I.see('Welcome')
38+
Within()
39+
```
40+
41+
### Forgetting to close
42+
43+
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.
44+
45+
## Callback Pattern
46+
47+
The callback pattern wraps actions in a function. The context is automatically closed when the function returns:
48+
49+
```js
50+
Within('.signup-form', () => {
51+
I.fillField('Email', 'user@example.com')
52+
I.fillField('Password', 'secret')
53+
I.click('Sign Up')
54+
})
55+
I.see('Account created')
56+
```
57+
58+
### Returning values
59+
60+
The callback pattern supports returning values. Use `await` on both the `Within` call and the inner action:
61+
62+
```js
63+
const text = await Within('#sidebar', async () => {
64+
return await I.grabTextFrom('h1')
65+
})
66+
I.fillField('Search', text)
67+
```
68+
69+
## When to use `await`
70+
71+
**Begin/end pattern** does not need `await`:
72+
73+
```js
74+
Within('.form')
75+
I.fillField('Name', 'John')
76+
Within()
77+
```
78+
79+
**Callback pattern** needs `await` when:
80+
81+
- The callback is `async`
82+
- You need a return value from `Within`
83+
84+
```js
85+
// async callback — await required
86+
await Within('.form', async () => {
87+
await I.click('Submit')
88+
await I.waitForText('Done')
1689
})
17-
I.see('There were problems creating your account.')
1890
```
1991

20-
> ⚠ `within` can cause problems when used incorrectly. If you see unexpected behavior, refactor to use the context parameter on individual actions instead (e.g. `I.click('Login', '.nav')`). Keep `within` for the simplest cases.
21-
> Since `within` returns a Promise, always `await` it when you need its return value.
92+
```js
93+
// sync callback — no await needed
94+
Within('.form', () => {
95+
I.fillField('Name', 'John')
96+
I.click('Submit')
97+
})
98+
```
99+
100+
## Working with IFrames
101+
102+
Use the `frame` locator to scope actions inside an iframe:
103+
104+
```js
105+
// Begin/end
106+
Within({ frame: 'iframe' })
107+
I.fillField('Email', 'user@example.com')
108+
I.click('Submit')
109+
Within()
110+
111+
// Callback
112+
Within({ frame: '#editor-frame' }, () => {
113+
I.see('Page content')
114+
})
115+
```
22116

23-
## IFrames
117+
### Nested IFrames
24118

25-
Use a `frame` locator to scope actions inside an iframe:
119+
Pass an array of selectors to reach nested iframes:
26120

27121
```js
28-
within({ frame: '#editor' }, () => {
29-
I.see('Page')
30-
I.fillField('Body', 'Hello world')
122+
Within({ frame: ['.wrapper', '#content-frame'] }, () => {
123+
I.fillField('Name', 'John')
124+
I.see('Sign in!')
31125
})
32126
```
33127

34-
Nested iframes _(WebDriver & Puppeteer only)_:
128+
Each selector in the array navigates one level deeper into the iframe hierarchy.
129+
130+
### switchTo auto-disables Within
131+
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:
133+
134+
```js
135+
Within('.sidebar')
136+
I.click('Open editor')
137+
I.switchTo('#editor-frame') // automatically ends Within('.sidebar')
138+
I.fillField('content', 'Hello')
139+
I.switchTo() // exits iframe
140+
```
141+
142+
## Usage in Page Objects
143+
144+
In page objects, import `Within` directly:
145+
146+
```js
147+
// pages/Login.js
148+
import { Within } from 'codeceptjs/effects'
149+
150+
export default {
151+
loginForm: '.login-form',
152+
153+
fillCredentials(email, password) {
154+
Within(this.loginForm)
155+
I.fillField('Email', email)
156+
I.fillField('Password', password)
157+
Within()
158+
},
159+
160+
submitLogin(email, password) {
161+
this.fillCredentials(email, password)
162+
I.click('Log In')
163+
},
164+
}
165+
```
35166

36167
```js
37-
within({ frame: ['.content', '#editor'] }, () => {
38-
I.see('Page')
168+
// tests/login_test.js
169+
Scenario('user can log in', ({ I, loginPage }) => {
170+
I.amOnPage('/login')
171+
loginPage.submitLogin('user@example.com', 'password')
172+
I.see('Dashboard')
39173
})
40174
```
41175

42-
> ℹ IFrames can also be accessed via `I.switchTo` command.
176+
The callback pattern also works in page objects:
177+
178+
```js
179+
// pages/Checkout.js
180+
import { Within } from 'codeceptjs/effects'
181+
182+
export default {
183+
async getTotal() {
184+
return await Within('.order-summary', async () => {
185+
return await I.grabTextFrom('.total')
186+
})
187+
},
188+
}
189+
```
43190

44-
## Returning Values
191+
## Deprecated: lowercase `within`
45192

46-
`within` can return a value for use in the scenario:
193+
The lowercase `within()` is still available as a global function for backward compatibility, but it is deprecated:
47194

48195
```js
49-
const val = await within('#sidebar', () => {
50-
return I.grabTextFrom({ css: 'h1' })
196+
// deprecated — still works, shows a one-time warning
197+
within('.form', () => {
198+
I.fillField('Name', 'John')
199+
})
200+
201+
// recommended
202+
import { Within } from 'codeceptjs/effects'
203+
Within('.form', () => {
204+
I.fillField('Name', 'John')
51205
})
52-
I.fillField('Description', val)
53206
```
54207

55-
When running steps inside a `within` block, they will be shown indented in the output.
208+
The global `within` only supports the callback pattern. For the begin/end pattern, you must import `Within`.
209+
210+
## Output
211+
212+
When running steps inside a `Within` block, the output shows them indented under the context:
213+
214+
```
215+
Within ".signup-form"
216+
I fill field "Email", "user@example.com"
217+
I fill field "Password", "secret"
218+
I click "Sign Up"
219+
I see "Account created"
220+
```
221+
222+
## Tips
223+
224+
- Prefer the begin/end pattern for simple linear flows — it's more readable.
225+
- Use the callback pattern when you need return values or want guaranteed cleanup.
226+
- Avoid deeply nesting `Within` blocks. If you find yourself needing nested contexts, consider restructuring your test.
227+
- `Within` cannot be used inside a `session`. Use `session` at the top level and `Within` inside it, not the other way around.

0 commit comments

Comments
 (0)