feat(webapi): saveScreenshot with custom path

.gitignore

@@ -10,6 +10,7 @@ website
 .idea
 docs/build
 test/data/output
+test/data/custom
 test/acceptance/output
 test/bdd/output
 examples/output
@@ -26,4 +27,4 @@ package-lock.json
 yarn.lock
 /.vs
 typings/types.d.ts
-typings/promiseBasedTypes.d.ts
+typings/promiseBasedTypes.d.ts

docs/helpers/Appium.md

@@ -1139,7 +1139,7 @@ Returns **[Promise][6]<[string][5]>** attribute value
 
 ### saveScreenshot
 
-Saves a screenshot to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+Saves a screenshot to output folder (set in codecept.conf.ts or codecept.conf.js).
 Filename is relative to output folder.
 
 ```js

docs/helpers/Nightmare.md

@@ -794,7 +794,7 @@ Returns **void** automatically synchronized promise through #recorder
 
 ### saveElementScreenshot
 
-Saves screenshot of the specified locator to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+Saves screenshot of the specified locator to output folder (set in codecept.conf.ts or codecept.conf.js).
 Filename is relative to output folder.
 
 ```js
@@ -810,7 +810,7 @@ Returns **void** automatically synchronized promise through #recorder
 
 ### saveScreenshot
 
-Saves a screenshot to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+Saves a screenshot to output folder (set in codecept.conf.ts or codecept.conf.js).
 Filename is relative to output folder.
 Optionally resize the window to the full available page `scrollHeight` and `scrollWidth` to capture the entire page by passing `true` in as the second argument.
 

docs/helpers/Playwright.md

@@ -1799,7 +1799,7 @@ Returns **void** automatically synchronized promise through #recorder
 
 ### saveElementScreenshot
 
-Saves screenshot of the specified locator to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+Saves screenshot of the specified locator to output folder (set in codecept.conf.ts or codecept.conf.js).
 Filename is relative to output folder.
 
 ```js
@@ -1815,13 +1815,14 @@ Returns **void** automatically synchronized promise through #recorder
 
 ### saveScreenshot
 
-Saves a screenshot to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+Saves a screenshot to output folder (set in codecept.conf.ts or codecept.conf.js).
 Filename is relative to output folder.
 Optionally resize the window to the full available page `scrollHeight` and `scrollWidth` to capture the entire page by passing `true` in as the second argument.
 
 ```js
 I.saveScreenshot('debug.png');
 I.saveScreenshot('debug.png', true) //resizes to available scrollHeight and scrollWidth before taking screenshot
+I.saveScreenshot('customFolder/debug.png') //saves to customFolder/debug.png
 ```
 
 #### Parameters

docs/helpers/Protractor.md

@@ -1036,7 +1036,7 @@ Returns **void** automatically synchronized promise through #recorder
 
 ### saveElementScreenshot
 
-Saves screenshot of the specified locator to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+Saves screenshot of the specified locator to output folder (set in codecept.conf.ts or codecept.conf.js).
 Filename is relative to output folder.
 
 ```js
@@ -1052,7 +1052,7 @@ Returns **void** automatically synchronized promise through #recorder
 
 ### saveScreenshot
 
-Saves a screenshot to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+Saves a screenshot to output folder (set in codecept.conf.ts or codecept.conf.js).
 Filename is relative to output folder.
 Optionally resize the window to the full available page `scrollHeight` and `scrollWidth` to capture the entire page by passing `true` in as the second argument.
 

docs/helpers/Puppeteer.md

