codeceptjs 4.0.0-rc.18 → 4.0.0-rc.19

package/docs/within.md

@@ -0,0 +1,55 @@
+---
+permalink: /within
+title: Within
+---
+
+# 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.
+
+```js
+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:
+
+```js
+within({ frame: '#editor' }, () => {
+  I.see('Page')
+  I.fillField('Body', 'Hello world')
+})
+```
+
+Nested iframes _(WebDriver & Puppeteer only)_:
+
+```js
+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:
+
+```js
+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.

package/lib/command/dryRun.js

@@ -10,6 +10,7 @@ import Container from '../container.js'
 export default async function (test, options) {
   if (options.grep) process.env.grep = options.grep
   if (options.ansi === false) chalk.level = 0
+  store.dryRun = true
   const configFile = options.config
   let codecept
 
@@ -20,9 +21,15 @@ export default async function (test, options) {
   }
 
   if (config.plugins) {
-    // disable all plugins by default, they can be enabled with -p option
+    // Disable plugins that block (interactive) or perform external I/O (AI/network).
+    // Leave the rest enabled so they can register support objects (e.g. auth registers
+    // `login`); helper calls inside those support fns are already no-op'd by HelperStep
+    // when store.dryRun is true.
+    const disableInDryRun = new Set(['pause', 'pauseOnFail', 'analyze', 'aiTrace', 'pageInfo', 'heal'])
     for (const plugin in config.plugins) {
-      config.plugins[plugin].enabled = false
+      if (disableInDryRun.has(plugin)) {
+        config.plugins[plugin].enabled = false
+      }
     }
   }
 
@@ -33,7 +40,6 @@ export default async function (test, options) {
     if (options.bootstrap) await codecept.bootstrap()
 
     codecept.loadTests()
-    store.dryRun = true
 
     if (!options.steps && !options.verbose && !options.debug) {
       await printTests(codecept.testFiles)

package/lib/command/init.js

@@ -15,7 +15,7 @@ import { test as generateTest } from './generate.js'
 const isLocal = installedLocally()
 
 const defaultConfig = {
-  tests: './*_test.js',
+  tests: './tests/*_test.js',
   output: '',
   helpers: {},
   include: {},
@@ -25,14 +25,6 @@ const defaultConfig = {
 }
 
 const helpers = ['Playwright', 'WebDriver', 'Puppeteer', 'REST', 'GraphQL', 'Appium']
-const noTranslation = 'English (no localization)'
-
-async function getTranslations() {
-  const translationsModule = await import('../../translations/index.js')
-  const translations = Object.keys(translationsModule.default || translationsModule)
-  translations.unshift(noTranslation)
-  return translations
-}
 
 const packages = []
 let isTypeScript = false
@@ -51,6 +43,7 @@ setCommonPlugins();
 `
 
 const defaultActor = `// in this file you can append custom step methods to 'I' object
+import { actor } from 'codeceptjs';
 
 export default function() {
   return actor({
@@ -63,6 +56,7 @@ export default function() {
 `
 
 const defaultActorTs = `// in this file you can append custom step methods to 'I' object
+import { actor } from 'codeceptjs';
 
 export = function() {
   return actor({
@@ -74,9 +68,9 @@ export = function() {
 }
 `
 
