Skip to content

Latest commit

 

History

History
186 lines (118 loc) · 8.88 KB

CONTRIBUTING.md

File metadata and controls

186 lines (118 loc) · 8.88 KB
Raw

Contributing to TestCafe

Table of Contents

The TestCafe Community

TestCafe is maintained by a core team of developers at Developer Express. TestCafe is an open-source project, and would not be possible without active support from the community. We appreciate and encourage your contributions.

The TestCafe team maintains a project roadmap. This roadmap contains a list of capabilities that we want to implement in the near future. We update the roadmap as we receive user feedback.

GitHub activity helps the TestCafe team gauge what our users want the most. Submit a GitHub issue to share your ideas about the future of TestCafe. Add votes and comments to existing issues to help us prioritize our work.

TestCafe is proud to follow a set of ethical standards called the Contributor Covenant Code of Conduct. This code of conduct helps us create a more open and welcoming environment. The TestCafe team expects both project maintainers and project contributors to adhere to these rules.

Build TestCafe from Source

If you want to test the development version of TestCafe, or contribute code to the project, you need to know how to build the framework from source.

Prerequisites

TestCafe is a Node.js application. It supports all actively maintained versions of the Node.js framework. The installation process requires the node package manager (npm) software utility.

Run the following shell command to check if your operating system contains node and npm:

node -v; npm -v

If your system does not contain Node.js, download and install it from the Node.js website.

You also need Git installed on your computer. Installation instructions depend on your operating system — consult the Git website for details.

Build TestCafe

  1. Clone the TestCafe repository.

  2. Navigate to the root directory of the repository. To install dependencies, run the following shell command:

    npm install

  3. Run the following shell command to build the project:

    npx gulp build

You now have two options to install TestCafe:

  • npm link is a useful option for testers and most other users. This command creates a symbolic link (symlink) that lets you use TestCafe while you make changes to its code.

  • npm pack creates a package that you can install with npm install package_name.

npm link

  1. From the root of the testcafe directory, run the following shell command:

    npm link

  2. Navigate to the directory that contains your test files and run the following shell command:

    npm link testcafe
Install from a package

  1. Run the following shell command to package the framework:

    npm pack

    This command creates a name-version.tgz package in the testcafe folder.

  2. Run the following shell command to install the package globally. Replace the path/to/package part with the path to the package:

    npm install -g path/to/package

Note

The /lib directory stores build artifacts. Build tasks remove this folder before they run. To remove this directory manually, run the following command:

gulp clean

Test New Versions of Testcafe

Before we publish new versions of TestCafe on npm, we thoroughly test them. We invite you to participate in this process.

Please don't use the development version of TestCafe in production.

Report Bugs and Issues

If you encounter a bug, check the issue tracker for an existing bug report. If no report for the issue exists, please file a new issue.

When you create a new issue, GitHub displays an issue template. Complete all sections of the template to help us understand the problem you are describing. Missing information could increase ticket processing time.

You are also welcome to submit issues relating to our documentation.

Create a Minimal Working Example

It is important to include a Minimal Working Example (MWE) with your bug report. A good MWE ensures the issue is easy to reproduce and troubleshoot, while being as small and as simple as possible.

A Minimal Working Example should:

  • Be simple and easy to follow. Convoluted scenarios are hard to reproduce.
  • Exclude code that does not help reproduce the issue. Remove actions that do not affect the outcome.
  • Include a complete set of relevant data: the URL of the test page, the list of launch options, and the steps you follow to launch the tests.

For further information, refer to our MWE guide.

Ask for Community Support

If you need help with TestCafe, or want to help other users, join the TestCafe community on Stack Overflow. Ask and answer questions with the TestCafe tag.

Contribute Code

TestCafe expects contributor pull requests to meet certain standards. Complete the following tasks before you submit a pull request:

  • Include appropriate tests:

    • If your code contains a bug fix, include regression tests.
    • If your code introduces new capabilities, include unit tests and/or functional tests.

  • Run the following shell commands to fetch upstream changes and rebase your branch onto master:

    git checkout master
git fetch upstream
git merge upstream/master

  • Run the following shell commands to test the changes:

    gulp test-server
gulp test-functional-local
gulp test-client-local

  • Give the pull request a name that describes the changes you made.

  • If the pull request contains a bug fix, reference the issue that it closes in the description.

  • The TestCafe package includes a linter and rules for that linter. Lint your code before you submit it.

Please keep in mind that the team may suspend or reject pull requests. There are multiple reasons why this can happen:

We merge pull requests after the changes are documented. If you want to document a new capability, add a comment with the description to the pull request. Review our writing guidelines before you proceed.

Contribute to Documentation

Users cannot submit documentation pull requests because TestCafe stores documentation in a private repository. To notify the team of an inaccuracy in the documentation, create a Github issue with the AREA: docs label.

Guidelines

The TestCafe team adheres to a set of writing guidelines that make our documentation easy to read. Follow these rules when you submit written content:

  • Avoid gerunds, passive voice, and past tense.
  • Avoid double negatives.
  • Avoid misleading or ambiguous words and jargon.
  • Avoid vague and confusing references between pronouns and their antecedents.
  • Be descriptive rather than prescriptive.
  • Keep your sentences short and simple. Make sure that each sentence expresses only a single idea.
  • Do not repeat the same piece of information.
  • If possible, include interactive examples (codes samples, screenshots, etc.).