@actionlogementservices/wdio-test-context 1.0.0

package/src/test-context.js

@@ -0,0 +1,248 @@
+/**
+ * **Test Context** to be populated and passed to WDIO specs.
+ * @module
+ * @category public
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { faker } from '@faker-js/faker/locale/fr';
+import merge from 'lodash.merge';
+import { SevereServiceError } from 'webdriverio';
+
+import { MailService } from './mail-service.js';
+import { logger } from './logger.js';
+
+/** @typedef {import('./types.js').TestEnvironmentConfiguration} TestEnvironmentConfiguration */
+/** @typedef {import('./types.js').TestUser} TestUser */
+/** @typedef {import('./types.js').MailProviderName} MailProviderName */
+/** @typedef {import('./types.js').DataGenerator} DataGenerator */
+/** @typedef {import('./types.js').LogLevel} LogLevel */
+
+export const defaultDatasetName = 'default';
+const defaultRecordedUsersFilename = 'users.json';
+/** @type {MailProviderName} */ const defaultMailProviderName = 'maildrop';
+
+/**
+ * Implements **Test Context** with data to pass to WDIO specs.
+ */
+export class TestContext {
+  /** Test user @type {TestUser} */ user;
+  /** Mail service @type {MailService} */ mailService;
+
+  /** Test environments @private @type {Map<string, TestEnvironmentConfiguration>} */
+  _environments = new Map();
+  /** Mail provider name @private @type {MailProviderName} */ _mailProviderName;
+  /** data folder @private @type {string} */ _dataFolder;
+  /** log folder @private @type {string} */ _logFolder;
+  /** data folder @private @type {string} */ _recordedUsersFilepath;
+  /** custom data generator @private @type {DataGenerator} */ _dataGenerator;
+  /** default dataset name @private @type {string} */ _defaultDatasetName;
+
+  /**
+   * Implements a test context with environments and dataset in webdriverio.
+   * @param {string} name name of the environment (defined by TARGET_ENV environment variable)
+   * @param {Record<string, any>} parameters custom parameters (like 'url')
+   * @param {import('./types.js').EnvironmentOptions} [environmentOptions] custom options
+   * @returns {TestContext}
+   */
+  setEnvironment(name, parameters, environmentOptions) {
+    const options = environmentOptions ?? { perEnvironmentData: false };
+    this._environments.set(name, { parameters: new Map(Object.entries(parameters)), options });
+    return this;
+  }
+
+  /**
+   * Defines a custom function that adds data to the current dataset
+   * @param {DataGenerator} dataGenerator
+   * @returns {TestContext}
+   */
+  setDataGenerator(dataGenerator) {
+    this._dataGenerator = dataGenerator;
+    return this;
+  }
+
+  /**
+   * Defines the **default dataset** when no DATASET environment variable is specified.
+   * @param {string} name name ot the default dataset
+   * @returns {TestContext}
+   */
+  setDefaultDataset(name) {
+    this._defaultDatasetName = name ?? defaultDatasetName;
+    return this;
+  }
+
+  /**
+   * Defines the **disposable email provider**. Overriden by MAILPROVIDER environment variable. **maildrop** is default value.
+   * @param {MailProviderName} name name of the disposable mail service provider
+   * @returns {TestContext}
+   */
+  setMailProvider(name) {
+    this._mailProviderName = /** @type {import('./types.js').MailProviderName} */ (
+      process.env.MAILPROVIDER ?? name
+    );
+    return this;
+  }
+
+  /**
+   * Sets the logging level.
+   * @param {LogLevel} level logging level
+   */
+  setLogLevel(level) {
+    logger.setLogLevel(level);
+  }
+
+  /**
+   * Initializes the data of the test context.
+   * @returns {TestContext}
+   */
+  initialize() {
+    // email provider
+    this.mailService = new MailService(this._mailProviderName ?? defaultMailProviderName);
+    // data folder
+    this._dataFolder =
+      (this.environment.options.perEnvironmentData ?? false)
+        ? path.join(process.cwd(), 'data', this.environmentName)
+        : path.join(process.cwd(), 'data');
+    this._logFolder = path.join(process.cwd(), 'data', 'log');
+    this._recordedUsersFilepath = path.join(this._logFolder, defaultRecordedUsersFilename);
+    const datasetFilepath = path.join(this._dataFolder, `${this.dataset}.json`);
+    if (!fs.existsSync(datasetFilepath))
+      throw new SevereServiceError(`Unable to find dataset file '${datasetFilepath}'!`);
+    // generate random user
+    const user = this._generateRandomUser(this.mailService);
+    // generate custom data
+    const customData = this._dataGenerator(this);
+    // load dataset
+    const data = JSON.parse(fs.readFileSync(datasetFilepath, 'utf8'));
+    // add dataset to test context
+    merge(this, data);
+    // add generated user to test context
+    merge(this, { user });
+    // add custom data to test context
+    merge(this, customData);
+    // EMAIL environment variable to force a previous recorder user
+    const email = process.env.EMAIL;
+    if (email) {
+      merge(this, { user: this._getPreviouslyRecordedUser(email) });
+    }
+    return this;
+  }
+
+  /**
+   * Retrieves the specified parameter of the current environment.
+   * @param {string} name
+   * @param {boolean} [mandatory]
+   * @returns {any | undefined}
+   */
+  getParameter(name, mandatory) {
+    if (mandatory && !this.environment.parameters.has(name))
+      throw new Error(`Parameter '${name}' was not defined for '${this.environmentName}' environment!`);
+    return this.environment.parameters.get(name);
+  }
+
+  /**
+   * Retrieves the name of the current environment.
+   * @returns {string}
+   */
+  get environmentName() {
+    if (this._environments.size === 0)
+      throw new SevereServiceError('At least one environment must be set! Check your environment.js file.');
+    const firstEnvironmentName = this._environments.keys().next().value;
+    return (process.env.TARGET_ENV || firstEnvironmentName).toLowerCase();
+  }
+
+  /**
+   * Retrieves the configuration of the current environment.
+   * @returns {TestEnvironmentConfiguration}
+   */
+  get environment() {
+    return this._environments.get(this.environmentName);
+  }
+
+  /**
+   * The current dataset.
+   * @returns {string}
+   */
+  get dataset() {
+    return process.env.DATASET || this._defaultDatasetName;
+  }
+
+  /**
+   * Is the current dataset the default one.
+   * @returns {boolean}
+   */
+  get isDefaultDataset() {
+    return this._defaultDatasetName === this.dataset;
+  }
+
+  /**
+   * Generates a random user.
+   * @private
+   * @param {MailService} mailService
+   * @returns {TestUser}
+   */
+  _generateRandomUser(mailService) {
+    if (!process.env.USER_PASSWORD)
+      throw new SevereServiceError(
+        `The default password for generated user was not provided with the 'USER_PASSWORD' environment variable!`
+      );
+    // random user
+    const sex = /** @type {'male' | 'female'} */ (faker.person.sexType());
+    const gender = sex === 'female' ? 'Madame' : 'Monsieur';
+    const lastname = faker.person.lastName().toUpperCase();
+    const firstname = faker.person.firstName(sex);
+    // random email
+    const domain = faker.helpers.arrayElement(mailService.domains);
+    const suffix = new Date().getMilliseconds();
+    const email = `${firstname[0]}${lastname}-${suffix}@${domain}`
+      .normalize('NFD')
+      .replaceAll(/[\u0300-\u036F]/g, '')
+      .replaceAll(new RegExp(' ', 'g'), '')
+      .toLowerCase();
+    return { gender, lastname, firstname, email, password: process.env.USER_PASSWORD };
+  }
+
+  /**
+   * Retrieves the previously recorded user.
+   * @private
+   * @param {string} email
+   * @returns {TestUser}
+   */
+  _getPreviouslyRecordedUser(email) {
+    /** @type {import('./types.js').RecordedTestUser[]} */
+    const users = JSON.parse(fs.readFileSync(this._recordedUsersFilepath, 'utf8'));
+    const lastUser = email?.toLowerCase() === 'last';
+    const previouslyRecordedUser = lastUser
+      ? users.findLast(a => a.environment === this.environmentName)
+      : users.findLast(a => a.email === email && a.environment === this.environmentName);
+    if (!previouslyRecordedUser) {
+      const userInfo = lastUser ? 'last recorded user' : `previously recorded user with email '${email}'`;
+      throw new SevereServiceError(
+        `Unable to find ${userInfo} for '${this.environmentName}' in the ${defaultRecordedUsersFilename} file!`
+      );
+    }
+    delete previouslyRecordedUser.dataset;
+    delete previouslyRecordedUser.date;
+    delete previouslyRecordedUser.environment;
+    return previouslyRecordedUser;
+  }
+
+  /**
+   * Records the current created user.
+   */
+  recordTestUser() {
+    if (!fs.existsSync(this._recordedUsersFilepath)) {
+      fs.mkdirSync(this._logFolder, { recursive: true });
+      fs.writeFileSync(this._recordedUsersFilepath, JSON.stringify([]));
+    }
+    const { firstname, lastname, gender, email, password } = this.user;
+    const environment = this.environmentName;
+    const dataset = this.dataset;
+    const date = new Date().toLocaleString('fr-FR');
+    const users = JSON.parse(fs.readFileSync(this._recordedUsersFilepath, 'utf8'));
+    users.push({ environment, dataset, date, lastname, firstname, gender, email, password });
+    fs.writeFileSync(this._recordedUsersFilepath, JSON.stringify(users));
+  }
+}

