You like WebdriverIO and want to help making it better? Awesome! We are working to make this process as easy and transparent as possible. We might be not quite there yet but this guide will help you to ramp you up as a contributor and give you everything you need to make your first contribution. If there is any information missing that prevents you from sending in a pull request, please let us know. We treat these kind of issues like actual bugs.
Code of Conduct
Everyone who participates in this project, either as a user or a contributor, is obliged to follow the projects Code of Conduct. Every violation against it will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
Find A Way To Contribute
The project offers a variety of ways to contribute. If you struggle to find something suited for you, join the WebdriverIO support channel on Matrix and reach out to the maintainer there. Don't be shy, they are there to help!
You can participate by:
- contributing code
- improving documentation
- help us translate the project to more languages
- answer questions and provide help in the Discord support channel
- create educational content (blog posts, tutorials, videos, etc.)
- spread the good word about the project (e.g. via Twitter)
- create bugs if you discover them while using WebdriverIO
- make feature requests if you are missing something in the project
- if you'd like to support us monetarily, consider donating to the project
The maintainers of the project try to organize all issues in the way that should allow anyone to have enough context to start working on it. If this is not the case please mention it in the issue thread so that either the issue creator or a maintainer can provide more information.
If you want to contribute code, a general good first way to find a task to work on is to look into all tickets with the label
help wanted and/or
good first pick. All these tickets are up for grab if they haven't a user assigned to them. If you find something that interests you, ensure to let us know in the issue thread that you have the intend to work on it.
Often issues require some amount of context to the problem which makes it difficult to get an idea about what needs to be done. Depending on your experience using / working with the project this context can be missing. Often it helps to start with tasks around missing documentation or just increase test coverage of some parts in the code. After some time you will get more familiar with the codebase which allows you to pick up more difficult tasks.
If you can't find something that suits you, look into the project roadmap to see if there is something interesting for you. At the end you can also always reach out to the maintainers in the Discord support channel. They are responsible to find a task for you.
Reporting New Issues
When opening a new issue, always make sure to fill out the issue template. This step is very important! Not doing so may result in your issue not managed in a timely fashion. Don't take this personally if this happens, and feel free to open a new issue once you've gathered all the information required by the template.
- One issue, one bug: Please report a single bug per issue.
- Provide reproduction steps: List all the steps necessary to reproduce the issue. The person reading your bug report should be able to follow these steps to reproduce your issue with minimal effort.
Providing a reproducible example
A reproducible example is a simple, self-contained script or program that demonstrates the issue or bug you're experiencing. The goal is to allow others to recreate the problem easily and efficiently.
Steps to Create a Reproducible Example:
- Isolate the Problem:
- Narrow down your code to the smallest amount that still reproduces the issue.
- Remove any non-essential code or dependencies that are not related to the problem.
- Ensure that others can run your example and reproduce the issue:
- It should not require any non-standard setup unless absolutely necessary, e.g. remove any need for special software or services like CI vendors.
- Document steps necessary to execute the reproducible example
- Share project
- Create a new public GitHub repository and push your reproducible example to it.
- Share the link to the repository in the issue.
- Document what behavior you observe and what behavior you would expect
Note: if you can't provide a reproducible example we unfortunately are forced to close the issue.
The flowcharts provide a high level overview of the WebdriverIO ecosystem and how the different packages interact with each other.
WDIO Commands - Explains the wdio config, install and repl command workflows.
Create local worker process - Explains the interaction between the @wdio/cli, @wdio/local-runner and @wdio/runner packages and how a worker process is created.
Test execution - Overview of how the tests are run in the local runner worker process.
High level overview - Flow chart provides a high level overview of how the WebdriverIO ecosystem interacts with the core packages.
Proposing a Change
We are happy for every idea you have that improves the usability of the framework. If you have an idea about a new feature please raise a feature request first to get feedback by the maintainer team on it. This lets us reach an agreement on your proposal before you put significant effort into it.
If you’re only fixing a bug, it’s fine to submit a pull request right away, but we still recommend to file an issue detailing what you’re fixing. This is helpful in case we don’t accept that specific fix but want to keep track of the issue.
Work With The Code
If you make any changes to the code, you want to test it quickly to see if they do what you expect. There are a couple of ways to do that in WebdriverIO. For one, you can link single sub-packages into your own project to see if the changes you've made have the effect you expected.
Another way to test changes in WebdriverIO is by using its example directory or by running its smoke test suite. The example directory is a set of sample scripts that use WebdriverIO in various of ways. Here, you need to have a browser driver running to run the scripts. With the smoke test suite you can run various flavors of WebdriverIO within a predefined execution scenario. All of these scenarios are defined in our WebDriver Mock Service that mimics a browser driver by stubbing the endpoints with predefined responses. It is a great way to run WebdriverIO suites quickly without having to setup anything.
Make a Pull Request
Once you have a fix implemented or finished a feature implementation you can make a pull request. Your changes needs to be pushed on your WebdriverIO fork. In the GitHub UI you should see a button popping up that allows you to raise a PR to the main repository.
We already provide a template for you to fill out. There are not many rules to follow here. Just try to explain your change with as much detail as possible. Make sure that you have written enough unit tests for your changes otherwise the code coverage check will let the build fail.
Like in many Open Source projects we ask you to sign a CLA which is a Contributor License Agreement that ensures that all contributions to the project are licensed under the project's respective open source license, which is MIT. It regulates the legal implications of you providing us (as the OpenJS Foundation) code changes.
The WebdriverIO maintainer will review your pull request as soon as possible. They will then either approve and merge your changes, request modifications or close with an explanation.
Set Up Project
Fork the project.
Clone the project somewhere on your computer
$ git clone email@example.com:<your-username>/webdriverio.git
On Windows, you need to set git config
trueas we currently have some symbolic links for type definition committed to our repo.
- To set git config globally:
git config --global --add core.symlinks true
- To set git config locally when cloning the repo:
git -c core.symlinks=true clone firstname.lastname@example.org:<your-username>/webdriverio.git.
See https://github.com/git-for-windows/git/wiki/Symbolic-Links for more information
- To set git config globally:
If you need to update your fork you can do so following the steps here
Switch to the most recent Node LTS (you should be able to use older/newer versions of Node but we recommend to use v18 LTS so all developers are on the same side) or to the one denoted in
.nvmrc. We recommend to use
nvmto switch between Node.js versions.
Set up the project: First make sure you have the right Node.js version installed. You can find the current defined development version in
.nvmrcwithin the root directory of the project. The easiest way to handle multiple Node.js versions is by using NVM. After it is installed you can run:
$ nvm install
This will install the defined Node.js version for you. You can then go ahead and set-up the project via:
$ npm install
$ npm run setup
The second command does two things:
Cleans (possible) existing build artifacts via
npm run clean
If you have compiled the code this command will remove them as well as all dependencies of the subpackages.
Bootstraps sub-projects via
npm run bootstrap
Many packages depend on each other, in order to properly set up the dependency tree you need to run the Lerna Bootstrap command to create all necessary links. As this project also does some other house keeping tasks, it is recommended to use the package bootstrap command.
Builds all subpackages via
npm run build
As the last step you need to build all sub-packages in order to resolve the internal dependencies. WebdriverIO uses TypeScript as a compiler.
Run Tests to ensure that everything is set up correctly
# run the complete unit test suite
$ npm run test
# run test for a specific sub project (e.g. webdriver)
$ npx vitest ./packages/webdriver/tests
It should give you a passing result. Now you can move on to set up your development environment and start working on some code. If tests do not pass please create an issue and provide logs to the error.