feat: introduce playwright locator

docs/helpers/Playwright.md

@@ -80,6 +80,7 @@ Type: [object][6]
 - `bypassCSP` **[boolean][26]?** bypass Content Security Policy or CSP
 - `highlightElement` **[boolean][26]?** highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
 - `recordHar` **[object][6]?** record HAR and will be saved to `output/har`. See more of [HAR options][3].
+- `testIdAttribute` **[string][9]?** locate elements based on the testIdAttribute. See more of [locate by test id][49].
 
 
 
@@ -2775,3 +2776,5 @@ Returns **void** automatically synchronized promise through #recorder
 [47]: https://playwright.dev/docs/browsers/#google-chrome--microsoft-edge
 
 [48]: https://playwright.dev/docs/api/class-consolemessage#console-message-type
+
+[49]: https://playwright.dev/docs/locators#locate-by-test-id

docs/locators.md

@@ -14,10 +14,11 @@ CodeceptJS provides flexible strategies for locating elements:
 * [Custom Locator Strategies](#custom-locators): by data attributes or whatever you prefer.
 * [Shadow DOM](/shadow): to access shadow dom elements
 * [React](/react): to access React elements by component names and props
+* Playwright: to access locator supported by Playwright, namely [_react](https://playwright.dev/docs/other-locators#react-locator), [_vue](https://playwright.dev/docs/other-locators#vue-locator), [data-testid](https://playwright.dev/docs/locators#locate-by-test-id)
 
 Most methods in CodeceptJS use locators which can be either a string or an object.
 
-If the locator is an object, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, `react`, `class`or `shadow`) and the value being the locator itself. This is called a "strict" locator.
+If the locator is an object, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, `react`, `class`, `shadow` or `pw`) and the value being the locator itself. This is called a "strict" locator.
 
 Examples:
 
@@ -26,6 +27,7 @@ Examples:
 * {css: 'input[type=input][value=foo]'} matches `<input type="input" value="foo">`
 * {xpath: "//input[@type='submit'][contains(@value, 'foo')]"} matches `<input type="submit" value="foobar">`
 * {class: 'foo'} matches `<div class="foo">`