package/src/types.d.ts

@@ -0,0 +1,60 @@
+import { TestContext } from './test-context';
+
+export { TestContext };
+
+/** TestContextWorkerService options */
+export type TestContextWorkerServiceOptions = {
+  testContext: TestContext;
+  logLevel?: LogLevel;
+};
+
+/** User gender. */
+export type Gender = 'Madame' | 'Monsieur';
+
+/** Implemented disposable email provider */
+export type MailProviderName = 'yopmail' | 'maildrop' | 'guerrillamail';
+
+/** Disposable email provider */
+export type MailProvider = {
+  /** name of the provider */ name: string;
+  /** domains exposed of the provider */ domains: string[];
+  /** wdio logic to open the inbox */ openInbox: (email?: string) => Promise<void>;
+  /** wdio logic to get emails */ getMessages: () => Promise<{ from: string; subject: string }[]>;
+  /** wdio logic to retieve email content */ getMessageContent: (index: number) => Promise<string>;
+};
+
+/** Randomly auto generated user */
+export type TestUser = {
+  /** last name */ lastname: string;
+  /** first name */ firstname: string;
+  /** gender */ gender: Gender;
+  /** e-mail */ email: string;
+  /** password */ password: string;
+};
+
+/** Recorded generated user */
+export type RecordedTestUser = TestUser & {
+  /** target environment used for recording */ environment: string;
+  /** dataset used for recording */ dataset: string;
+  /** recording date */ date: string;
+};
+
+/** Log level */
+export type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug';
+
+/** Test environment configuration*/
+export type TestEnvironmentConfiguration = {
+  /** parameters of the environment */ parameters: Map<string, any>;
+  /** options of the environment */ options: EnvironmentOptions;
+};
+
+/** Custom options for the environement */
+export type EnvironmentOptions = {
+  /** Retrieve dataset **per environment** rather than globally. Dataset are global if not specified. */
+  perEnvironmentData?: boolean;
+};
+
+/** Generate dynamic data to append to TestContext */
+export type DataGenerator = {
+  (context: TestContext): any;
+};