@@ -1567,7 +1567,7 @@ This action supports [React locators](https://codecept.io/react#locators)
 
 ### saveElementScreenshot
 
-Saves screenshot of the specified locator to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+Saves screenshot of the specified locator to output folder (set in codecept.conf.ts or codecept.conf.js).
 Filename is relative to output folder.
 
 ```js
@@ -1583,13 +1583,14 @@ Returns **void** automatically synchronized promise through #recorder
 
 ### saveScreenshot
 
-Saves a screenshot to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+Saves a screenshot to output folder (set in codecept.conf.ts or codecept.conf.js).
 Filename is relative to output folder.
 Optionally resize the window to the full available page `scrollHeight` and `scrollWidth` to capture the entire page by passing `true` in as the second argument.
 
 ```js
 I.saveScreenshot('debug.png');
 I.saveScreenshot('debug.png', true) //resizes to available scrollHeight and scrollWidth before taking screenshot
+I.saveScreenshot('customFolder/debug.png') //saves to customFolder/debug.png
 ```
 
 #### Parameters

docs/helpers/TestCafe.md

@@ -766,7 +766,7 @@ Returns **void** automatically synchronized promise through #recorder
 
 ### saveElementScreenshot
 
-Saves screenshot of the specified locator to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+Saves screenshot of the specified locator to output folder (set in codecept.conf.ts or codecept.conf.js).
 Filename is relative to output folder.
 
 ```js
@@ -782,13 +782,14 @@ Returns **void** automatically synchronized promise through #recorder
 
 ### saveScreenshot
 
-Saves a screenshot to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+Saves a screenshot to output folder (set in codecept.conf.ts or codecept.conf.js).
 Filename is relative to output folder.
 Optionally resize the window to the full available page `scrollHeight` and `scrollWidth` to capture the entire page by passing `true` in as the second argument.
 
 ```js
 I.saveScreenshot('debug.png');
 I.saveScreenshot('debug.png', true) //resizes to available scrollHeight and scrollWidth before taking screenshot
+I.saveScreenshot('customFolder/debug.png') //saves to customFolder/debug.png
 ```
 
 #### Parameters

docs/helpers/WebDriver.md

@@ -1657,7 +1657,7 @@ Placeholder for ~ locator only test case write once run on both Appium and WebDr
 
 ### saveElementScreenshot
 
-Saves screenshot of the specified locator to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+Saves screenshot of the specified locator to output folder (set in codecept.conf.ts or codecept.conf.js).
 Filename is relative to output folder.
 
 ```js
@@ -1673,13 +1673,14 @@ Returns **void** automatically synchronized promise through #recorder
 
 ### saveScreenshot
 
-Saves a screenshot to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+Saves a screenshot to output folder (set in codecept.conf.ts or codecept.conf.js).
 Filename is relative to output folder.
 Optionally resize the window to the full available page `scrollHeight` and `scrollWidth` to capture the entire page by passing `true` in as the second argument.
 
 ```js
 I.saveScreenshot('debug.png');
 I.saveScreenshot('debug.png', true) //resizes to available scrollHeight and scrollWidth before taking screenshot
+I.saveScreenshot('customFolder/debug.png') //saves to customFolder/debug.png
 ```
 
 #### Parameters

docs/webapi/saveElementScreenshot.mustache

@@ -1,4 +1,4 @@
-Saves screenshot of the specified locator to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+Saves screenshot of the specified locator to output folder (set in codecept.conf.ts or codecept.conf.js).
 Filename is relative to output folder.
 
 ```js

docs/webapi/saveScreenshot.mustache

@@ -1,10 +1,11 @@
-Saves a screenshot to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+Saves a screenshot to output folder (set in codecept.conf.ts or codecept.conf.js).
 Filename is relative to output folder.
 Optionally resize the window to the full available page `scrollHeight` and `scrollWidth` to capture the entire page by passing `true` in as the second argument.
 
 ```js
 I.saveScreenshot('debug.png');
 I.saveScreenshot('debug.png', true) //resizes to available scrollHeight and scrollWidth before taking screenshot
+I.saveScreenshot('customFolder/debug.png') //saves to customFolder/debug.png
 ```
 
 @param {string} fileName file name to save.

lib/helper/Appium.js

@@ -1672,7 +1672,7 @@ class Appium extends Webdriver {
   }
 
   /**
-   * Saves a screenshot to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+   * Saves a screenshot to output folder (set in codecept.conf.ts or codecept.conf.js).
    * Filename is relative to output folder.
    *
    * ```js

lib/utils.js

@@ -312,9 +312,13 @@ module.exports.deleteDir = function (dir_path) {
  * @param fileName {string} - filename.
  */
 module.exports.screenshotOutputFolder = function (fileName) {
-  const fileSep = path.sep
+  const isPathLike = fileName.includes('/') || fileName.includes('\\')
 
-  if (!fileName.includes(fileSep) || fileName.includes('record_')) {
+  if (isPathLike && !(fileName.includes(global.output_dir) || fileName.includes(global.codecept_dir))) {
+    return path.resolve(fileName)
+  }
+
+  if (!isPathLike || fileName.includes('record_')) {
     return path.resolve(global.output_dir, fileName)
   }
   return path.resolve(global.codecept_dir, fileName)

runok.js

@@ -184,7 +184,7 @@ Our community prepared some valuable recipes for setting up CI systems with Code
     // generate documentation for helpers
     const files = fs.readdirSync('lib/helper').filter(f => path.extname(f) === '.js')
 
-    const ignoreList = ['Polly', 'MockRequest'] // WebDriverIO won't be documented and should be removed
+    const ignoreList = ['Polly', 'MockRequest', 'Nightmare', 'Protractor'] // WebDriverIO won't be documented and should be removed
 
     const partials = fs.readdirSync('docs/webapi').filter(f => path.extname(f) === '.mustache')
     const placeholders = partials.map(file => `{{> ${path.basename(file, '.mustache')} }}`)
@@ -587,7 +587,7 @@ const exec = require('child_process').exec
 const { codecept_dir, codecept_run } = require('./consts')
 const debug = require('debug')('codeceptjs:tests')
 
-const config_run_config = (config, grep, verbose = false) => 
+const config_run_config = (config, grep, verbose = false) =>
   \`\${codecept_run} \${verbose ? '--verbose' : ''} --config \${codecept_dir}/configs/${featureName}/\${config} \${grep ? \`--grep "\${grep}"\` : ''}\`
 
 describe('CodeceptJS ${featureName}', function () {

test/helper/webapi.js

@@ -872,6 +872,7 @@ module.exports.tests = function () {
   describe('#saveScreenshot', () => {
     beforeEach(() => {
       global.output_dir = path.join(global.codecept_dir, 'output')
+      global.custom_dir = path.join(global.codecept_dir, 'custom')
     })
 
     it('should create a screenshot file in output dir', async () => {
@@ -887,6 +888,15 @@ module.exports.tests = function () {
       await I.saveScreenshot(`screenshot_full_${+sec}.png`, true)
       assert.ok(fileExists(path.join(global.output_dir, `screenshot_full_${+sec}.png`)), null, 'file does not exists')
     })
+
+    it('should create a screenshot file in custom dir', async () => {
+      if (isHelper('TestCafe')) return
+
+      const sec = new Date().getUTCMilliseconds()
+      await I.amOnPage('/')
+      await I.saveScreenshot(path.resolve(global.custom_dir, `screenshot_${sec}.png`))
+      assert.ok(fileExists(path.join(global.custom_dir, `screenshot_${sec}.png`)), null, 'file does not exists')
+    })
   })
 
   describe('cookies : #setCookie, #clearCookies, #seeCookie, #waitForCookie', () => {

test/unit/utils_test.js

@@ -1,7 +1,5 @@
-let expect
-import('chai').then(chai => {
-  expect = chai.expect
-})
+const { expect } = require('chai')
+
 const os = require('os')
 const path = require('path')
 const sinon = require('sinon')
@@ -330,6 +328,15 @@ describe('utils', () => {
         expect(_path).eql('/Users/someuser/workbase/project1/test_output/screenshot1.failed.png')
       }
     })
+
+    it.only('saves screenshot to custom path', () => {
+      const _path = utils.screenshotOutputFolder('/Users/someuser/workbase/project1/custom_path/'.replace(/\//g, path.sep) + 'screenshot1.failed.png')
+      if (os.platform() === 'win32') {
+        expect(_path).eql(path.resolve(global.codecept_dir, '/Users/someuser/workbase/project1/custom_path/screenshot1.failed.png'))
+      } else {
+        expect(_path).eql('/Users/someuser/workbase/project1/custom_path/screenshot1.failed.png')
+      }
+    })
   })
 
   describe('#requireWithFallback', () => {