-export default async function (initPath) {
+export default async function (initPath, options = {}) {
   const testsPath = getTestRoot(initPath)
-  const translations = await getTranslations()
+  const skipPrompts = !!options.yes
 
   print()
   print(`  Welcome to ${colors.magenta.bold('CodeceptJS')} initialization tool`)
@@ -114,251 +108,265 @@ export default async function (initPath) {
     return
   }
 
-  inquirer
-    .prompt([
-      {
-        name: 'typescript',
-        type: 'confirm',
-        default: false,
-        message: 'Do you plan to write tests in TypeScript?',
-      },
-      {
-        name: 'tests',
-        type: 'input',
-        default: answers => `./*_test.${answers.typescript ? 'ts' : 'js'}`,
-        message: 'Where are your tests located?',
-      },
-      {
-        name: 'helper',
-        type: 'list',
-        choices: helpers,
-        default: 'Playwright',
-        message: 'What helpers do you want to use?',
-      },
-      {
-        name: 'jsonResponse',
-        type: 'confirm',
-        default: true,
-        message: 'Do you want to use JSONResponse helper for assertions on JSON responses? http://bit.ly/3ASVPy9',
-        when: answers => ['GraphQL', 'REST'].includes(answers.helper) === true,
-      },
-      {
-        name: 'output',
-        default: './output',
-        message: 'Where should logs, screenshots, and reports to be stored?',
-      },
-      {
-        name: 'translation',
-        type: 'list',
-        message: 'Do you want to enable localization for tests? http://bit.ly/3GNUBbh',
-        choices: translations,
-      },
-    ])
-    .then(async result => {
-      if (result.typescript === true) {
-        isTypeScript = true
-        extension = isTypeScript === true ? 'ts' : 'js'
-        packages.push('typescript')
-        packages.push('tsx')  // Add tsx for TypeScript support
-        packages.push('@types/node')
+  const result = skipPrompts
+    ? {
+        typescript: false,
+        tests: './tests/*_test.js',
+        helper: 'Playwright',
+        jsonResponse: false,
+        output: './output',
       }
+    : await inquirer.prompt([
+        {
+          name: 'typescript',
+          type: 'confirm',
+          default: false,
+          message: 'Do you plan to write tests in TypeScript?',
+        },
+        {
+          name: 'tests',
+          type: 'input',
+          default: answers => `./tests/*_test.${answers.typescript ? 'ts' : 'js'}`,
+          message: 'Where are your tests located?',
+        },
+        {
+          name: 'helper',
+          type: 'list',
+          choices: helpers,
+          default: 'Playwright',
+          message: 'What helpers do you want to use?',
+        },
+        {
+          name: 'jsonResponse',
+          type: 'confirm',
+          default: true,
+          message: 'Do you want to use JSONResponse helper for assertions on JSON responses? http://bit.ly/3ASVPy9',
+          when: answers => ['GraphQL', 'REST'].includes(answers.helper) === true,
+        },
+        {
+          name: 'output',
+          default: './output',
+          message: 'Where should logs, screenshots, and reports to be stored?',
+        },
+      ])
+
+  if (result.typescript === true) {
+    isTypeScript = true
+    extension = isTypeScript === true ? 'ts' : 'js'
+    packages.push('typescript')
+    packages.push('tsx')
+    packages.push('@types/node')
+  }
 
-      const config = defaultConfig
-      config.name = testsPath.split(path.sep).pop()
-      config.output = result.output
+  const config = defaultConfig
+  config.name = testsPath.split(path.sep).pop()
+  config.output = result.output
 
-      config.tests = result.tests
-      if (isTypeScript) {
-        config.tests = `${config.tests.replace(/\.js$/, `.${extension}`)}`
-        config.require = ['tsx/cjs']  // Add tsx/cjs loader for TypeScript tests
-      }
+  config.tests = result.tests
+  if (isTypeScript) {
+    config.tests = `${config.tests.replace(/\.js$/, `.${extension}`)}`
+    config.require = ['tsx/cjs']
+  }
+
+  const matchResults = config.tests.match(/[^*.]+/)
+  if (matchResults) {
+    mkdirp.sync(path.join(testsPath, matchResults[0]))
+  }
+
+  const helperName = result.helper
+  config.helpers[helperName] = {}
 
-      // create a directory tests if it is included in tests path
-      const matchResults = config.tests.match(/[^*.]+/)
-      if (matchResults) {
-        mkdirp.sync(path.join(testsPath, matchResults[0]))
+  if (result.jsonResponse === true) {
+    config.helpers.JSONResponse = {}
+  }
+
+  let helperConfigs = []
+
+  try {
+    const HelperModule = await import(`../helper/${helperName}.js`)
+    const Helper = HelperModule.default || HelperModule
+    if (Helper._checkRequirements) {
+      packages.concat(Helper._checkRequirements())
+    }
+
+    if (!Helper._config()) return
+    helperConfigs = helperConfigs.concat(
+      Helper._config().map(config => {
+        config.message = `[${helperName}] ${config.message}`
+        config.name = `${helperName}_${config.name}`
+        config.type = config.type || 'input'
+        return config
+      }),
+    )
+  } catch (err) {
+    error(err)
+  }
+
+  const finish = async () => {
+    const stepFile = `./steps_file.${extension}`
+    fs.writeFileSync(path.join(testsPath, stepFile), extension === 'ts' ? defaultActorTs : defaultActor)
+
+    config.include = { I: isTypeScript ? './steps_file' : stepFile }
+
+    print(`Steps file created at ${stepFile}`)
+
+    let configSource
+    const hasConfigure = isLocal && !initPath
+
+    if (isTypeScript) {
+      configSource = beautify(`export const config : CodeceptJS.MainConfig = ${inspect(config, false, 4, false)}`)
+
+      if (hasConfigure) configSource = importCodeceptConfigure + configHeader + configSource
+
+      fs.writeFileSync(typeScriptconfigFile, configSource, 'utf-8')
+      print(`Config created at ${typeScriptconfigFile}`)
+    } else {
+      configSource = beautify(`/** @type {CodeceptJS.MainConfig} */\nexport const config = ${inspect(config, false, 4, false)}`)
+
+      if (hasConfigure) configSource = importCodeceptConfigure + configHeader + configSource
+
+      fs.writeFileSync(configFile, configSource, 'utf-8')
+      print(`Config created at ${configFile}`)
+    }
+
+    if (config.output) {
+      if (!fileExists(config.output)) {
+        mkdirp.sync(path.join(testsPath, config.output))
+        print(`Directory for temporary output files created at '${config.output}'`)
+      } else {
+        print(`Directory for temporary output files is already created at '${config.output}'`)
       }
+    }
 
-      if (result.translation !== noTranslation) config.translation = result.translation
+    const jsconfig = {
+      compilerOptions: {
+        allowJs: true,
+      },
+    }
 
-      const helperName = result.helper
-      config.helpers[helperName] = {}
+    const tsconfig = {
+      'ts-node': {
+        files: true,
+      },
+      compilerOptions: {
+        target: 'es2018',
+        lib: ['es2018', 'DOM'],
+        esModuleInterop: true,
+        module: 'commonjs',
+        strictNullChecks: false,
+        types: ['codeceptjs', 'node'],
+        declaration: true,
+        skipLibCheck: true,
+      },
+      exclude: ['node_modules'],
+    }
 
-      if (result.jsonResponse === true) {
-        config.helpers.JSONResponse = {}
+    if (isTypeScript) {
+      const tsconfigJson = beautify(JSON.stringify(tsconfig))
+      const tsconfigFile = path.join(testsPath, 'tsconfig.json')
+      if (fileExists(tsconfigFile)) {
+        print(`tsconfig.json already exists at ${tsconfigFile}`)
+      } else {
+        fs.writeFileSync(tsconfigFile, tsconfigJson)
+      }
+    } else {
+      const jsconfigJson = beautify(JSON.stringify(jsconfig))
+      const jsconfigFile = path.join(testsPath, 'jsconfig.json')
+      if (fileExists(jsconfigFile)) {
+        print(`jsconfig.json already exists at ${jsconfigFile}`)
+      } else {
+        fs.writeFileSync(jsconfigFile, jsconfigJson)
+        print(`Intellisense enabled in ${jsconfigFile}`)
       }
+    }
 
-      let helperConfigs = []
+    const generateDefinitionsManually = colors.bold(`To get auto-completion support, please generate type definitions: ${colors.green('npx codeceptjs def')}`)
 
+    if (packages) {
       try {
-        const HelperModule = await import(`../helper/${helperName}.js`)
-        const Helper = HelperModule.default || HelperModule
-        if (Helper._checkRequirements) {
-          packages.concat(Helper._checkRequirements())
-        }
-
-        if (!Helper._config()) return
-        helperConfigs = helperConfigs.concat(
-          Helper._config().map(config => {
-            config.message = `[${helperName}] ${config.message}`
-            config.name = `${helperName}_${config.name}`
-            config.type = config.type || 'input'
-            return config
-          }),
-        )
+        install(packages)
       } catch (err) {
-        error(err)
+        print(colors.bold.red(err.toString()))
+        print()
+        print(colors.bold.red('Please install next packages manually:'))
+        print(`npm i ${packages.join(' ')} --save-dev`)
+        print()
+        print('Things to do after missing packages installed:')
+        print('☑', generateDefinitionsManually)
+        print('☑ Create first test:', colors.green('npx codeceptjs gt'))
+        print(colors.bold.magenta('Find more information at https://codecept.io'))
+        return
       }
+    }
 
-      const finish = async () => {
-        // create steps file by default
-        // no extra step file for typescript (as it doesn't match TS conventions)
-        const stepFile = `./steps_file.${extension}`
-        fs.writeFileSync(path.join(testsPath, stepFile), extension === 'ts' ? defaultActorTs : defaultActor)
-
-        if (isTypeScript) {
-          config.include = await _actorTranslation('./steps_file', config.translation, translations)
-        } else {
-          config.include = await _actorTranslation(stepFile, config.translation, translations)
-        }
-
-        print(`Steps file created at ${stepFile}`)
-
-        let configSource
-        const hasConfigure = isLocal && !initPath
-
-        if (isTypeScript) {
-          configSource = beautify(`export const config : CodeceptJS.MainConfig = ${inspect(config, false, 4, false)}`)
-
-          if (hasConfigure) configSource = importCodeceptConfigure + configHeader + configSource
-
-          fs.writeFileSync(typeScriptconfigFile, configSource, 'utf-8')
-          print(`Config created at ${typeScriptconfigFile}`)
-        } else {
-          configSource = beautify(`/** @type {CodeceptJS.MainConfig} */\nexport const config = ${inspect(config, false, 4, false)}`)
-
-          if (hasConfigure) configSource = importCodeceptConfigure + configHeader + configSource
-
-          fs.writeFileSync(configFile, configSource, 'utf-8')
-          print(`Config created at ${configFile}`)
-        }
-
-        if (config.output) {
-          if (!fileExists(config.output)) {
-            mkdirp.sync(path.join(testsPath, config.output))
-            print(`Directory for temporary output files created at '${config.output}'`)
-          } else {
-            print(`Directory for temporary output files is already created at '${config.output}'`)
-          }
-        }
-
-        const jsconfig = {
-          compilerOptions: {
-            allowJs: true,
-          },
-        }
-
-        const tsconfig = {
-          'ts-node': {
-            files: true,
-          },
-          compilerOptions: {
-            target: 'es2018',
-            lib: ['es2018', 'DOM'],
-            esModuleInterop: true,
-            module: 'commonjs',
-            strictNullChecks: false,
-            types: ['codeceptjs', 'node'],
-            declaration: true,
-            skipLibCheck: true,
-          },
-          exclude: ['node_modules'],
-        }
-
-        if (isTypeScript) {
-          const tsconfigJson = beautify(JSON.stringify(tsconfig))
-          const tsconfigFile = path.join(testsPath, 'tsconfig.json')
-          if (fileExists(tsconfigFile)) {
-            print(`tsconfig.json already exists at ${tsconfigFile}`)
-          } else {
-            fs.writeFileSync(tsconfigFile, tsconfigJson)
-          }
-        } else {
-          const jsconfigJson = beautify(JSON.stringify(jsconfig))
-          const jsconfigFile = path.join(testsPath, 'jsconfig.json')
-          if (fileExists(jsconfigFile)) {
-            print(`jsconfig.json already exists at ${jsconfigFile}`)
-          } else {
-            fs.writeFileSync(jsconfigFile, jsconfigJson)
-            print(`Intellisense enabled in ${jsconfigFile}`)
-          }
-        }
-
-        const generateDefinitionsManually = colors.bold(`To get auto-completion support, please generate type definitions: ${colors.green('npx codeceptjs def')}`)
-
-        if (packages) {
-          try {
-            install(packages)
-          } catch (err) {
-            print(colors.bold.red(err.toString()))
-            print()
-            print(colors.bold.red('Please install next packages manually:'))
-            print(`npm i ${packages.join(' ')} --save-dev`)
-            print()
-            print('Things to do after missing packages installed:')
-            print('☑', generateDefinitionsManually)
-            print('☑ Create first test:', colors.green('npx codeceptjs gt'))
-            print(colors.bold.magenta('Find more information at https://codecept.io'))
-            return
-          }
-        }
-
-        try {
-          generateDefinitions(testsPath, {})
-        } catch (err) {
-          print(colors.bold.red("Couldn't generate type definitions"))
-          print(colors.red(err.toString()))
-          print('Skipping type definitions...')
-          print(generateDefinitionsManually)
-        }
-
-        print('')
-        success(' Almost ready... Next step:')
-
-        const generatedTest = generateTest(testsPath)
-        if (!generatedTest) return
-        generatedTest.then(() => {
-          print('\n--')
-          print(colors.bold.green('CodeceptJS Installed! Enjoy supercharged testing! 🤩'))
-          print(colors.bold.magenta('Find more information at https://codecept.io'))
-          print()
-        })
-      }
+    try {
+      generateDefinitions(testsPath, {})
+    } catch (err) {
+      print(colors.bold.red("Couldn't generate type definitions"))
+      print(colors.red(err.toString()))
+      print('Skipping type definitions...')
+      print(generateDefinitionsManually)
+    }
+
+    print('')
+    success(' Almost ready... Next step:')
+
+    if (skipPrompts) {
+      print('\n--')
+      print(colors.bold.green('CodeceptJS Installed! Enjoy supercharged testing! 🤩'))
+      print(colors.bold.magenta('Find more information at https://codecept.io'))
+      print()
+      return
+    }
 
-      print('Configure helpers...')
-      inquirer.prompt(helperConfigs).then(async helperResult => {
-        if (helperResult.Playwright_browser === 'electron') {
-          delete helperResult.Playwright_url
-          delete helperResult.Playwright_show
-
-          helperResult.Playwright_electron = {
-            executablePath: '// require("electron") or require("electron-forge")',
-            args: ['path/to/your/main.js'],
-          }
-        }
-
-        Object.keys(helperResult).forEach(key => {
-          const parts = key.split('_')
-          const helperName = parts[0]
-          const configName = parts[1]
-          if (!configName) return
-          config.helpers[helperName][configName] = helperResult[key]
-        })
-
-        print('')
-        await finish()
-      })
+    const generatedTest = generateTest(testsPath)
+    if (!generatedTest) return
+    generatedTest.then(() => {
+      print('\n--')
+      print(colors.bold.green('CodeceptJS Installed! Enjoy supercharged testing! 🤩'))
+      print(colors.bold.magenta('Find more information at https://codecept.io'))
+      print()
     })
+  }
+
+  const helperResult = skipPrompts
+    ? defaultHelperAnswers(helperName)
+    : await (async () => {
+        print('Configure helpers...')
+        return inquirer.prompt(helperConfigs)
+      })()
+
+  if (helperResult.Playwright_browser === 'electron') {
+    delete helperResult.Playwright_url
+    delete helperResult.Playwright_show
+
+    helperResult.Playwright_electron = {
+      executablePath: '// require("electron") or require("electron-forge")',
+      args: ['path/to/your/main.js'],
+    }
+  }
+
+  Object.keys(helperResult).forEach(key => {
+    const parts = key.split('_')
+    const hName = parts[0]
+    const configName = parts[1]
+    if (!configName) return
+    config.helpers[hName][configName] = helperResult[key]
+  })
+
+  print('')
+  await finish()
+}
+
+function defaultHelperAnswers(helperName) {
+  if (helperName === 'Playwright') {
+    return {
+      Playwright_browser: 'chromium',
+      Playwright_url: process.env.BASE_URL || 'http://localhost',
+      Playwright_show: false,
+    }
+  }
+  return {}
 }
 
 function install(dependencies) {
@@ -399,30 +407,3 @@ function install(dependencies) {
   }
   return true
 }
-
-async function _actorTranslation(stepFile, translationSelected, translations) {
-  let actor
-
-  for (const translationAvailable of translations) {
-    if (actor) {
-      break
-    }
-
-    if (translationSelected === translationAvailable) {
-      const translationsModule = await import('../../translations/index.js')
-      const nameOfActor = (translationsModule.default || translationsModule)[translationAvailable].I
-
-      actor = {
-        [nameOfActor]: stepFile,
-      }
-    }
-  }
-
-  if (!actor) {
-    actor = {
-      I: stepFile,
-    }
-  }
-
-  return actor
-}