@actionlogementservices/wdio-test-context 2.0.0 → 2.1.0

package/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Every change requires approval from the PR reviewers team
+* @actionlogementservices/pr-reviewers

package/.github/workflows/release.yml

@@ -0,0 +1,92 @@
+# Stages the package on npm when a merged PR brings a new version in package.json.
+# npm authentication relies on npm trusted publishing (OIDC): no npm token is stored in GitHub.
+# The staged version goes public only once a maintainer approves it on npmjs.com with 2FA,
+# then the draft GitHub release has to be published to create the git tag.
+name: Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# never run two releases at the same time
+concurrency: release
+
+permissions:
+  contents: write # creates the draft GitHub release
+  issues: write # creates the approval reminder issue
+  id-token: write # npm trusted publishing
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+          cache: npm
+
+      # staged publishing requires npm >= 11.15.0
+      - run: npm install --global npm@^11.15.0
+
+      - name: Check whether the version is already published or staged
+        id: version
+        run: |
+          NAME=$(node -p "require('./package.json').name")
+          VERSION=$(node -p "require('./package.json').version")
+          PUBLISHED=$(npm view "$NAME@$VERSION" version 2>/dev/null || true)
+          echo "name=$NAME" >> "$GITHUB_OUTPUT"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          if [ "$PUBLISHED" = "$VERSION" ]; then
+            echo "publish=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::$NAME@$VERSION is already published, nothing to release."
+          # a (draft) GitHub release means the version has already been staged and awaits approval
+          elif gh release list --limit 100 --json tagName --jq '.[].tagName' | grep -Fxq "$VERSION"; then
+            echo "publish=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::$NAME@$VERSION is already staged, approve it on npmjs.com."
+          else
+            echo "publish=true" >> "$GITHUB_OUTPUT"
+          fi
+          # prereleases (e.g. 5.1.0-0) go to the 'next' dist-tag, like release-it does
+          if [[ "$VERSION" == *-* ]]; then
+            echo "dist-tag=next" >> "$GITHUB_OUTPUT"
+            echo "prerelease=--prerelease" >> "$GITHUB_OUTPUT"
+          else
+            echo "dist-tag=latest" >> "$GITHUB_OUTPUT"
+            echo "prerelease=" >> "$GITHUB_OUTPUT"
+          fi
+
+      # no build step: install scripts are skipped (msnodesqlv8 native addon is not needed to lint)
+      - if: steps.version.outputs.publish == 'true'
+        run: npm ci --ignore-scripts
+
+      - if: steps.version.outputs.publish == 'true'
+        run: npm test
+
+      - if: steps.version.outputs.publish == 'true'
+        run: npm stage publish --tag ${{ steps.version.outputs.dist-tag }}
+
+      # a draft release creates no git tag: the tag is created when the draft is published
+      - name: Create the draft GitHub release and the approval reminder
+        if: steps.version.outputs.publish == 'true'
+        env:
+          NAME: ${{ steps.version.outputs.name }}
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          RELEASE_URL=$(gh release create "$VERSION" --draft --target "$GITHUB_SHA" --title "$VERSION" --generate-notes ${{ steps.version.outputs.prerelease }})
+          BODY="$NAME@$VERSION has been staged on npm and awaits your approval.
+
+          - [ ] Approve it in the **Staged Packages** tab of https://www.npmjs.com/package/$NAME (or \`npm stage list\` / \`npm stage approve <stage-id>\`)
+          - [ ] Publish the draft GitHub release, which creates the \`$VERSION\` git tag: $RELEASE_URL
+          - [ ] Close this issue
+
+          If you reject the staged version, delete the draft release and close this issue."
+          echo "$BODY" >> "$GITHUB_STEP_SUMMARY"
+          # the reminder issue notifies the person who merged (requires issues to be enabled on the repository)
+          gh issue create --assignee "$GITHUB_ACTOR" --title "Approve the npm release $VERSION" --body "$BODY" \
+            || echo "::warning::Could not create the reminder issue (are issues enabled on the repository?)"

package/README.md

@@ -1,12 +1,21 @@
 # wdio-test-context
 
+[![npm package](https://img.shields.io/npm/v/%40actionlogementservices%2Fwdio-test-context)](https://www.npmjs.com/package/@actionlogementservices/wdio-test-context)
+
 A framework to add test context to webdriverio end to end tests.
 
-- It uses JSON files (named dataset) and optional javascript function to add dynamic content to your dataset.
-- It consumes a disposable mail service (YOPmail, maildrop or Guerilla Mail) in order to check for new message.
+- It uses JSON files (named datasets) and an optional javascript function to add dynamic content to your dataset.
+- It generates a random test user (name, gender, disposable email address) for each run.
+- It consumes a disposable mail service (maildrop, YOPmail or Guerrilla Mail) in order to check for new messages.
+- It executes SQL queries on Microsoft SQL Server, publishes AMQP (RabbitMQ) messages and runs VTOM jobs.
 - It provides pdf generation to enable document uploads.
 - It provides an Azure DevOps webdriverio reporter.
-- It generates a screenshot when the test fails.
+- It generates a screenshot when a test fails.
+
+## Prerequisites
+
+- Node.js 22 or later.
+- webdriverio 9 (`@wdio/globals` is a peer dependency).
 
 ## Installation
 
@@ -16,11 +25,24 @@ A framework to add test context to webdriverio end to end tests.
   npm install @actionlogementservices/wdio-test-context
   ```
 
