Skip to main content

Updating Serenity/JS

Staying up-to-date with the latest version of Serenity/JS is essential to ensure your test automation framework is equipped with the latest features, performance improvements, and critical security patches. Regular updates help avoid technical debt, reduce the risk of using deprecated features, and ensure compatibility with the latest tools and platforms.

In this guide, we’ll explore the best approaches for staying up-to-date with Serenity/JS.

Using flexible version ranges​

Configuring your package.json to use the 3.x version range for Serenity/JS modules allows your Node package manager, like NPM, Yarn, or PNPM, to install the latest compatible versions automatically.

Example configuration​

package.json
{
  "devDependencies": {
    "@serenity-js/core": "3.x",
    "@serenity-js/assertions": "3.x",
    "@serenity-js/rest": "3.x",
    "@serenity-js/playwright": "3.x",
    "@serenity-js/playwright-test": "3.x",
    "@serenity-js/serenity-bdd": "3.x",
    "@serenity-js/web": "3.x"
  }
}

Benefits​

  • Automation: Your package manager will automatically install the latest compatible versions of your dependencies during a fresh npm install, it will also update its lock file to reflect the exact versions installed.
  • Ease of use: No manual intervention is required to update dependencies within the specified range.
  • Predictability: Your package manager will ensure compatibility since the version constraint (3.x) avoids breaking changes introduced by major version updates.

Disadvantages​

  • No explicit control: Updates occur implicitly when installing dependencies, which may not align with your preferred schedule.
  • Possible discrepancies: If team members or CI pipelines use different node_modules states, discrepancies may arise.

Recommendation​

This approach is recommended for simple project or those without strict update policies. To mitigate the disadvantages, make sure to keep the lock file generated by your package manager under version control.

Updating Serenity/JS modules manually​

For teams who want direct control over their dependencies, using npm-check-updates allows to manually update all Serenity/JS dependencies when needed.

To update all Serenity/JS dependencies listed in your package.json file to the latest versions, run the following command:

npx -y npm-check-updates '/@serenity-js/' -u

You can also extend this command to update all dependencies in your package.json:

npx -y npm-check-updates -u

After updating package.json, install the dependencies:

npm install

Benefits​

  • Control: You decide when and which dependencies to update, ensuring alignment with your development schedule.
  • Granularity: Allows selective updates, ideal for projects that require stability or when testing compatibility with other tools.
  • Transparency: Changes to dependencies are explicitly visible in your commit history.

Disadvantages​

  • Manual effort: Requires time and attention to run updates and review changes.
  • Inconsistent timing: Updates may be delayed if not regularly checked, potentially missing critical patches.

Recommendation​

This approach is recommended for projects with strict update policies or those requiring compatibility testing with other tools. To mitigate the disadvantages, consider using a dependency management bot.

Using a dependency management bot​

Dependency management bots like Renovate or Dependabot automate the process of checking for updates and proposing pull requests.

Benefits​

  • Proactive updates: Ensures timely adoption of new features, fixes, and patches.
  • Streamlined workflow: Automates the creation of pull requests with changelogs for easy review.
  • Security: Helps identify and update dependencies with critical security vulnerabilities.
  • Customisability: Configure the bot to match your team’s update policies (e.g., daily/weekly schedules, dependency groups).

Disadvantages​

  • Requires setup: Initial configuration might require effort, especially for complex projects.
  • Possible noise: If bots are not configured correctly, they might create overly granular or too frequent pull requests.

Recommendation​

This approach is used by Serenity/JS and is recommended for larger teams or projects that require both stability and regular updates.

To mitigate the disadvantages, use a configuration file that groups Serenity/JS-related dependencies and sets update policies. For example, you can use the below file to configure Renovate:

renovate.json
{
  "extends": [
    "config:base"
  ],
  "rangeStrategy": "bump",
  "packageRules": [
    {
      "packagePatterns": [
        "^@serenity-js",
        "^playwright$",
        "^@playwright/",
        "npm-failsafe"
      ],
      "groupName": "Serenity/JS and Playwright",
    }
  ]
}