Within

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.

within('.js-signup-form', () => {
  I.fillField('user[login]', 'User')
  I.fillField('user[email]', 'user@user.com')
  I.fillField('user[password]', 'user@user.com')
  I.click('button')
})
I.see('There were problems creating your account.')

⚠ 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. Since within returns a Promise, always await it when you need its return value.

IFrames

Use a frame locator to scope actions inside an iframe:

within({ frame: '#editor' }, () => {
  I.see('Page')
  I.fillField('Body', 'Hello world')
})

Nested iframes (WebDriver & Puppeteer only):

within({ frame: ['.content', '#editor'] }, () => {
  I.see('Page')
})

ℹ IFrames can also be accessed via I.switchTo command.

Returning Values

within can return a value for use in the scenario:

const val = await within('#sidebar', () => {
  return I.grabTextFrom({ css: 'h1' })
})
I.fillField('Description', val)

When running steps inside a within block, they will be shown indented in the output.