package/src/wdio/ado-reporter.js

@@ -0,0 +1,111 @@
+/**
+ * **WDIO Reporter** to handle Azure DevOps Test Run generation.
+ * @module
+ * @category public
+ * @public
+ */
+
+import { inspect } from 'node:util';
+
+import WDIOReporter from '@wdio/reporter';
+
+import { createAdoTestRun } from '../ado-client.js';
+import { logger } from '../logger.js';
+import { defaultDatasetName } from '../test-context.js';
+
+/** @typedef {  import('azure-devops-node-api/interfaces/TestInterfaces.d.ts').TestCaseResult} TestResult */
+
+/** Default Azure Devops Test Run model @type {import('../ado-client.js').RunModel} */
+const testRun = {
+  name: 'Tests e2e',
+  results: [],
+  state: 'Completed'
+};
+
+export class AdoReporter extends WDIOReporter {
+  /**
+   * Implements the **WDIO Reporter** that produces an Azure DevOps Test Run.
+   */
+  constructor(options) {
+    super(options);
+    this.isSynchronising = false;
+  }
+
+  get isSynchronised() {
+    return this.isSynchronising;
+  }
+
+  /**
+   * Gets executed when the runner starts.
+   * @param {import('@wdio/reporter').RunnerStats} run run information
+   */
+  onRunnerStart(run) {
+    const projet = process.env.SYSTEM_TEAMPROJECT;
+    const dataset = process.env.DATASET || defaultDatasetName;
+    const environnement = process.env.TARGET_ENV.toUpperCase();
+    const buildId = process.env.BUILD_BUILDID;
+    testRun.startDate = new Date().toISOString();
+    testRun.name = `Tests e2e ${projet} | Scénario '${dataset}' sur ${environnement}`;
+    testRun.comment = `Executé avec ${run.capabilities.browserName}(${run.capabilities.browserVersion}) | ${run.capabilities.platformName}`;
+    testRun.build = { id: buildId };
+  }
+
+  /**
+   * Gets executed when the test passes.
+   * @param {import('@wdio/reporter').TestStats} test test information
+   */
+  onTestPass(test) {
+    testRun.results.push({
+      automatedTestName: test.fullTitle,
+      testCaseTitle: test.fullTitle,
+      startedDate: test.start,
+      completedDate: test.end,
+      outcome: 'Passed',
+      state: 'Completed'
+    });
+  }
+
+  /**
+   * Gets executed when the test fails.
+   * @param {import('@wdio/reporter').TestStats} test test information
+   */
+  onTestFail(test) {
+    testRun.state = 'Aborted';
+    testRun.results.push({
+      automatedTestName: test.fullTitle,
+      testCaseTitle: test.fullTitle,
+      startedDate: test.start,
+      completedDate: test.end,
+      outcome: test.error.stack === undefined ? 'Failed' : 'Error',
+      errorMessage: test.error.message,
+      stackTrace: test.error.stack,
+      state: 'Completed'
+    });
+  }
+
+  /**
+   * Gets executed when the test is skipped.
+   * @param {import('@wdio/reporter').TestStats} test test information
+   */
+  onTestSkip(test) {
+    testRun.results.push({
+      automatedTestName: test.fullTitle,
+      testCaseTitle: test.fullTitle,
+      startedDate: test.start,
+      completedDate: test.end,
+      outcome: 'NotExecuted',
+      state: 'Completed'
+    });
+  }
+
+  /**
+   * Gets executed when the runner ends.
+   * @param {import('@wdio/reporter').RunnerStats} _run run information
+   */
+  async onRunnerEnd(_run) {
+    testRun.completedDate = new Date().toISOString();
+    logger.debug(inspect(testRun, { colors: true, depth: 5 }));
+    await createAdoTestRun(testRun);
+    this.isSynchronising = true;
+  }
+}

