Adding playwright test documentation

Author: karanshah-browserstack

README.md

@@ -97,6 +97,19 @@ If you are using Jest to run your Playwright tests, you can run all your playwri
 5. If you are trying to run your own Jest tests on BrowserStack, then you need to ensure that you have configured the `connectOptions` and `browsers` as shown in the `module.exports` of the config file.
 6. Run the sample jest script using `npm test` which runs the test `google.test.js` across 3 browsers in BrowserStack serially. Your can also configure Jest to run your tests in parallel.
 
+## Playwright with Test Runner
+
+If you are using Playwright Test Runner to run your Playwright tests, you can run all your playwright-test tests on BrowserStack as well. Follow the steps below to run the sample tests in this repository:
+
+1. Clone this repository using `git clone https://github.com/browserstack/playwright-browserstack.git` (if not already done).
+2. Go inside the directory playwright-test using `cd playwright-test`
+3. Install the dependencies using `npm install`
+4. Put in your credentials in the file `fixtures.js` in the caps part.
+5. If you are trying to run your own tests on BrowserStack, then you need to ensure that you have configured the `projects` correctly in `playwright.config.js` file.
+6. Run the sample test script using `npm run test` which runs all the tests inside tests directory across 5 browsers in BrowserStack.
+7. Run the sample test script using `npm run test:local` and add `browserstack.local:true` in the file `fixture.js` in caps part which runs all the tests inside tests directory across 5 browsers in BrowserStack.
+8. If you want to run your tests locally, you just need to configure the `projects` without name `@browserstack` in `playwright.config.js` file.
+
 ## Facing issues?
 
 If you are facing any issue with any of the above or any other issue in trying to run your Playwright tests on BrowserStack, you can [reach out to support](https://www.browserstack.com/contact#technical-support), select product as `Automate` and post your query there.

playwright-test/fixtures.js

@@ -0,0 +1,74 @@
+const base = require('@playwright/test');
+const cp = require('child_process');
+const clientPlaywrightVersion = cp
+  .execSync('npx playwright --version')
+  .toString()
+  .trim()
+  .split(' ')[1];
+const BrowserStackLocal = require('browserstack-local');
+
+const caps = {
+  browser: 'chrome',
+  os: 'osx',
+  os_version: 'catalina',
+  name: 'My first playwright test',
+  build: 'playwright-build-1',
+  'browserstack.username': process.env.BROWSERSTACK_USERNAME || 'YOUR_USERNAME',
+  'browserstack.accessKey':
+    process.env.BROWSERSTACK_ACCESS_KEY || 'YOUR_ACCESS_KEY',
+  'client.playwrightVersion': clientPlaywrightVersion,
+};
+
+exports.bsLocal = new BrowserStackLocal.Local();
+
+// replace YOUR_ACCESS_KEY with your key. You can also set an environment variable - "BROWSERSTACK_ACCESS_KEY".
+exports.BS_LOCAL_ARGS = {
+  key: process.env.BROWSERSTACK_ACCESS_KEY || 'YOUR_ACCESS_KEY',
+};
+
+const patchCaps = (name) => {
+  let combination = name.split(/@browserstack/)[0];
+  let [browerCaps, osCaps] = combination.split(/:/);
+  let [browser, browser_version] = browerCaps.split(/@/);
+  let osCapsSplit = osCaps.split(/ /);
+  let os = osCapsSplit.shift();
+  let os_version = osCapsSplit.join(' ');
+  caps.browser = browser ? browser : 'chrome';
+  caps.browser_version = browser_version ? browser_version : 'latest';
+  caps.os = os ? os : 'osx';
+  caps.os_version = os_version ? os_version : 'catalina';
+  caps.name = name;
+};
+
+exports.test = base.test.extend({
+  browser: async ({ playwright, browser }, use, workerInfo) => {
+    if (workerInfo.project.name.match(/browserstack/)) {
+      patchCaps(workerInfo.project.name);
+      const vBrowser = await playwright.chromium.connect({
+        wsEndpoint:
+          `wss://cdp.browserstack.com/playwright?caps=` +
+          `${encodeURIComponent(JSON.stringify(caps))}`,
+      });
+      await use(vBrowser);
+    } else {
+      await use(browser);
+    }
+  },
+  page: async ({ page, browser }, use, testInfo) => {
+    if (testInfo.project.name.match(/browserstack/)) {
+      const vPage = await browser.newPage();
+      await use(vPage);
+      const testResult = {
+        action: 'setSessionStatus',
+        arguments: {
+          status: testInfo.status,
+          reason: testInfo?.error?.message,
+        },
+      };
+      await vPage.evaluate(() => {},
+      `browserstack_executor: ${JSON.stringify(testResult)}`);
+    } else {
+      use(page);
+    }
+  },
+});

playwright-test/global-setup.js

@@ -0,0 +1,16 @@
+// global-setup.js
+const { bsLocal, BS_LOCAL_ARGS } = require('./fixtures');
+let localStarted = false;
+const { promisify } = require('util');
+const sleep = promisify(setTimeout);
+module.exports = async (config) => {
+  console.log('Starting BrowserStackLocal ...');
+  // Starts the Local instance with the required arguments
+  bsLocal.start(BS_LOCAL_ARGS, (callback) => {
+    console.log('BrowserStackLocal Started');
+    localStarted = true;
+  });
+  while (!localStarted) {
+    await sleep(1000);
+  }
+};

playwright-test/global-teardown.js

@@ -0,0 +1,15 @@
+// global-teardown.js
+const { bsLocal } = require('./fixtures');
+let localStopped = false;
+const {promisify} = require('util');
+const sleep = promisify(setTimeout);
+module.exports = async (config) => {
+  // Stop the Local instance after your test run is completed, i.e after driver.quit
+  bsLocal.stop(() => {
+    localStopped = true;
+    console.log('Stopped BrowserStackLocal')
+  });
+  while(!localStopped){
+    await sleep(1000);
+  }
+};