+* { pw: '_react=t[name = "="]' }
 
 Writing good locators can be tricky.
 The Mozilla team has written an excellent guide titled [Writing reliable locators for Selenium and WebDriver tests](https://blog.mozilla.org/webqa/2013/09/26/writing-reliable-locators-for-selenium-and-webdriver-tests/).

lib/helper/Playwright.js

@@ -33,7 +33,7 @@ const ElementNotFound = require('./errors/ElementNotFound');
 const RemoteBrowserConnectionRefused = require('./errors/RemoteBrowserConnectionRefused');
 const Popup = require('./extras/Popup');
 const Console = require('./extras/Console');
-const { findReact, findVue } = require('./extras/PlaywrightReactVueLocator');
+const { findReact, findVue, findByPlaywrightLocator } = require('./extras/PlaywrightReactVueLocator');
 
 let playwright;
 let perfTiming;
@@ -100,6 +100,7 @@ const pathSeparator = path.sep;
  * @prop {boolean} [bypassCSP] - bypass Content Security Policy or CSP
  * @prop {boolean} [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
  * @prop {object} [recordHar] - record HAR and will be saved to `output/har`. See more of [HAR options](https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-har).
+ * @prop {string} [testIdAttribute=data-testid] - locate elements based on the testIdAttribute. See more of [locate by test id](https://playwright.dev/docs/locators#locate-by-test-id).
  */
 const config = {};
 
@@ -379,6 +380,7 @@ class Playwright extends Helper {
  highlightElement: false,
  };
 
+ process.env.testIdAttribute = 'data-testid';
  config = Object.assign(defaults, config);
 
  if (availableBrowsers.indexOf(config.browser) < 0) {
@@ -464,6 +466,7 @@ class Playwright extends Helper {
  try {
  await playwright.selectors.register('__value', createValueEngine);
  await playwright.selectors.register('__disabled', createDisabledEngine);
+ if (process.env.testIdAttribute) await playwright.selectors.setTestIdAttribute(process.env.testIdAttribute);
  } catch (e) {
  console.warn(e);
  }
@@ -3455,13 +3458,16 @@ function buildLocatorString(locator) {
 async function findElements(matcher, locator) {
  if (locator.react) return findReact(matcher, locator);
  if (locator.vue) return findVue(matcher, locator);
+ if (locator.pw) return findByPlaywrightLocator.call(this, matcher, locator);
  locator = new Locator(locator, 'css');
 
  return matcher.locator(buildLocatorString(locator)).all();
 }
 
 async function findElement(matcher, locator) {
  if (locator.react) return findReact(matcher, locator);
+ if (locator.vue) return findVue(matcher, locator);
+ if (locator.pw) return findByPlaywrightLocator.call(this, matcher, locator);
  locator = new Locator(locator, 'css');
 
  return matcher.locator(buildLocatorString(locator)).first();
@@ -3517,6 +3523,7 @@ async function proceedClick(locator, context = null, options = {}) {
 async function findClickable(matcher, locator) {
  if (locator.react) return findReact(matcher, locator);
  if (locator.vue) return findVue(matcher, locator);
+ if (locator.pw) return findByPlaywrightLocator.call(this, matcher, locator);
 
  locator = new Locator(locator);
  if (!locator.isFuzzy()) return findElements.call(this, matcher, locator);

lib/helper/extras/PlaywrightReactVueLocator.js

@@ -20,6 +20,11 @@ async function findVue(matcher, locator) {
  return matcher.locator(_locator).all();
 }
 
+async function findByPlaywrightLocator(matcher, locator) {
+ if (locator && locator.toString().includes(process.env.testIdAttribute)) return matcher.getByTestId(locator.pw.value.split('=')[1]);
+ return matcher.locator(locator.pw).all();
+}
+
 function propBuilder(props) {
  let _props = '';
 
@@ -35,4 +40,4 @@ function propBuilder(props) {
  return _props;
 }
 
-module.exports = { findReact, findVue };
+module.exports = { findReact, findVue, findByPlaywrightLocator };

lib/locator.js

@@ -3,7 +3,7 @@ const { sprintf } = require('sprintf-js');
 
 const { xpathLocator } = require('./utils');
 
-const locatorTypes = ['css', 'by', 'xpath', 'id', 'name', 'fuzzy', 'frame', 'shadow'];
+const locatorTypes = ['css', 'by', 'xpath', 'id', 'name', 'fuzzy', 'frame', 'shadow', 'pw'];
 /** @class */
 class Locator {
  /**
@@ -51,6 +51,9 @@ class Locator {
  if (isShadow(locator)) {
  this.type = 'shadow';
  }
+ if (isPlaywrightLocator(locator)) {
+ this.type = 'pw';
+ }
 
  Locator.filters.forEach(f => f(locator, this));
  }
@@ -71,6 +74,8 @@ class Locator {
  return this.value;
  case 'shadow':
  return { shadow: this.value };
+ case 'pw':
+ return { pw: this.value };
  }
  return this.value;
  }
@@ -115,6 +120,13 @@ class Locator {
  return this.type === 'css';
  }
 
+ /**
+ * @returns {boolean}
+ */
+ isPlaywrightLocator() {
+ return this.type === 'pw';
+ }
+
  /**
  * @returns {boolean}
  */
@@ -522,6 +534,16 @@ function removePrefix(xpath) {
  .replace(/^(\.|\/)+/, '');
 }
 
+/**
+ * @private
+ * check if the locator is a Playwright locator
+ * @param {string} locator
+ * @returns {boolean}
+ */
+function isPlaywrightLocator(locator) {
+ return locator.includes('_react') || locator.includes('_vue') || locator.includes('data-testid');
+}
+
 /**
  * @private
  * @param {CodeceptJS.LocatorOrString} locator

test/acceptance/react_test.js

@@ -1,6 +1,8 @@
+const { I } = inject();
+
 Feature('React Selectors');
 
-Scenario('props @Puppeteer @Playwright', ({ I }) => {
+Scenario('props @Puppeteer @Playwright', () => {
  I.amOnPage('https://codecept.io/test-react-calculator/');
  I.click('7');
  I.click({ react: 't', props: { name: '=' } });
@@ -11,10 +13,21 @@ Scenario('props @Puppeteer @Playwright', ({ I }) => {
  I.seeElement({ react: 't', props: { value: '10' } });
 });
 
-Scenario('component name @Puppeteer @Playwright', ({ I }) => {
+Scenario('component name @Puppeteer @Playwright', () => {
  I.amOnPage('http://negomi.github.io/react-burger-menu/');
  I.click({ react: 'BurgerIcon' });
  I.waitForVisible('#slide', 10);
  I.click('Alerts');
  I.seeElement({ react: 'Demo' });
 });
+
+Scenario('using playwright locator @Playwright', () => {
+ I.amOnPage('https://codecept.io/test-react-calculator/');
+ I.click('7');
+ I.click({ pw: '_react=t[name = "="]' });
+ I.seeElement({ pw: '_react=t[value = "7"]' });
+ I.click({ pw: '_react=t[name = "+"]' });
+ I.click({ pw: '_react=t[name = "3"]' });
+ I.click({ pw: '_react=t[name = "="]' });
+ I.seeElement({ pw: '_react=t[value = "10"]' });
+});

test/data/app/view/index.php

@@ -2,7 +2,7 @@
  <title>TestEd Beta 2.0</title>
 <body>
 
-<h1>Welcome to test app!</h1>
+<h1 data-testid="welcome">Welcome to test app!</h1>
 <h2>With&nbsp;special&nbsp;space chars</h1>
 
 <div class="notice" qa-id = "test"><?php if (isset($notice)) echo $notice; ?></div>

test/helper/Playwright_test.js

@@ -1678,3 +1678,39 @@ describe('Playwright - HAR', () => {
  });
  });
 });
+
+describe('using data-testid attribute', () => {
+ before(() => {
+ global.codecept_dir = path.join(__dirname, '/../data');
+ global.output_dir = path.join(`${__dirname}/../data/output`);
+
+ I = new Playwright({
+ url: siteUrl,
+ windowSize: '500x700',
+ show: false,
+ restart: true,
+ browser: 'chromium',
+ });
+ I._init();
+ return I._beforeSuite();
+ });
+
+ beforeEach(async () => {
+ return I._before().then(() => {
+ page = I.page;
+ browser = I.browser;
+ });
+ });
+
+ afterEach(async () => {
+ return I._after();
+ });
+
+ it('should find element by data-testid attribute', async () => {
+ await I.amOnPage('/');
+
+ const webElements = await I.grabWebElements({ pw: '[data-testid="welcome"]' });
+ assert.equal(webElements[0]._selector, '[data-testid="welcome"] >> nth=0');
+ assert.equal(webElements.length, 1);
+ });
+});

test/unit/locator_test.js

@@ -243,6 +243,27 @@ describe('Locator', () => {
  expect(l.value).to.equal('foo');
  expect(l.toString()).to.equal('foo');
  });
+
+ it('should create playwright locator - _react', () => {
+ const l = new Locator({ pw: '_react=button' });
+ expect(l.type).to.equal('pw');
+ expect(l.value).to.equal('_react=button');
+ expect(l.toString()).to.equal('{pw: _react=button}');
+ });
+
+ it('should create playwright locator - _vue', () => {
+ const l = new Locator({ pw: '_vue=button' });
+ expect(l.type).to.equal('pw');
+ expect(l.value).to.equal('_vue=button');
+ expect(l.toString()).to.equal('{pw: _vue=button}');
+ });
+
+ it('should create playwright locator - data-testid', () => {
+ const l = new Locator({ pw: '[data-testid="directions"]' });
+ expect(l.type).to.equal('pw');
+ expect(l.value).to.equal('[data-testid="directions"]');
+ expect(l.toString()).to.equal('{pw: [data-testid="directions"]}');
+ });
  });
 
  describe('with object argument', () => {

typings/index.d.ts

@@ -442,8 +442,8 @@ declare namespace CodeceptJS {
  | { react: string }
  | { vue: string }
  | { shadow: string[] }
- | { custom: string };
-
+ | { custom: string }
+ | { pw: string };
  interface CustomLocators {}
  interface OtherLocators { props?: object }
  type LocatorOrString =