package/src/wdio/test-context-worker-service.js

@@ -0,0 +1,88 @@
+/* global browser */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { inspect } from 'node:util';
+
+import moment from 'moment';
+import { SevereServiceError } from 'webdriverio';
+
+import { logger } from '../logger.js';
+
+/** @typedef {import('@wdio/types/build/Options.d.ts').Testrunner } TestrunnerOptions */
+/** @typedef {import('@wdio/types/build/Capabilities.d.ts').TestrunnerCapabilities} TestrunnerCapabilities */
+/** @typedef {import('@wdio/types/build/Frameworks.d.ts').Test} Test */
+/** @typedef {import('@wdio/types/build/Frameworks.d.ts').TestResult} TestResult */
+/** @typedef {import('../types.js').TestContextWorkerServiceOptions} TestContextWorkerServiceOptions */
+/** @typedef {import('../types.js').LogLevel} LogLevel */
+
+/** @type {(object: any) => any } */ const filterPrivateProperty = object =>
+  Object.fromEntries(Object.entries(object).filter(([key]) => !key.startsWith('_') && key !== 'mailService'));
+
+export default class TestContextWorkerService {
+  /**
+   * Imlements the **WDIO Worker Service** that handles the Test Context life cycle.
+   * @param {TestContextWorkerServiceOptions} serviceOptions
+   * @param {TestrunnerCapabilities} _capabilities
+   * @param {TestrunnerOptions} _config
+   */
+  constructor(serviceOptions, _capabilities, _config) {
+    const { testContext, logLevel } = serviceOptions;
+    if (!testContext)
+      throw new SevereServiceError(
+        'No context specified in TestContextWorkerService options! This is a required parameter.'
+      );
+    this._logLevel = logLevel ?? 'error';
+    logger.setLogLevel(this._logLevel);
+    this._context = testContext;
+    this._context.setLogLevel(this._logLevel);
+  }
+
+  /**
+   * Gets executed just before initialising the webdriver session and test framework.
+   * **Displays** the Test Context.
+   * @param {TestrunnerOptions} _config
+   * @param {TestrunnerCapabilities} _capabilities
+   * @param {string[]} _specs
+   * @param {string} _cid
+   */
+  beforeSession(_config, _capabilities, _specs, _cid) {
+    logger.debug(
+      inspect(filterPrivateProperty(this._context), {
+        colors: true,
+        depth: 5
+      })
+    );
+  }
+
+  /**
+   * Gets executed after a test.
+   * Generates **error screenshot** if applicable.
+   * @param {Test} test
+   * @param {*} _context
+   * @param {TestResult} result
+   */
+  async afterTest(test, _context, result) {
+    const { passed, error: testError } = result;
+    if (passed || !testError || !this._context) return;
+    const { dataset, environmentName } = this._context;
+    try {
+      const folder = path.join(process.cwd(), 'screenshot', environmentName, dataset);
+      await fs.mkdir(folder, { recursive: true });
+      const timestamp = moment().format('YYYY-MM-DD_HH-mm-ss');
+      const filename = path.join(folder, `error-${timestamp}`);
+      const { message, stack } = testError;
+      const errorLines = stack?.split('at ') ?? [];
+      const errorFile = errorLines
+        .find((/** @type {string} */ l) => l.toLowerCase().includes('e2e.js'))
+        .trim();
+      const fileContent = `Test : ${test.fullName}\nErreur : ${message}${
+        errorFile ? '\nEmplacement : ' + errorFile : ''
+      }`;
+      await fs.writeFile(`${filename}.txt`, fileContent, { encoding: 'utf8', flag: 'w', flush: true });
+      await browser.saveScreenshot(`${filename}.png`);
+    } catch (error) {
+      logger.detailError(error);
+    }
+  }
+}