From 95afa6129a6f776cf9cfa0abfeddf1a675a1ecc3 Mon Sep 17 00:00:00 2001 From: wixmobile Date: Sun, 10 Dec 2023 08:37:03 -0800 Subject: [PATCH] Publish docs version 20.x --- .../version-20.x/api/webviews.md | 5 +- .../version-20.x/config/testRunner.mdx | 10 + .../version-20.x/contributing.md | 219 +++--------------- .../contributing/code-of-conduct.md | 143 ++++++++++++ .../contributing/code/building-and-testing.md | 138 +++++++++++ .../contributing/code/example-projects.md | 10 + .../contributing/code/overview.md | 50 ++++ .../code/reviewing-pull-requests.md | 42 ++++ .../code/setting-up-the-dev-environment.md | 65 ++++++ .../code/submitting-pull-requests.md | 44 ++++ .../contributing/documentation.md | 37 +++ .../contributing/feature-requests.md | 32 +++ .../questions/answering-questions.md | 26 +++ .../questions/asking-questions.md | 34 +++ .../contributing/reporting-bugs.md | 29 +++ .../version-20.x/guide/launch-args.md | 2 +- .../introduction/environment-setup.md | 83 +++++++ .../introduction/getting-started.mdx | 108 ++++----- .../version-20.x-sidebars.json | 33 ++- 19 files changed, 850 insertions(+), 260 deletions(-) create mode 100644 website/versioned_docs/version-20.x/contributing/code-of-conduct.md create mode 100644 website/versioned_docs/version-20.x/contributing/code/building-and-testing.md create mode 100644 website/versioned_docs/version-20.x/contributing/code/example-projects.md create mode 100644 website/versioned_docs/version-20.x/contributing/code/overview.md create mode 100644 website/versioned_docs/version-20.x/contributing/code/reviewing-pull-requests.md create mode 100644 website/versioned_docs/version-20.x/contributing/code/setting-up-the-dev-environment.md create mode 100644 website/versioned_docs/version-20.x/contributing/code/submitting-pull-requests.md create mode 100644 website/versioned_docs/version-20.x/contributing/documentation.md create mode 100644 website/versioned_docs/version-20.x/contributing/feature-requests.md create mode 100644 website/versioned_docs/version-20.x/contributing/questions/answering-questions.md create mode 100644 website/versioned_docs/version-20.x/contributing/questions/asking-questions.md create mode 100644 website/versioned_docs/version-20.x/contributing/reporting-bugs.md create mode 100644 website/versioned_docs/version-20.x/introduction/environment-setup.md diff --git a/website/versioned_docs/version-20.x/api/webviews.md b/website/versioned_docs/version-20.x/api/webviews.md index 24c5681d57..13f8a95f07 100644 --- a/website/versioned_docs/version-20.x/api/webviews.md +++ b/website/versioned_docs/version-20.x/api/webviews.md @@ -140,7 +140,6 @@ Web view actions are used to interact with elements within a web view: - [`focus()`] - [`moveCursorToEnd()`] - [`runScript()`] -- [`runScriptWithArgs()`] - [`getCurrentUrl()`] - [`getTitle()`] @@ -361,9 +360,7 @@ await expect(web.element(by.web.id('identifier'))).not.toHaveText('Hello World!' [name]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input#name -[`runScript()`]: webviews.md#runscriptscript - -[`runScriptWithArgs()`]: webviews.md#runscriptwithargsscript-args +[`runScript()`]: webviews.md#runscriptscript-args [`getCurrentUrl()`]: webviews.md#getcurrenturl diff --git a/website/versioned_docs/version-20.x/config/testRunner.mdx b/website/versioned_docs/version-20.x/config/testRunner.mdx index ca7638d5f4..524f5d2c1d 100644 --- a/website/versioned_docs/version-20.x/config/testRunner.mdx +++ b/website/versioned_docs/version-20.x/config/testRunner.mdx @@ -142,6 +142,16 @@ Default: `false`. When true, tells `detox test` to cancel next retrying if it gets at least one report about a [permanent test suite failure](../api/internals.mdx#reporting-test-results). Has no effect, if [`testRunner.retries`] is undefined or set to zero. +### `testRunner.detached` \[boolean] + +Default: `false`. + +When true, tells `detox test` to spawn the test runner in a detached mode. + +This is useful in CI environments, where you want to intercept SIGINT and SIGTERM signals to gracefully shut down the test runner and the device. + +Instead of passing the kill signal to the child process (the test runner), Detox will send an emergency shutdown request to all the workers, and then it will wait for them to finish. + ### `testRunner.forwardEnv` \[boolean] Default: `false`. diff --git a/website/versioned_docs/version-20.x/contributing.md b/website/versioned_docs/version-20.x/contributing.md index 9014072c5e..869f6ec2ed 100644 --- a/website/versioned_docs/version-20.x/contributing.md +++ b/website/versioned_docs/version-20.x/contributing.md @@ -1,201 +1,48 @@ -# Contributing +# Contributing to Detox - +Detox, an open-source project, greatly values community involvement. Whether you're a mobile developer, QA specialist, or an open source enthusiast, your contribution could significantly enhance the reliability, user experience, and development process of mobile applications. -This guide is about contributing to our codebase. +## Our Code of Conduct -We donโ€™t have any special guidelines - just some setup walk-through! +To ensure an inclusive, safe environment for all contributors, we adhere to the [Contributor Covenant code of conduct]. This well-recognized code provides clear guidelines for respectful behavior. -### Environment +## Ways to Contribute -First, complete our [Getting Started](introduction/getting-started.mdx) guide. +All contributions, regardless of size, can help shape Detox. We welcome: -#### Install the monorepo management tool, `lerna` +- **[Questions]**: Your inquiries can help identify gaps in our documentation and benefit all users. +- **[Answers]**: Assisting other Detox users by providing guidance or responses to their questions. +- **[Bug Reports]**: Help us identify and resolve Detox issues. +- **[Feature Suggestions]**: Your ideas for new features can help us improve Detox according to user needs. +- **[Code Contributions]**: Directly contribute by fixing bugs, adding features, or improving our codebase. +- **[Code Reviews]**: Help maintain the quality of our codebase by reviewing others' contributions. +- **[Documentation Enhancements]**: Improve Detox documentation from user guides to API references. +- **Content Creation**: Share your knowledge of Detox through blog posts, tutorials, videos, and more. We're always excited to share your content on our [Twitter account] and [Discord server]. -```bash npm2yarn -npm install lerna@3.x.x --global -``` +Your active participation helps build a vibrant community dedicated to improving mobile development. -For all the internal projects (detox, detox-cli, demos, test) `lerna` will create symbolic links in `node_modules` instead of `npm` copying the content of the projects. This way, any change you do on any code is there immediately. There is no need to update node modules or copy files between projects. +## Engaging in the Community -#### Install common React Native dependencies +Join our [Discord server] to discuss Detox, ask questions, and provide help. Follow our [Twitter account] for updates on the project. -React-Native CLI: +Becoming an active community member is a great way to start contributing to Detox. It provides familiarity with the project, helps identify opportunities to contribute, and allows guidance from other contributors. The more you engage, the more recognition your contributions receive and the greater impact you can make on the project's direction. -```bash npm2yarn -npm install react-native-cli --global -``` +## Appreciation and Recognition -Watchman: +All our contributors deserve recognition. We express our gratitude by featuring them in our [Release Notes]. -```bash -brew install watchman -``` +### Core Contributors Program -#### xcpretty +We plan to launch a "Core Contributor" program for individuals who have significantly contributed to Detox and shown deep understanding of the project while being active in the community. Core contributors will be invited to a private Discord channel for exclusive discussions and will receive a distinguished role on our Discord server. -You must also have `xcpretty` installed: - -```bash -gem install xcpretty -``` - -### Detox - -#### Clone Detox and Submodules - -```bash -git clone git@github.com:wix/Detox.git -cd detox -git submodule update --init --recursive -``` - -(this makes sure all git submodule dependencies have been properly checked out) - -#### Installing and Linking Internal Projects - -```bash -lerna bootstrap -``` - -#### Building and Testing - -##### Automatically - -`scripts/ci.ios.sh` and `scripts/ci.android.sh` are the scripts Detox runs in CI, they will run `lerna bootstrap`, unit tests, and E2E tests. Make sure these scripts pass before submitting a PR, this is exactly what Detox is going to run in CI. - -##### Manually - -The following steps can be run manually in order to build / test the various components of Detox. - -###### 1. Unit Tests and Lint - -```bash -lerna run test -``` - -Detox JS code is 100% test covered and is set to break the build if coverage gets below, so make sure you run unit tests (`lerna run test`) locally before pushing. - -Alternatively, to run only the JS tests, run the following from the `detox/detox` directory: - -```bash npm2yarn -npm run unit -``` - -or - -```bash npm2yarn -npm run unit:watch -``` - -After running the tests, _Jest_ will create a coverage report you can examine: - -```bash -cd detox -open coverage/lcov-report/index.html -``` - -###### 2. Running Detox E2E Coverage Tests - -Detox has a suite of end-to-end tests to test its own API while developing (and for regression); We maintain a special application that is "tested" against Detoxโ€™s API, but essentially, itโ€™s the API that is tested, not the app. - -To run the tests, you must first build the native code and then run based on your target of choice (Android / iOS): - -- **iOS:** - - ```bash npm2yarn - cd detox/test - npm run build:ios - npm run e2e:ios - ``` - -- **Android:** - - ```bash npm2yarn - cd detox/test - npm run build:android - npm run e2e:android - ``` - -FYI Android test project includes two flavors: - -- `fromBin` - (**standard use case**) utilizes the precompiled `.aar` from `node_modules` just like a standard RN project. -- `fromSource` - compiles the project with RN sources from `node_modules`, this is useful when developing and debugging Espresso idle resource. - [Here](https://github.com/facebook/react-native/wiki/Building-from-source#android) are the prerequisites to compiling React Native from source. - -Each build can be triggered separately by running its Gradle assembling task (under `detox/test/android/`): - -```bash -./gradlew assembleFromSourceDebug -``` - -or: - -```bash -./gradlew assembleFromBinDebug -``` - -To run from Android Studio, React Nativeโ€™s `react.gradle` script may require `node` to be in path. -On MacOS, environment variables can be exported to desktop applications by adding the following to your `.bashrc`/`.zshrc`: - -```bash -launchctl setenv PATH $PATH -``` - -###### 3. Android Native Unit-Tests - -Under `detox/`: - -```bash -npm run unit:android-release -``` - -:::caution Note -Due to limitations with Robolectric, this currently does not work with JDK 17. Best to use Java 11, as explained in the [Android environment setup guide](./guide/android-dev-env.md). -::: - -### Detox - Example Projects - -This is in fact a monorepo that also sports some example projects (for usage reference), alongside the main test project: - -- `examples/demo-react-native-jest`: Demonstrate usage of Detox in a React Native app project. -- `examples/demo-native-ios`: Demonstrates usage of Detox in a pure-native iOS app. -- `examples/demo-native-android` (broken): Demonstrates usage of Detox in a pure-native Android app. -- `examples/demo-pure-native-android`: Demonstrates usage of the _pure_ [Detox-Native](https://github.com/wix/Detox/tree/master/detox-native/README.md) project -- more... - -**In order to run E2E tests associated with any of these projects, refer to the [project-specific](https://github.com/wix/Detox/tree/master/examples) READMEs.** - -### Detox Documentation Website - -The [documentation website](https://wix.github.io/Detox) is built using [Docusaurus](https://docusaurus.io/). - -To run the website locally, run the following commands: - -```bash npm2yarn -cd website -npm install -npm start -``` - -#### Updating the Website - -To update a specific page, edit the corresponding markdown file in `docs/`. To add a new page, create a new markdown file in `docs/` and add a link to it in `website/sidebars.json`. - -##### Website Deployment - -While changes to the website are published automatically on every commit to `master` under the `Next` version, tagging and locking docs to a specific version is done automatically on every Detox release. - -In case you want to update the docs for a specific version, you can change the related files and code under `website/versioned_docs/version-/` and `website/versioned_sidebars/version--sidebars.json`. - -##### Update Old Versions - -To update a specific version with the latest changes: - -1. Remove the version from `versions.json`. -1. Run `npm run docusaurus docs:version `. - -##### Inspect Documentation Style Changes - -This [demo page](demo.mdx) serves as a visual representation of the styling and formatting of our documentation. -If you are changing the stylesheets, check with it to prevent undesirable visual regressions. +[Contributor Covenant code of conduct]: contributing/code-of-conduct.md +[Questions]: contributing/questions/asking-questions.md +[Answers]: contributing/questions/answering-questions.md +[Bug Reports]: contributing/reporting-bugs.md +[Feature Suggestions]: contributing/feature-requests.md +[Code Contributions]: contributing/code/overview.md +[Code Reviews]: contributing/code/reviewing-pull-requests.md +[Documentation Enhancements]: contributing/documentation.md +[Discord server]: https://discord.gg/CkD5QKheF5 +[Twitter account]: https://twitter.com/detoxe2e +[Release Notes]: https://github.com/wix/Detox/releases diff --git a/website/versioned_docs/version-20.x/contributing/code-of-conduct.md b/website/versioned_docs/version-20.x/contributing/code-of-conduct.md new file mode 100644 index 0000000000..060a64209a --- /dev/null +++ b/website/versioned_docs/version-20.x/contributing/code-of-conduct.md @@ -0,0 +1,143 @@ +# Code of Conduct + +:::note Attribution + +This Code of Conduct is adapted from the [Contributor Covenant], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +::: + +Our community is dedicated to providing a safe and inclusive environment for all contributors. +To ensure this, we have adopted the **[Contributor Covenant]** code of conduct. +This widely recognized and respected code of conduct sets clear guidelines for behavior, and it's easy for everyone to understand and follow. + +By participating in the Detox community, you agree to abide by the terms of this code of conduct. +We take violations of this code of conduct seriously, and we will not tolerate any form of harassment or discrimination. + +If you have any questions or concerns, please reach out to the project maintainers. + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or advances of + any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, + without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at [our Discord server]. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +[Contributor Covenant]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations +[our Discord server]: https://discord.gg/CkD5QKheF5 diff --git a/website/versioned_docs/version-20.x/contributing/code/building-and-testing.md b/website/versioned_docs/version-20.x/contributing/code/building-and-testing.md new file mode 100644 index 0000000000..e7a5ff26b5 --- /dev/null +++ b/website/versioned_docs/version-20.x/contributing/code/building-and-testing.md @@ -0,0 +1,138 @@ +# Building and Testing + +Our JavaScript code is thoroughly verified with comprehensive unit tests, complemented by integration tests. +Additionally, our native code undergoes rigorous testing through both unit and integration tests. +To ensure complete functionality, we conduct end-to-end tests on a fully-featured React Native application, designed to encompass all our public APIs (refer to our [test app] for details). + +:::note Important + +Before submitting a pull request, please ensure at a minimum that your code adheres to our linting standards and that all unit tests run successfully without any errors. + +::: + +The following sections describe how to build and test our code, with a general instruction. +However, we recommend you to refer to our `package.json` files for a complete list of available scripts: + +- Detox Framework: [`detox/package.json`] +- Detox Test App: [`detox/test/package.json`] + +## Unit Tests (JavaScript) + +We use [Jest] for running our unit tests. + +Under the `detox/` directory, run the following command to run the unit tests with coverage: + +```bash +cd detox +npm run unit +``` + +The unit tests reside alongside the JavaScript code. Typically, they can also be easily run directly from within an IDE such as [WebStorm](https://www.jetbrains.com/webstorm/) or [vscode](https://code.visualstudio.com/), even in debug (i.e step-by-step execution) mode. + +## Unit Tests - Android Native + +We also have unit tests for our native code (Android only). They reside alongside Detox's native Android code, under a dedicated subdirectory called `testFull`. You can run them using the following commands: + +```bash +cd detox +npm run unit:android-release +``` + +The native unit tests can also be run in [Android Studio](https://developer.android.com/studio) (i.e. the IDE for Android apps development). Most tests can be run seamlessly using Android Studio's build-in support for unit-tests, but some require a plugin called [Spek](https://plugins.jetbrains.com/plugin/10915-spek-framework), which can be installed from within Android Studio itself - under the Plugins marketplace. + +## iOS: Rebuilding the Framework + +After changing the native code of Detox iOS, you need to rebuild the Detox framework. This is done when running: + +```bash +detox build-framework-cache +``` + +Note that it is only required when you change the native code of Detox, or one of its dependencies (e.g. [DetoxSync]). +If you are only changing the JavaScript code, you don't need to rebuild the framework. + +## Building the Detox Test App + +The Detox self-test app is a full-feature React Native app for testing Detox end-to-end. + +Before running the tests, you must first build the Detox test app. To do so, under `detox/test`, use the `build` command of the Detox CLI. +List of available configurations can be found under [`detox/test/e2e/detox.config.js`]. + +For example, to build the Detox test app for iOS in release mode, run: + +```bash +cd detox/test +detox build --configuration ios.sim.release + +### End-to-End Tests + +To run the end-to-end tests (after building the app), use the `test` command of the Detox CLI. + +For example, to run the end-to-end tests for iOS in release mode, run: + +```bash +cd detox/test +detox test --configuration ios.sim.release +``` + +To run in Android release mode, run: + +```bash +cd detox/test +detox test --configuration android.emu.release +``` + +:::note + +Mind that on Android, Detox expects a specific AVD with a [specific name](https://github.com/wix/Detox/blob/24f68c3bd7675ed6f508e3f5fea97509eb7991b2/detox/test/e2e/detox.config.js#L111) to be available on your computer. +Be sure to [install such an AVD](https://developer.android.com/studio/run/managing-avds#createavd), beforehand. + +::: + +## Integration Tests + +Besides unit tests and end-to-end tests, we have some middle ground integration tests, which typically run Detox in a custom headless-like mode (i.e. stubs replace devices). Those tests typically execute Detox from a command line in that mode, and then do some post-processing of the results. We use [Jest] for running our integration tests. + +The integration reside under a dedicated directory alongside Detox's the self-test app's code. + +Run the following command to run the integration tests: + +```bash +cd detox/test +npm run integration + +### Linting + +We use [ESLint] for linting our JavaScript code. + +You can run the linter locally using the following command (under `detox/test`): + +```bash +npm run lint +``` + +We also test our types using the following command: + +```bash +npm run test:types +``` + +## Running the CI Scripts Locally + +On our CI, we test our changes on both iOS and Android, and we lint-check our code. +You can run the same scripts we run on our CI locally, to ensure your changes are passing the tests (under the project's root directory): + +```bash +npm run ci.ios +npm run ci.android +``` + +Refer to the scripts `scripts/ci.ios.sh` and `scripts/ci.android.sh` to see how we run the tests on our CI. + +[test app]: https://github.com/wix/Detox/tree/master/detox/test +[DetoxSync]: https://github.com/wix/DetoxSync +[`detox/test/e2e/detox.config.js`]: https://github.com/wix/Detox/blob/6e87dc13826341dba21ed0a732e5b57efa08e7b5/detox/test/e2e/detox.config.js#L137 +[ESLint]: https://eslint.org/ +[Jest]: https://jestjs.io/ +[`detox/package.json`]: https://github.com/wix/Detox/blob/master/detox/package.json +[`detox/test/package.json`]: https://github.com/wix/Detox/blob/master/detox/test/package.json diff --git a/website/versioned_docs/version-20.x/contributing/code/example-projects.md b/website/versioned_docs/version-20.x/contributing/code/example-projects.md new file mode 100644 index 0000000000..a023c6ee0a --- /dev/null +++ b/website/versioned_docs/version-20.x/contributing/code/example-projects.md @@ -0,0 +1,10 @@ +# Example Projects + +Explore various example projects hosted in this monorepo to understand real-world usage and testing with Detox. + +- `examples/demo-react-native-jest`: Demonstrates Detox usage in a React Native app project. +- `examples/demo-native-ios`: Illustrates Detox usage in a native (non-React Native) iOS app. +- `examples/demo-native-android` (broken): Illustrates Detox usage in a native (non-React Native) Android app. +- `examples/demo-pure-native-android`: Illustrates the subsidiary [Detox-Native](https://github.com/wix/Detox/blob/master/detox/detox-native/README.md) project. + +To run end-to-end tests associated with these projects, refer to the [project-specific](https://github.com/wix/Detox/tree/master/examples) READMEs. diff --git a/website/versioned_docs/version-20.x/contributing/code/overview.md b/website/versioned_docs/version-20.x/contributing/code/overview.md new file mode 100644 index 0000000000..62e9510940 --- /dev/null +++ b/website/versioned_docs/version-20.x/contributing/code/overview.md @@ -0,0 +1,50 @@ +--- +sidebar_label: Overview +--- + +# Code Changes Overview + +Welcome to the code changes section! As a contributor, it's essential to understand the project's goals and adhere to its code of conduct. Before contributing, please review any existing issues related to your work, ensure your code is well-documented, and has adequate test coverage. It's also important that your code is compatible with the project's supported platforms and their versions. + +Our collaborative workflow is simple: + +1. **Identify an Issue:** If not exists already, create an issue for new features or bug reports, outlining your proposal or the identified problem. +2. **Propose a Solution:** Open a pull request with a proposed solution to the issue. On complex issues, it's recommended to discuss your approach with the community and maintainers before submitting a PR. +3. **Engage in Review:** A collaborator will review your pull request. Reviews from other contributors are also encouraged. +4. **Merge and Release:** After the review, a collaborator will merge your contribution, typically releasing it in the next version of the project. + +We use [GitHub] for managing pull requests, conducting code reviews, and tracking issues. + +The code review process is central to our collaboration. Every contribution must go through a review before merging to maintain the quality of our codebase. As a contributor, being willing to discuss your work, respond to feedback, and work with the community is key to improving the project and creating a positive environment for all contributors. + +## Repository Structure + +Our GitHub repository is a monorepo, which means it contains multiple Detox-related projects and packages. + +The main package is the Detox framework, which is the core of the project. +It contains the native code for iOS and Android, as well as the JavaScript code. +The other projects are the Detox CLI, the Detox test app, example apps, and the Detox documentation website. + +Here's a high-level overview of the repository structure: + +- ๐Ÿ“ **detox-cli** - The CLI for Detox (e.g., `detox init`, `detox test`, read more about our [CLI docs]) +- ๐Ÿ“ **detox** - The Detox framework + - ๐Ÿ“ **android** - The Android native code, alongside native unit tests + - ๐Ÿ“ **ios** - The iOS native code, including its native submodules (e.g., DetoxSync) + - ๐Ÿ“ **test** - The Detox self-test app: A full-feature React Native app for end-to-end testing Detox itself + - ๐Ÿ“ **src** - The app's JavaScript code + - ๐Ÿ“ **e2e** - The Detox self-tests + - ๐Ÿ“ **integration** - Detox integration self-tests + - ๐Ÿ“ **local-cli** - Local CLI commands for Detox development (e.g., `detox rebuild-framework-cache`, which rebuilds the iOS framework) + - ๐Ÿ“ **runners** - The Detox runners, which are used to run the tests + - ๐Ÿ“ **scripts** - Scripts for building the framework for publishing + - ๐Ÿ“ **src** - The JavaScript source code of Detox. The include bundled JavaScript unit tests +- ๐Ÿ“ **website** - The documentation website of Detox (read more about our [documentation site docs]) +- ๐Ÿ“ **docs** - The documentation of Detox, written in Markdown and published on the website +- ๐Ÿ“ **examples** - Example apps for Detox (for more information, check the [list of example projects]) +- ๐Ÿ“ **scripts** - Scripts for building and testing Detox + +[GitHub]: https://github.com/wix/Detox +[documentation site docs]: ../documentation.md +[list of example projects]: ./example-projects.md +[CLI docs]: ../../cli/overview.md diff --git a/website/versioned_docs/version-20.x/contributing/code/reviewing-pull-requests.md b/website/versioned_docs/version-20.x/contributing/code/reviewing-pull-requests.md new file mode 100644 index 0000000000..bebaf0cad4 --- /dev/null +++ b/website/versioned_docs/version-20.x/contributing/code/reviewing-pull-requests.md @@ -0,0 +1,42 @@ +# Review a Pull Request + +Reviewing a PR is an important part of the contribution process. It ensures the quality of the codebase and provides an opportunity for the community to collaborate and learn from each other. + +:::note + +Reviewers should refer to the [Submitting Pull Requests] page to understand the guidelines the contributor followed when creating the PR. This will provide context and ensure a thorough review process. + +::: + +## Understand the Changes + +- Ensure alignment with the projectโ€™s coding standards and overall architecture. +- Read the provided description and any linked issues for context. + +## Provide Constructive Feedback + +Community members can provide valuable feedback on PRs, especially if they have experience with the feature or area of the codebase. + +- Be respectful and courteous. +- Offer code snippet suggestions if something could be done better. +- Request changes if necessary and provide clear, constructive feedback. + +## Review the Code + +Experienced developers are encouraged to review PRs and provide feedback. This is a great way to learn more about the project and collaborate with the community. + +You can review the code by following these requirements: + +- Alignment with coding standards and architectural guidelines. +- Adequate test coverage (unit, integration, and e2e). +- Ensure the documentation reflects the changes in the PR, if necessary. Refer to the [Documentation Changes] page for guidelines. +- Meaningful and semantically correct commit messages. + +## Merging Pull Requests + +Every PR requires approval from a maintainer before it can be merged. + +However, we encourage the community to review and provide feedback on PRs. Helping with the review process not only improves the quality of the code changes, but also helps the maintainers by reducing the workload. + +[Documentation Changes]: ../documentation.md +[Submitting Pull Requests]: ./submitting-pull-requests.md diff --git a/website/versioned_docs/version-20.x/contributing/code/setting-up-the-dev-environment.md b/website/versioned_docs/version-20.x/contributing/code/setting-up-the-dev-environment.md new file mode 100644 index 0000000000..6db7592904 --- /dev/null +++ b/website/versioned_docs/version-20.x/contributing/code/setting-up-the-dev-environment.md @@ -0,0 +1,65 @@ +# Setting up the Development Environment + +This document guides you through setting up your development environment to start contributing to our codebase. + +:::important Prerequisites + +Please complete our [Introductory environment setup](introduction/environment-setup.md) guide before proceeding. This ensures you have the necessary tools and dependencies installed in order to _run_ Detox tests, which is a fundamental step before being able to contribute to the project itself. + +::: + +## Setting Up The Monorepo Management + +Our repository is a monorepo, which means it contains multiple Detox-related projects and packages. [Read more about our repository structure](../code/overview.md#repository-structure). + +To set up the monorepo locally, follow these steps: + +Install the monorepo management tool, `lerna`: + +```bash npm2yarn +npm install lerna@3.x.x --global +``` + +Clone the repository and navigate to the project directory: + +```bash +git clone git@github.com:wix/Detox.git +cd detox +git submodule update --init --recursive +``` + +From the project's root directory, install and link the internal projects: + +```bash +lerna bootstrap +``` + +## Installing Common Dependencies + +### React-Native CLI + +[react-native-cli] is a command line interface for React Native. + +```bash npm2yarn +npm install react-native-cli --global +``` + +### Watchman + +[Watchman] is a tool by Facebook for watching changes in the filesystem. + +```bash +brew install watchman +``` + +### xcpretty + +[xcpretty] is a fast and flexible formatter for xcodebuild. + +```bash +gem install xcpretty +``` + +[react-native-cli]: https://www.npmjs.com/package/react-native-cli +[Watchman]: https://facebook.github.io/watchman/ +[xcpretty]: https://github.com/xcpretty/xcpretty diff --git a/website/versioned_docs/version-20.x/contributing/code/submitting-pull-requests.md b/website/versioned_docs/version-20.x/contributing/code/submitting-pull-requests.md new file mode 100644 index 0000000000..0a525d6ba2 --- /dev/null +++ b/website/versioned_docs/version-20.x/contributing/code/submitting-pull-requests.md @@ -0,0 +1,44 @@ +# Submitting Pull Requests + +:::note + +Before creating a PR, it's recommended to consult with the Detox collaborators. Request a design review or assistance with planning the tests to ensure alignment with project goals. + +Contact us on our [Discord Server] or open an [issue on GitHub]. + +::: + +## Fork the Repository + +- Fork the repository to your own GitHub account. +- Create a new branch from the `master` branch for your work. + +## Test Your Changes + +Being a testing framework, Detox is a highly self-tested project. Be sure to add/fix test coverage over your work, by running the various test flavors associated with your changes. You can review them, [here](./building-and-testing). + +## Modify Documentation + +If your changes affect the public API, update the documentation accordingly to reflect your changes. +Refer to the [Documentation Changes] page for guidelines. + +## Commit Message Guidelines + +Write descriptive, meaningful commit messages that follow the **Conventional Commits** format, specifying the type of change, the scope, and a concise description. For example: + +```plaintext +fix(ios): resolve crash on scrolling in iOS 17.0 +feat(android): add new API for setting the device locale +test: update unit tests for new utility function +``` + +More details on good commit messages can be found [here](https://www.conventionalcommits.org/en/v1.0.0/). + +## Open the Pull Request + +- Fill in the provided PR template fields on GitHub. +- Provide a clear description of your changes and any necessary context. + +[Documentation Changes]: ../documentation.md +[Discord Server]: https://discord.gg/CkD5QKheF5 +[issue on GitHub]: https://github.com/wix/Detox/issues/new/choose diff --git a/website/versioned_docs/version-20.x/contributing/documentation.md b/website/versioned_docs/version-20.x/contributing/documentation.md new file mode 100644 index 0000000000..2298660b6a --- /dev/null +++ b/website/versioned_docs/version-20.x/contributing/documentation.md @@ -0,0 +1,37 @@ +# Documentation Site + +Contributions towards enhancing our documentation are highly valued in the Detox community. +Clear, concise, and comprehensive documentation enables users to understand and utilize the project more effectively. + +We appreciate all contributions, from correcting typos to creating new documentation pages. + +## Getting Started + +Our [documentation website](https://wix.github.io/Detox) is developed using [Docusaurus](https://docusaurus.io/). To set up a local version of the website for editing, follow these steps: + +```bash npm2yarn +cd website +npm install +npm start +``` + +## Making Updates + +To modify an existing page, find the associated markdown file in the `docs/` directory and make the required changes. To introduce a new page, create a markdown file in `docs/` and link to it in `website/sidebars.json`. + +## Deploying Changes + +Automatic updates to the website occur with each commit to the `master` branch, with these changes reflected under the `Next` version. The process of tagging and locking documentation to a specific version is automated and coincides with each Detox release. + +If there's a need to update the documentation of a particular version, modify the associated files and code located under `website/versioned_docs/version-/` and `website/versioned_sidebars/version--sidebars.json`. + +## Modifying Old Versions + +To update an older version with the latest changes: + +1. Remove the desired version from `versions.json`. +1. Execute `npm run docusaurus docs:version `. + +## Reviewing Style Modifications + +If you're making changes to the stylesheets, use this [demo page](../demo.mdx) to visually inspect the impact of your changes and avoid unintentional visual regressions. diff --git a/website/versioned_docs/version-20.x/contributing/feature-requests.md b/website/versioned_docs/version-20.x/contributing/feature-requests.md new file mode 100644 index 0000000000..5f18010b4f --- /dev/null +++ b/website/versioned_docs/version-20.x/contributing/feature-requests.md @@ -0,0 +1,32 @@ +# Feedback and Suggestions + +Open dialogue and feedback, particularly feature requests, play an invaluable role in open-source communities like Detox. They provide insights into user preferences and requirements, aiding in the refinement and enhancement of the project. + +Detox project provides various platforms for feedback: [GitHub Issues], [Twitter], and [Discord]. + +Keep in mind that feedback is varied, including feature suggestions, improvements, identification of missing functionality, and support requests. Each type of feedback has a preferred method of submission. + +## Giving Feedback + +Follow these tips to deliver clear, actionable feedback: + +- **Constructive Criticism:** Frame your feedback in a positive light, understanding the perspective of the project maintainers. +- **Comprehensive Details:** Include as much relevant information as possible to help maintainers understand the context and use case. +- **Clarity and Respect:** Make your feedback specific, clear, and respectful, ensuring it is actionable for the maintainers. +- **Guidelines:** Adhere to the below suggestions for each type of feedback. + +## Suggesting Features + +When suggesting a new feature, remember to provide thorough information, such as examples, screenshots, and code snippets, to communicate your idea effectively. + +Just as in general feedback, make sure your feature request is: + +- **Specific:** Clearly describe the feature you wish to see implemented. +- **Detailed:** Offer as much context as possible, including use cases, examples, and why this addition would benefit the community. +- **Respectful:** Remember, the project maintainers or contributors are not obligated to implement your request. Be polite and respectful in your request. + +By making your feedback as clear and detailed as possible, you'll greatly assist the maintainers in understanding and potentially implementing your suggestion. + +[GitHub Issues]: https://github.com/wix/Detox/issues +[Twitter]: https://twitter.com/detoxe2e +[Discord]: https://discord.gg/CkD5QKheF5 diff --git a/website/versioned_docs/version-20.x/contributing/questions/answering-questions.md b/website/versioned_docs/version-20.x/contributing/questions/answering-questions.md new file mode 100644 index 0000000000..be4c7108ba --- /dev/null +++ b/website/versioned_docs/version-20.x/contributing/questions/answering-questions.md @@ -0,0 +1,26 @@ +# Answering Questions + +Contributing answers is an invaluable part of supporting the Detox community. By sharing your knowledge and experience, you help others learn and grow, and you also contribute to enhancing Detox for the entire community. + +## Different Ways to Answer + +Answering a question is not limited to providing a solution in the comments. +Sometimes, you may not have a solution, but you can still contribute by: + +- **Guide towards a solution**: If unsure about an answer, provide guidance on where to look, including relevant documentation or resources. +- **Request more information**: Ask for more detail if required to better address the question. For example, you may ask for code snippets, screenshots, or reproducible examples. +- **Refer to existing answers**: Link an already answered question if applicable. + +## Guidelines for Writing Clear Answers + +When answering questions, follow these guidelines to ensure your answers are clear and actionable: + +- **Be specific**: Try to pinpoint what exact information you need to effectively answer the question. General requests such as "Please share more details" are not very helpful. +- **Maintain respect**: Ensure your communication is always polite and contextual. When asking for more information, it's better to explain why it's needed so that the person asking understands the relevance. +- **Completeness**: Make sure to provide a detailed answer that includes all relevant information, such as code snippets, screenshots, and examples. This practice helps others understand your answer and apply it to their use case. + +:::tip In a Nutshell + +When you're answering a question, remember to be specific, clear, and respectful. By providing detailed and well-thought out response, you will play an important role in contributing to and enhancing the knowledge of our community. + +::: diff --git a/website/versioned_docs/version-20.x/contributing/questions/asking-questions.md b/website/versioned_docs/version-20.x/contributing/questions/asking-questions.md new file mode 100644 index 0000000000..24dd749f58 --- /dev/null +++ b/website/versioned_docs/version-20.x/contributing/questions/asking-questions.md @@ -0,0 +1,34 @@ +# Asking Questions + +Posting queries on public forums increases visibility and chances of getting an answer, and it also helps others with similar issues. However, it's essential to ask questions the right way to get the right answers. + +In case you were able to resolve your issue, consider sharing your solution with the community. By doing so, you contribute to enhancing Detox for the entire community. + +## Before Asking + +In case you're facing an issue, consider the following steps before posting a question: + +- **Suspect a bug?** Refer to our [Reporting Bugs] guide to determine if you've encountered a Detox bug and how to report it. +- **Search** for existing answers that may have addressed your question already. [Below](#where-to-ask), we've listed the right platforms to ask (and search) questions. +- Review our **documentation** thoroughly for any related information. Use document.querySelector('.DocSearch-Button').click()}>the search bar in the top right corner to streamline your search. + +If an existing answer doesn't fully address your question, feel free to ask a follow-up in the same thread if comment-enabled or create a new question, linking back to the original one if possible. + +## Where to Ask + +If you can't find an answer to your question, you can ask it in the following ways: + +- **Discord**: Join our dedicated [Discord server][Discord] to seek community assistance. +- **Stack Overflow**: Tag your question with ["Detox" on Stack Overflow] to reach the right audience. +- **GitHub**: Raise an issue on our [Detox repository]. + +:::tip Pro Tip + +When posting a question, ensure to include all relevant information, such as code snippets, screenshots, and examples. This practice helps others understand your query and provide comprehensive answers. + +::: + +[Reporting Bugs]: ../reporting-bugs.md +[Discord]: https://discord.gg/CkD5QKheF5 +[Detox repository]: https://github.com/wix/Detox/issues +["Detox" on Stack Overflow]: https://stackoverflow.com/questions/tagged/detox diff --git a/website/versioned_docs/version-20.x/contributing/reporting-bugs.md b/website/versioned_docs/version-20.x/contributing/reporting-bugs.md new file mode 100644 index 0000000000..b8e3ae7f7d --- /dev/null +++ b/website/versioned_docs/version-20.x/contributing/reporting-bugs.md @@ -0,0 +1,29 @@ +# Reporting Bugs + +Encountering a bug? Your detailed report is key for us to identify and rectify the issue. + +Before reporting a bug, please review the following guidelines. + +## Search for Existing Issues + +Before creating a new issue, search for [existing issues] to see if the bug has already been reported. +If you find an existing issue, add a comment to it with any additional information you have. + +## Create a Bug Report + +If you canโ€™t find an existing issue, create a new one. When creating a bug report, follow these guidelines: + +1. **Follow the Template:** While [creating a bug report on GitHub], adhere to the provided template for creating a clear and concise report. +2. **Reproduction Steps:** Providing a reproduction example is essential. +3. **Artifacts:** Include screenshots, logs, visibility artifacts, and any other relevant information. Be ready to provide more information upon request. +4. **Detailed Description:** Avoid creating issues with brief descriptions or general error messages. Providing a thorough description and context is vital. + +:::tip Tip + +Creating a minimal code reproduction is crucial as it helps other contributors and maintainers understand and investigate the issue better. +**Issues without a reproduction are less likely to be addressed**. + +::: + +[existing issues]: https://github.com/wix/Detox/issues +[creating a bug report on GitHub]: https://github.com/wix/Detox/issues/new/choose diff --git a/website/versioned_docs/version-20.x/guide/launch-args.md b/website/versioned_docs/version-20.x/guide/launch-args.md index 8c2416e8b5..a8e192c907 100644 --- a/website/versioned_docs/version-20.x/guide/launch-args.md +++ b/website/versioned_docs/version-20.x/guide/launch-args.md @@ -41,5 +41,5 @@ Examples: Our official recommendation for getting the arguments inside the app is by integrating the [react-native-launch-arguments](https://github.com/iamolegga/react-native-launch-arguments) project, which provides that seamlessly. For those who are interested, here are the underlying details: -- On iOS, the specified launch arguments are passed as the process launch arguments and available through normal means. +- On iOS, the specified launch arguments are passed as the process launch arguments and available through normal means, such as accesing `[[NSProcessInfo processInfo] arguments]`. - On Android, the launch arguments are set as bundle-extraโ€™s into the activityโ€™s intent. They are therefore accessible on the native side via the current activity as: `currentActivity.getIntent().getBundleExtra("launchArgs")`. diff --git a/website/versioned_docs/version-20.x/introduction/environment-setup.md b/website/versioned_docs/version-20.x/introduction/environment-setup.md new file mode 100644 index 0000000000..88039bb58d --- /dev/null +++ b/website/versioned_docs/version-20.x/introduction/environment-setup.md @@ -0,0 +1,83 @@ +# Environment Setup + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import IntroRN from './partials/_getting-started-rn.md'; +import IntroExpo from './partials/_getting-started-expo.md'; +import IntroOther from './partials/_getting-started-other.mdx'; + +The _Introduction section_ walks you through setting up Detox in your project, one step at a time. + +You will find that some steps are longer than the others: some are a couple of paragraphs, while the others look like a dedicated multistep guide. +Bear with us - it is all necessary, and once set up, it is easy to move forward with writing tests at a high pace. + +Please select type of your mobile application before you start the tutorial: + + + + + + + + + + + + + +## React Native CLI Quickstart + +Your first step would be to complete the +[๐Ÿ“š React Native CLI Quickstart Guide](https://reactnative.dev/docs/next/environment-setup). + +![RN Env](../img/rn-env.png) + +

+ Open the link above and switch there to React Native CLI Quickstart tab to see + the interactive tutorial for Development OS and Target OS of your choice. +

+ +

+ Follow all + the steps (yes, even if you have a native app!) and + make sure you can create and run React Native apps on virtual testing devices. +

+ +![RN Env Done](../img/rn-env-done.png) + +## Detox Prerequisites + +To complete the environment setup, you still have 2 steps ahead: installing `detox-cli` and `applesimutils`. + +### 1. Command Line Tools (`detox-cli`) + +`detox-cli` is merely a script that passes commands through to +a local Detox executable located at `node_modules/.bin/detox`, +making it easier to operate Detox from the command line, e.g. `detox test -c ios.sim.debug`. + +It should be installed globally, enabling usage of the command line tools outside your npm scripts: + +```bash npm2yarn +npm install detox-cli --global +``` + +On the other hand, if you are fine with running Detox commands with `npx detox ...`, you may skip installing `detox-cli`. + +### 2. [MacOS Only] `applesimutils` + +This tool is **required** by Detox to work with iOS simulators. The recommended way to install +[`applesimutils`](https://github.com/wix/AppleSimulatorUtils) is via [Homebrew](https://brew.sh): + +```bash +brew tap wix/brew +brew install applesimutils +``` + +:::info Note + +Make sure to periodically update your version of `applesimutils` to the latest version. + +::: + +Now, when your environment is ready, let's move to the next section, [Project Setup](project-setup.mdx). diff --git a/website/versioned_docs/version-20.x/introduction/getting-started.mdx b/website/versioned_docs/version-20.x/introduction/getting-started.mdx index 7f8d906004..263d3bc163 100644 --- a/website/versioned_docs/version-20.x/introduction/getting-started.mdx +++ b/website/versioned_docs/version-20.x/introduction/getting-started.mdx @@ -1,85 +1,65 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; +# Getting Started -import IntroRN from './partials/_getting-started-rn.md'; -import IntroExpo from './partials/_getting-started-expo.md'; -import IntroOther from './partials/_getting-started-other.mdx'; +## Before You Start -# Environment Setup +### Overview of Detox -**Welcome to Detox!** +Detox is an open-source end-to-end (E2E) testing framework for React Native mobile applications. +Our main goal is to enable the testing of any end-to-end flow in the app, with maximum velocity and zero flakiness. +Detox tests your mobile app while it's running on a real device or simulator, simulating a real user's interactions. -The _Introduction section_ walks you through setting up Detox in your project, one step at a time. +![Detox overview](../img/Detox.gif) -You will find that some steps are longer than the others: some are a couple of paragraphs, while the others look like a dedicated multistep guide. -Bear with us - it is all necessary, and once set up, it is easy to move forward with writing tests at a high pace. +### What Does a Detox Test Look Like? -Please select type of your mobile application before you start the tutorial: +This is a test for a login screen, it runs on a device or simulator like an actual user: - - - - - - - - - - - +```js +describe('Login flow', () => { + beforeEach(async () => { + await device.reloadReactNative(); + }); -## React Native CLI Quickstart + it('should login successfully', async () => { + await element(by.id('email')).typeText('john@example.com'); + await element(by.id('password')).typeText('123456'); -Your first step would be to complete the -[๐Ÿ“š React Native CLI Quickstart Guide](https://reactnative.dev/docs/next/environment-setup). + const loginButton = element(by.text('Login')); + await loginButton.tap(); -![](../img/rn-env.png) - -

- Open the link above and switch there to React Native CLI Quickstart tab to see - the interactive tutorial for Development OS and Target OS of your choice. -

- -

- Follow all - the steps (yes, even if you have a native app!) and - make sure you can create and run React Native apps on virtual testing devices. -

- -![](../img/rn-env-done.png) - -## Detox Prerequisites - -To complete the environment setup, you still have 2 steps ahead: installing `detox-cli` and `applesimutils`. - -### 1. Command Line Tools (`detox-cli`) + await expect(loginButton).not.toExist(); + await expect(element(by.label('Welcome'))).toBeVisible(); + }); +}); +``` -`detox-cli` is merely a script that passes commands through to -a local Detox executable located at `node_modules/.bin/detox`, -making it easier to operate Detox from the command line, e.g. `detox test -c ios.sim.debug`. +### Gray box testing -It should be installed globally, enabling usage of the command line tools outside your npm scripts: +One of the most challenging aspects of automated testing on mobile is end-to-end testing. +UI testing frameworks are often not fully-deterministic, since they are built with a "black box" approach, where the test runner has no access to the internals of the app under test, and is unaware of asynchronous operations that take place in the app (such as network requests, animations, etc.). +This makes it difficult to write reliable E2E tests, and often leads to flaky tests that are hard to debug and maintain. -```bash npm2yarn -npm install detox-cli --global -``` +To address this issue, Detox adopts a "gray box" testing approach, by having access to the internals of the app under test. +This allows for more control and predictability in the testing process. For more information, you can read [how Detox works]. -On the other hand, if you are fine with running Detox commands with `npx detox ...`, you may skip installing `detox-cli`. +## Start with Detox -### 2. [MacOS Only] `applesimutils` +### Follow the Setup Guides -This tool is **required** by Detox to work with iOS simulators. The recommended way to install -[`applesimutils`](https://github.com/wix/AppleSimulatorUtils) is via [Homebrew](https://brew.sh): +The following guides in this Introduction section will help you get started with Detox, one step at a time, from setting up your environment to writing and running your first test. -```bash -brew tap wix/brew -brew install applesimutils -``` +### Join the Community ๐Ÿค -:::info Note +As an open-source project, Detox encourages and welcomes contributions from the community. +Whether you're a developer, tester, or just someone who is passionate about making mobile development better, there's a place for you in the Detox community. +By contributing to Detox, you'll be helping to improve the reliability and user experience of mobile apps, and you'll be part of a team that is dedicated to making mobile development faster and more efficient. +We welcome all types of contributions, from code and documentation, to bug reports, questions and feature requests. -Make sure to periodically update your version of `applesimutils` to the latest version. +So, if you're interested to be part of the community, we encourage you to get involved by reading our [contributing guidelines], and join our [Discord server]. +We also have a [Twitter account] where we share updates about the project. -::: -Now, when your environment is ready, let's move to the next section, [Project Setup](project-setup.mdx). +[how Detox works]: ../articles/how-detox-works.md +[contributing guidelines]: contributing.md +[Discord server]: https://discord.gg/CkD5QKheF5 +[Twitter account]: https://twitter.com/detoxe2e diff --git a/website/versioned_sidebars/version-20.x-sidebars.json b/website/versioned_sidebars/version-20.x-sidebars.json index dccd8da976..37024477cb 100644 --- a/website/versioned_sidebars/version-20.x-sidebars.json +++ b/website/versioned_sidebars/version-20.x-sidebars.json @@ -5,6 +5,7 @@ "label": "Introduction", "items": [ "introduction/getting-started", + "introduction/environment-setup", "introduction/project-setup", "introduction/your-first-test", "introduction/debugging", @@ -46,11 +47,6 @@ { "type": "doc", "id": "guide/migration" - }, - { - "type": "doc", - "label": "Contributing", - "id": "contributing" } ], "apiSidebar": [ @@ -107,5 +103,32 @@ "articles/third-party-drivers" ] } + ], + "contributeSidebar": [ + "contributing", + { + "type": "category", + "label": "Questions & Answers", + "items": [ + "contributing/questions/asking-questions", + "contributing/questions/answering-questions" + ] + }, + "contributing/reporting-bugs", + "contributing/feature-requests", + { + "type": "category", + "label": "Code Changes", + "items": [ + "contributing/code/overview", + "contributing/code/setting-up-the-dev-environment", + "contributing/code/building-and-testing", + "contributing/code/example-projects", + "contributing/code/submitting-pull-requests", + "contributing/code/reviewing-pull-requests" + ] + }, + "contributing/documentation", + "contributing/code-of-conduct" ] }