-- Create a `data` folder
+- Create a `data` folder.
+
+- Create JSON files in the `data` folder: these are your datasets. The content of the selected dataset is merged into the test context. For instance `data/test.json`:
 
-- Create JSON files in the `data` folder: this will be your datasets.
+  ```json
+  {
+    "company": { "name": "ACME" }
+  }
+  ```
 
-- Create a `data/test-context.d.ts`: this will add intellisense when you use your test context data within the spec files.
+- Create a `data/test-context.d.ts` file: it adds intellisense when you use your test context data within the spec files.
+
+  ```ts
+  export type TestContextModel = {
+    company: { name: string };
+    customDate: Date;
+  };
+  ```
 
 - Create a `data/test-context.js` file with the following code:
 
@@ -35,10 +57,12 @@ A framework to add test context to webdriverio end to end tests.
   /** @type {TestContextModel & TestContext} */
   export const testContext = /** @type {TestContextModel & TestContext} */ (
     new TestContext()
-      .setDataGenerator(generateRandomData) // optional : add your own dynamic data
-      .setDefaultDataset('test') // default dataset name when DATASET env var is not specified
+      .setDataGenerator(generateRandomData) // add your own dynamic data
+      .setDefaultDataset('test') // default dataset name when the DATASET env var is not specified
+      .setMailProvider('maildrop') // optional: 'maildrop' (default), 'yopmail' or 'guerrillamail'
+      .setSmtpServer({ host: 'smtp.domain.com', port: 25 }) // optional: only to send emails with mailService.sendMessage
       .setEnvironment('local', {
-        //define parameters for your environment
+        // define the parameters of your environment
         frontUrl: 'https://test.lvh.me',
         backOfficeUrl: 'https://test-backoffice.lvh.me:4432',
         sso: true
@@ -51,17 +75,22 @@ A framework to add test context to webdriverio end to end tests.
   );
   ```
 
-- Create optionnally `data/generate-random-data.js` to add dynamic data, file with the following code:
+  > **NOTES**
+  >
+  > - The first environment is the default one when the `TARGET_ENV` env var is not specified.
+  > - `setEnvironment` accepts a third `options` argument. With `{ perEnvironmentData: true }`, the datasets of this environment are read from `data/{environment_name}/` instead of `data/`.
+  > - The mail provider can be overridden with the `MAILPROVIDER` env var.
+
+- Create `data/generate-random-data.js` to add dynamic data, with the following code:
 
   ```js
   import { faker } from '@faker-js/faker/locale/fr';
-  import moment from 'moment';
 
   /** @typedef {import('@actionlogementservices/wdio-test-context/types').DataGenerator} DataGenerator */
 
   /** @type {DataGenerator} */
   function generateRandomData(_context) {
-    // dates random
+    // random date
     const customDate = faker.date.between({ from: '1995-01-01', to: '2001-01-01' });
     return {
       customDate
@@ -71,32 +100,7 @@ A framework to add test context to webdriverio end to end tests.
   export { generateRandomData };
   ```
 
-- Configure optionnaly a **RabbitMQ client** if you plan to send some RabbitMQ message within your tests:
-
-  > **NOTE**
-  >
-  > - If you have secrets in your connection string, you need to
-  >
-  >   - create a `.env.{your_environment_name}.local` file (for instance `.env.staging.local`) with your secret configuration parameters.
-  >   - add the following entries to your `.gitignore`:
-  >
-  >     `.env.local`<br>`.env.*.local`
-
-  ```js
-  export const testContext = /** @type {TestContextModel & TestContext} */ (
-    new TestContext()
-      .setEnvironment(
-        'local',
-        {
-          frontUrl: 'https://test.lvh.me',
-        },
-        {
-          amqp: String.raw`amqps://${process.env.RMQ_USER}:${process.env.RMQ_PWD}@your-host:5671/your-vhost`,
-        }
-      )
-  ```
-
-- Configure webdriverio: in your wdio.conf.js:
+- Configure webdriverio in your `wdio.conf.js`:
 
   ```js
   import { AdoReporter, TestContextWorkerService } from '@actionlogementservices/wdio-test-context';
@@ -110,168 +114,225 @@ A framework to add test context to webdriverio end to end tests.
   }
   ```
 
+  The `logLevel` option accepts `none`, `error` (default), `warn`, `info` or `debug`.
+
+## Environment variables
+
+| Name                                                                        | Description                                                                                           |
+| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `USER_PASSWORD`                                                             | **Required.** Password given to the generated test user (`testContext.user.password`).                |
+| `TARGET_ENV`                                                                | Name of the environment to use. Defaults to the first environment set.                                |
+| `DATASET`                                                                   | Name of the dataset (JSON file name without extension). Defaults to `setDefaultDataset` value.        |
+| `MAILPROVIDER`                                                              | Overrides the disposable mail provider (`maildrop`, `yopmail` or `guerrillamail`).                    |
+| `EMAIL`                                                                     | Reuses a previously recorded user (see [Test user](#test-user)) instead of generating a new one.      |
+| `DEBUG`                                                                     | When set, raises the `BasePage` default wait timeout from 20 s to 1 hour, for step by step debugging. |
+| `SYSTEM_ACCESSTOKEN` or `TOKEN`                                             | Azure DevOps reporter: pipeline access token, or personal access token when `TOKEN` is used.          |
+| `SYSTEM_TEAMFOUNDATIONCOLLECTIONURI`, `SYSTEM_TEAMPROJECT`, `BUILD_BUILDID` | Azure DevOps reporter: set automatically by Azure Pipelines.                                          |
+
 ## Notes on secrets
 
-If you have **secrets** in your parameter values, you need to
+Environment variables are loaded with [dotenv-flow](https://www.npmjs.com/package/dotenv-flow), the environment name (`TARGET_ENV`) being the dotenv-flow `node_env`: `.env`, `.env.local`, `.env.{environment_name}` and `.env.{environment_name}.local` files are read.
 
-- create a `.env.{your_environment_name}.local` file (for instance `.env.staging.local`) with your secret configuration parameters:
+If you have **secrets** in your parameter values, you need to:
+
+- create a `.env.{environment_name}.local` file (for instance `.env.staging.local`) with your secret configuration parameters:
 
   ```sh
-  DB_PWD="MySyperStrongPassword"
-  CLIENT_SECRET="MySuperSafeSecret"
+  USER_PASSWORD="MySuperStrongPassword"
+  DB_PWD="MySuperStrongPassword"
+  RMQ_USER="MyUser"
+  RMQ_PWD="MySuperSafeSecret"
   ```
 
-- references the secret in the environment.js like this:
+- reference the secret in `data/test-context.js` with a **template literal** (backticks, not quotes):
 
   ```js
   .setEnvironment('staging', {
-    sql: 'Server=YourServer;Password=${process.env.DB_PWD};...'
+    sqlBO: `Server=YourServer;Database=YourDatabase;User Id=YourUser;Password=${process.env.DB_PWD};`
+  })
   ```
 
-- to add the following entries to your `.gitignore` to prevent storing secret values in your repository:
+- add the following entries to your `.gitignore` to prevent storing secret values in your repository:
 
   ```sh
   .env.local
   .env.*.local
+  # recorded test users, including their password
+  data/log/
+  # error screenshots
+  screenshot/
   ```
 
 ## Use the test context in the spec file
 
+### Test user
+
+- A random user is generated at each run and is available in `testContext.user` (`gender`, `firstname`, `lastname`, `email` on a domain of the mail provider, `password` from the `USER_PASSWORD` env var).
+- Call `testContext.recordTestUser()` (for instance once the user account is created) to append the user to `data/log/users.json`. As it contains the passwords, a `.gitignore` is created in `data/log/` so that the folder is never committed.
+- Run the tests with `EMAIL=<recorded email>` to reuse a recorded user of the current environment, or `EMAIL=last` to reuse the last recorded one.
+
 ### To access the mail service
 
-- Access the `mailService` property:
+- Use the `mailService` property:
 
   ```js
-  import { testContext } from '../../environments.js';
+  import { testContext } from '../data/test-context.js';
 
-  describe(`[Inbox] - ${testContext.user.email} - I`, () => {
-  let confirmationLink;
-    it('receive a mail with confirmation code within 10s', async () => {
-      await browser.open(testContext.getParameter('frontUrl')); // to retrieve parameters
+  describe(`[Inbox] - ${testContext.user.email}`, () => {
+    it('receives a mail with a confirmation code', async () => {
+      await browser.url(testContext.getParameter('frontUrl')); // to retrieve parameters
+      ...
       const from = 'no-reply@domain.com';
-      const subject = `Confirmation code`;
-      // to wait for email and to access test context data
+      const subject = 'Confirmation code';
+      // to wait for the email and to access the test context data
       const content = await testContext.mailService.waitForMessage(testContext.user.email, from, subject);
-      confirmationCode = getConfirmationCode(content);
+      const confirmationCode = getConfirmationCode(content); // your own function
       expect(confirmationCode).toContain('123456');
     });
-  }
+  });
   ```
 
+- To send an email, define the smtp server with `setSmtpServer({ host, port, secure })` in `data/test-context.js`, then call `await testContext.mailService.sendMessage(from, to, subject, html)`.
+
 ### To execute SQL queries
 
-- You need to define a **parameter** in `your environment.js` that contains the **sql connection string**. In the following exemple it is named `sqlBO`.
+- You need to define a **parameter** in `data/test-context.js` that contains the **sql connection string**. In the following example it is named `sqlBO`.
 
   ```js
   export const testContext = /** @type {TestContextModel & TestContext} */ (
     new TestContext()
-      .setEnvironment(
-        'local',
-        {
-          frontUrl: 'https://test.lvh.me',
-          sqlBO: String.raw`Driver={ODBC Driver 17 for SQL Server};Server=(localdb)\MSSQLLocalDB;Database=YourDatabase;Trusted_Connection=yes;`,
-        }
-      )
+      .setEnvironment('local', {
+        frontUrl: 'https://test.lvh.me',
+        sqlBO: String.raw`Driver={ODBC Driver 17 for SQL Server};Server=(localdb)\MSSQLLocalDB;Database=YourDatabase;Trusted_Connection=yes;`
+      })
+      .initialize()
+  );
   ```
 
   > **NOTES on SQL connection string**
   >
-  > - If you plan to use `(localdb)` or **Windows authentication** this requires an **ODBC driver** with a specific connection string syntax : `Driver={...}`. You also need to check which Microsoft SQL Server **ODBC driver** is installed on your system with the `ODBC Data Sources` control panel.
-  > - For Microsoft Sql Server instance without Windows Authentication, there is no need to use an ODBC driver. In such case remove the `Driver={...}` portion of the connection string.
-  > - You **can not** mix both syntax in the same environment.
-  > - In the previous example, `(localdb)` is used with the `ODBC Driver 17 for SQL Server` which is installed.
+  > - If you plan to use `(localdb)` or **Windows authentication**, this requires an **ODBC driver** with a specific connection string syntax: `Driver={...}`. You also need to check which Microsoft SQL Server **ODBC driver** is installed on your system with the `ODBC Data Sources` control panel.
+  > - For a Microsoft SQL Server instance without Windows authentication, there is no need to use an ODBC driver. In such case remove the `Driver={...}` portion of the connection string.
+  > - You **cannot** mix both syntaxes in the same environment.
+  > - In the previous example, `(localdb)` is used with the `ODBC Driver 17 for SQL Server`, which is installed.
 
-- Somewhere in you spec files
+- Somewhere in your spec files:
 
   ```js
-  import { testContext } from '../../environments.js';
+  import { testContext } from '../data/test-context.js';
 
-  describe(`Before starting the test, we`, () => {
-
-  it('check the sql version', async () => {
-    const result = await testContext.executeSql('sqlBO', (sql) => sql.query('SELECT @@Version'));
-    ...
+  describe('Before starting the test, we', () => {
+    it('check the sql version', async () => {
+      const result = await testContext.executeSql('sqlBO', sql => sql.query('SELECT @@Version'));
+      ...
+    });
   });
   ```
 
-### To publish AMQP message
+### To publish AMQP messages
 
-- You need to define a **parameter** in `your environment.js` that contains the **amqp connection string**. In the following exemple it is named `amqpBO`.
+- You need to define a **parameter** in `data/test-context.js` that contains the **amqp connection string**. In the following example it is named `amqpBO`.
 
   ```js
   export const testContext = /** @type {TestContextModel & TestContext} */ (
     new TestContext()
-      .setEnvironment(
-        'local',
-        {
-          frontUrl: 'https://test.lvh.me',
-          amqpBO: String.raw`Driver={ODBC Driver 17 for SQL Server};Server=(localdb)\MSSQLLocalDB;Database=YourDatabase;Trusted_Connection=yes;`,
-        }
-      )
+      .setEnvironment('local', {
+        frontUrl: 'https://test.lvh.me',
+        amqpBO: `amqps://${process.env.RMQ_USER}:${process.env.RMQ_PWD}@your-host:5671/your-vhost`
+      })
+      .initialize()
+  );
   ```
 
-- Somewhere in you spec files
+- Somewhere in your spec files:
 
   ```js
-  import { testContext } from '../../environments.js';
-
-  describe(`Before starting the test, we`, () => {
-
-  it('send an amqp message', async () => {
-    const result = await testContext.publishMessage('amqpBO',
-      'exchange',             // your exchange name
-      'routingKey',           // your routing key
-      'type',                 // your message type
-      { test: true },         // your message payload
-      testContext.user.email  // something to correlate/track you message
-    );
-    expect(result).toBe(true);
+  import { testContext } from '../data/test-context.js';
+
+  describe('Before starting the test, we', () => {
+    it('send an amqp message', async () => {
+      const result = await testContext.publishMessage(
+        'amqpBO',
+        'exchange', // your exchange name
+        'routingKey', // your routing key
+        'type', // your message type
+        { test: true }, // your message payload
+        testContext.user.email // correlation id to track your message
+      );
+      expect(result).toBe(true);
+    });
   });
   ```
 
 ### To run a VTOM job
 
-- You need to define a **parameter** in `your environment.js` that contains the **VTOM configuration**. In the following exemple it is named `vtomBO`.
+- You need to define a **parameter** in `data/test-context.js` that contains the **VTOM configuration**. In the following example it is named `vtomBO`.
 
   ```js
   export const testContext = /** @type {TestContextModel & TestContext} */ (
     new TestContext()
-      .setEnvironment(
-        'local',
-        {
-          frontUrl: 'https://test.lvh.me',
-          vtomBO: {
-            url: 'https://...',
-            apiKey: 'abcdef',
-            environement: 'DEV'
-          },
+      .setEnvironment('local', {
+        frontUrl: 'https://test.lvh.me',
+        vtomBO: {
+          url: 'https://...',
+          apiKey: process.env.VTOM_API_KEY,
+          environment: 'DEV'
         }
-      )
+      })
+      .initialize()
+  );
   ```
 
-- Somewhere in you spec files
+- Somewhere in your spec files (the job is stopped, started, then its status is checked every 5 s for 100 s at most):
 
   ```js
-  import { testContext } from '../../environments.js';
-
-  describe(`Before starting the test, we`, () => {
+  import { testContext } from '../data/test-context.js';
 
-  it('run a vtom job', async () => {
-    const result = await testContext.runVtomJob('vtomBO', 'app', 'job');
-    expect(result).toBe(true);
+  describe('Before starting the test, we', () => {
+    it('run a vtom job', async () => {
+      const result = await testContext.runVtomJob('vtomBO', 'app', 'job');
+      expect(result).toBe(true);
+    });
   });
   ```
 
-## Run your test
+### Other helpers
+
+- `BasePage`: base class for your page objects (tab management, wait helpers…).
+- `pdfGenerator`: `generatePdf(filename, testContext)` creates a pdf file to upload and returns its path, `deletePdf(filepath)` deletes it.
+
+## Corporate CA certificates
+
+If your environments use certificates issued by a private certificate authority, put the CA certificates (`*.crt` files) in a `ca` folder at the root of your test project: they are trusted when the test context is initialized.
 
-- Specify the dataset with the `DATASET` env var and the environment with the `TARGET_ENV` env var
+## Run your tests
+
+- Specify the dataset with the `DATASET` env var and the environment with the `TARGET_ENV` env var:
 
   ```sh
   TARGET_ENV=staging DATASET=full-scenario npx wdio
-  or
+  # or
   TARGET_ENV=staging DATASET=full-scenario npm test
   ```
 
+- When a test fails, a screenshot and a text file with the error are saved in `screenshot/{environment_name}/{dataset}/`.
+
+- With the `AdoReporter`, the results are published as an Azure DevOps test run at the end of the run. In an Azure Pipelines job, map the access token to the script: `env: { SYSTEM_ACCESSTOKEN: $(System.AccessToken) }`.
+
 ## Code documentation
 
-- Code is [documented here](./doc/toc.md).
+- Code is [documented here](./doc/toc.md) (generated with `npm run doc`).
+
+## Release
+
+The package is published on npm by the `Release` GitHub workflow, with npm trusted publishing (no npm token is stored in GitHub):
+
+1. In your pull request, bump the version with `npm run bump -- <major|minor|patch|prerelease>` (updates `package.json` and `package-lock.json` only).
+1. When the pull request is merged on `main`, the workflow runs the linter and **stages** the new version on npm.
+   Prerelease versions (e.g. `2.1.0-0`) are staged with the `next` dist-tag.
+1. The workflow creates a draft GitHub release and an issue assigned to the person who merged, as a reminder to:
+   - approve the staged version in the **Staged Packages** tab of the [npm package](https://www.npmjs.com/package/@actionlogementservices/wdio-test-context) (2FA required),
+   - publish the draft GitHub release, which creates the git tag,
+   - close the issue.
+
+If the staged version is rejected, delete the draft release and close the issue.

package/doc/src_test-context.md

@@ -82,6 +82,19 @@ __*return*__ | [TestContext](src_test-context.md) | **
 
 ---
 
+### `setSmtpServer(smtpServer) ► TestContext`
+
+![modifier: public](images/badges/modifier-public.png)
+
+Defines the **smtp server** used by the mail service to send emails.
+
+Parameters | Type | Description
+--- | --- | ---
+__smtpServer__ | `SmtpServer` | *smtp server*
+__*return*__ | [TestContext](src_test-context.md) | **
+
+---
+
 ### `setLogLevel(level)`
 
 ![modifier: public](images/badges/modifier-public.png)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actionlogementservices/wdio-test-context",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "A framework to add test context to webdriverio end to end tests.",
   "main": "src/index.js",
   "type": "module",
@@ -12,7 +12,9 @@
   "scripts": {
     "prettier": "prettier \"./src/**/*.js\" --write",
     "eslint": "eslint \"./src/**/*.js\"",
-    "doc": "jsdoc -c ./.jsdoc.json"
+    "doc": "jsdoc -c ./.jsdoc.json",
+    "test": "npm run eslint",
+    "bump": "npm version --no-git-tag-version"
   },
   "repository": {
     "type": "git",
@@ -44,6 +46,7 @@
   },
   "dependencies": {
     "@faker-js/faker": "^10.4.0",
+    "@wdio/reporter": "^9.27.1",
     "amqplib": "^2.0.1",
     "axios": "^1.16.1",
     "azure-devops-node-api": "^15.1.2",
@@ -59,7 +62,8 @@
     "syswide-cas": "^5.3.0"
   },
   "peerDependencies": {
-    "@wdio/globals": "^9.27.1"
+    "@wdio/globals": "^9.27.1",
+    "webdriverio": "^9.27.1"
   },
   "engines": {
     "node": ">=22"

package/src/mail-service.js

@@ -11,16 +11,20 @@ import * as provider from './page-objects/index.js';
 import { logger } from './logger.js';
 
 /** @typedef {import('./types.js').MailProvider} MailProvider */
+/** @typedef {import('./types.js').SmtpServer} SmtpServer */
 
 export class MailService {
   /** disposable email provider @type {MailProvider} */ provider;
+  /** smtp server used to send emails @type {SmtpServer | undefined} */ smtpServer;
 
   /**
    * Implements a service that sends and retrieves emails with a given provider.
    * @param {import('./types.js').MailProviderName} providerName disposable email provider name
+   * @param {SmtpServer} [smtpServer] smtp server used to send emails
    */
-  constructor(providerName) {
+  constructor(providerName, smtpServer) {
     this.provider = provider[providerName].default;
+    this.smtpServer = smtpServer;
   }
 
   /**
@@ -48,7 +52,10 @@ export class MailService {
    * @returns {Promise<void>}
    */
   async sendMessage(from, to, subject, html) {
-    const transporter = nodemailer.createTransport({ host: 'smtp.als.lan', secure: false, port: 25 });
+    if (!this.smtpServer?.host)
+      throw new Error('No smtp server defined! Call setSmtpServer on the test context to send emails.');
+    const { host, port, secure } = this.smtpServer;
+    const transporter = nodemailer.createTransport({ host, port: port ?? 25, secure: secure ?? false });
     await transporter.sendMail({ from, to, subject, html });
   }
 

package/src/test-context.js

@@ -24,6 +24,7 @@ import { runVtomJob } from './vtom-client.js';
 /** @typedef {import('./types.d.ts').MailProviderName} MailProviderName */
 /** @typedef {import('./types.d.ts').DataGenerator} DataGenerator */
 /** @typedef {import('./types.d.ts').LogLevel} LogLevel */
+/** @typedef {import('./types.d.ts').SmtpServer} SmtpServer */
 
 export const defaultDatasetName = 'default';
 const defaultRecordedUsersFilename = 'users.json';
@@ -39,6 +40,7 @@ export class TestContext {
   /** Test environments @private @type {Map<string, TestEnvironmentConfiguration>} */
   _environments = new Map();
   /** Mail provider name @private @type {MailProviderName} */ _mailProviderName;
+  /** Smtp server @private @type {SmtpServer} */ _smtpServer;
   /** data folder @private @type {string} */ _dataFolder;
   /** log folder @private @type {string} */ _logFolder;
   /** data folder @private @type {string} */ _recordedUsersFilepath;
@@ -90,6 +92,16 @@ export class TestContext {
     return this;
   }
 
+  /**
+   * Defines the **smtp server** used by the mail service to send emails.
+   * @param {SmtpServer} smtpServer smtp server
+   * @returns {TestContext}
+   */
+  setSmtpServer(smtpServer) {
+    this._smtpServer = smtpServer;
+    return this;
+  }
+
   /**
    * Sets the logging level.
    * @param {LogLevel} level logging level
@@ -109,7 +121,7 @@ export class TestContext {
       node_env: process.env.TARGET_ENV || this.defaultEnvironmentName
     });
     // email provider
-    this.mailService = new MailService(this._mailProviderName ?? defaultMailProviderName);
+    this.mailService = new MailService(this._mailProviderName ?? defaultMailProviderName, this._smtpServer);
     // data folder
     this._dataFolder =
       (this.environment.options.perEnvironmentData ?? false)
@@ -123,7 +135,7 @@ export class TestContext {
     // generate random user
     const user = this._generateRandomUser(this.mailService);
     // generate custom data
-    const customData = this._dataGenerator(this);
+    const customData = this._dataGenerator?.(this) ?? {};
     // load dataset
     const data = JSON.parse(fs.readFileSync(datasetFilepath, 'utf8'));
     // add dataset to test context
@@ -255,6 +267,9 @@ export class TestContext {
       fs.mkdirSync(this._logFolder, { recursive: true });
       fs.writeFileSync(this._recordedUsersFilepath, JSON.stringify([]));
     }
+    // recorded users contain passwords: never commit the log folder
+    const gitignoreFilepath = path.join(this._logFolder, '.gitignore');
+    if (!fs.existsSync(gitignoreFilepath)) fs.writeFileSync(gitignoreFilepath, '*\n');
     const { firstname, lastname, gender, email, password } = this.user;
     const environment = this.environmentName;
     const dataset = this.dataset;

package/src/types.d.ts

@@ -23,6 +23,13 @@ export type MailProvider = {
   /** wdio logic to retieve email content */ getMessageContent: (index: number) => Promise<string>;
 };
 
+/** Smtp server used to send emails */
+export type SmtpServer = {
+  /** host name */ host: string;
+  /** port (25 by default) */ port?: number;
+  /** use TLS from the start of the connection (false by default) */ secure?: boolean;
+};
+
 /** Randomly auto generated user */
 export type TestUser = {
   /** last name */ lastname: string;

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

@@ -76,7 +76,7 @@ export default class TestContextWorkerService {
       const errorLines = stack?.split('at ') ?? [];
       const errorFile = errorLines
         .find((/** @type {string} */ l) => l.toLowerCase().includes('e2e.js'))
-        .trim();
+        ?.trim();
       const fileContent = `Test : ${test.fullName}\nErreur : ${message}${
         errorFile ? '\nEmplacement : ' + errorFile : ''
       }`;