|
| 1 | +--- |
| 2 | +sidebar_position: 3 |
| 3 | +title: Updating Serenity/JS |
| 4 | +--- |
| 5 | + |
| 6 | + |
| 7 | +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, |
| 8 | +performance improvements, and critical security patches. |
| 9 | +Regular updates help avoid technical debt, reduce the risk of using deprecated features, and ensure compatibility with the latest tools and platforms. |
| 10 | + |
| 11 | +In this guide, we’ll explore the best approaches for staying up-to-date with Serenity/JS. |
| 12 | + |
| 13 | +## Using flexible version ranges |
| 14 | + |
| 15 | +Configuring your `package.json` to use the `3.x` version range for Serenity/JS modules allows your Node package manager, like |
| 16 | +[NPM](https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager), |
| 17 | +[Yarn](https://classic.yarnpkg.com/lang/en/docs/install/), |
| 18 | +or [PNPM](https://pnpm.io/), to install the latest compatible versions automatically. |
| 19 | + |
| 20 | +### Example configuration |
| 21 | + |
| 22 | +```json title="package.json" |
| 23 | +{ |
| 24 | + "devDependencies": { |
| 25 | + "@serenity-js/core": "3.x", |
| 26 | + "@serenity-js/assertions": "3.x", |
| 27 | + "@serenity-js/rest": "3.x", |
| 28 | + "@serenity-js/playwright": "3.x", |
| 29 | + "@serenity-js/playwright-test": "3.x", |
| 30 | + "@serenity-js/serenity-bdd": "3.x", |
| 31 | + "@serenity-js/web": "3.x" |
| 32 | + } |
| 33 | +} |
| 34 | +``` |
| 35 | + |
| 36 | +### Benefits |
| 37 | + |
| 38 | +- **Automation**: Your package manager will automatically install the latest compatible versions of your dependencies during a fresh npm install, |
| 39 | + it will also update its lock file to reflect the exact versions installed. |
| 40 | +- **Ease of use**: No manual intervention is required to update dependencies within the specified range. |
| 41 | +- **Predictability**: Your package manager will ensure compatibility since the version constraint (3.x) avoids breaking changes introduced by major version updates. |
| 42 | + |
| 43 | +### Disadvantages |
| 44 | + |
| 45 | +- **No explicit control**: Updates occur implicitly when installing dependencies, which may not align with your preferred schedule. |
| 46 | +- **Possible discrepancies**: If team members or CI pipelines use different node_modules states, discrepancies may arise. |
| 47 | + |
| 48 | +### Recommendation |
| 49 | + |
| 50 | +This approach is recommended for simple project or those without strict update policies. |
| 51 | +To mitigate the disadvantages, make sure to keep the lock file generated by your package manager under version control. |
| 52 | + |
| 53 | +## Updating Serenity/JS modules manually |
| 54 | + |
| 55 | +For teams who want direct control over their dependencies, using [`npm-check-updates`](https://www.npmjs.com/package/npm-check-updates) |
| 56 | +allows to manually update all Serenity/JS dependencies when needed. |
| 57 | + |
| 58 | +To update all Serenity/JS dependencies listed in your `package.json` file to the latest versions, run the following command: |
| 59 | + |
| 60 | +```npm |
| 61 | +npx -y npm-check-updates '/@serenity-js/' -u |
| 62 | +``` |
| 63 | + |
| 64 | +You can also extend this command to update all dependencies in your `package.json`: |
| 65 | + |
| 66 | +```npm |
| 67 | +npx -y npm-check-updates -u |
| 68 | +``` |
| 69 | + |
| 70 | +After updating `package.json`, install the dependencies: |
| 71 | + |
| 72 | +```sh npm2yarn |
| 73 | +npm install |
| 74 | +``` |
| 75 | + |
| 76 | +### Benefits |
| 77 | + |
| 78 | +- **Control**: You decide when and which dependencies to update, ensuring alignment with your development schedule. |
| 79 | +- **Granularity**: Allows selective updates, ideal for projects that require stability or when testing compatibility with other tools. |
| 80 | +- **Transparency**: Changes to dependencies are explicitly visible in your commit history. |
| 81 | + |
| 82 | +### Disadvantages |
| 83 | + |
| 84 | +- **Manual effort**: Requires time and attention to run updates and review changes. |
| 85 | +- **Inconsistent timing**: Updates may be delayed if not regularly checked, potentially missing critical patches. |
| 86 | + |
| 87 | +### Recommendation |
| 88 | + |
| 89 | +This approach is recommended for projects with strict update policies or those requiring compatibility testing with other tools. |
| 90 | +To mitigate the disadvantages, consider using a dependency management bot. |
| 91 | + |
| 92 | +## Using a dependency management bot |
| 93 | + |
| 94 | +Dependency management bots like [Renovate](https://docs.renovatebot.com/) or [Dependabot](https://docs.github.com/en/code-security/getting-started/dependabot-quickstart-guide) automate |
| 95 | +the process of checking for updates and proposing pull requests. |
| 96 | + |
| 97 | +### Benefits |
| 98 | + |
| 99 | +- **Proactive updates**: Ensures timely adoption of new features, fixes, and patches. |
| 100 | +- **Streamlined workflow**: Automates the creation of pull requests with changelogs for easy review. |
| 101 | +- **Security**: Helps identify and update dependencies with critical security vulnerabilities. |
| 102 | +- **Customisability**: Configure the bot to match your team’s update policies (e.g., daily/weekly schedules, dependency groups). |
| 103 | + |
| 104 | +### Disadvantages |
| 105 | + |
| 106 | +- **Requires setup**: Initial configuration might require effort, especially for complex projects. |
| 107 | +- **Possible noise**: If bots are not configured correctly, they might create overly granular or too frequent pull requests. |
| 108 | + |
| 109 | +### Recommendation |
| 110 | + |
| 111 | +This approach is used by Serenity/JS and is recommended for larger teams or projects that require both stability and regular updates. |
| 112 | + |
| 113 | +To mitigate the disadvantages, use a configuration file that groups Serenity/JS-related dependencies and sets update policies. |
| 114 | +For example, you can use the below file to [configure Renovate](https://docs.renovatebot.com/configuration-options/): |
| 115 | + |
| 116 | +```json title="renovate.json" |
| 117 | +{ |
| 118 | + "extends": [ |
| 119 | + "config:base" |
| 120 | + ], |
| 121 | + "rangeStrategy": "bump", |
| 122 | + "packageRules": [ |
| 123 | + { |
| 124 | + "packagePatterns": [ |
| 125 | + "^@serenity-js", |
| 126 | + "^playwright$", |
| 127 | + "^@playwright/", |
| 128 | + "npm-failsafe" |
| 129 | + ], |
| 130 | + "groupName": "Serenity/JS and Playwright", |
| 131 | + } |
| 132 | + ] |
| 133 | +} |
| 134 | +``` |
0 commit comments