Publish docs version 20.x

wix · May 22, 2024 · 909dfc4 · 909dfc4
1 parent 2943ff0
commit 909dfc4
Show file tree

Hide file tree

Showing 7 changed files with 143 additions and 22 deletions.
diff --git a/website/versioned_docs/version-20.x/api/system.md b/website/versioned_docs/version-20.x/api/system.md
@@ -0,0 +1,89 @@
+# System
+
+System APIs allows you to interact with dialogs in the system-level (e.g. permissions, alerts, etc.).
+
+:::caution Experimental
+
+System APIs are currently in an experimental phase.
+This means that the API is not yet final and **may change over minor releases.**
+
+:::
+
+:::note
+
+**System APIs are only available on iOS**. Android support is coming soon.
+
+At the moment, System APIs are limited to system dialogs (e.g. permissions, alerts, etc.).
+We plan to expand the System APIs to include more system-level interactions in the future,
+such as OS browser (Safari / Chrome), interactions with push notifications, photo library, etc.
+
+:::
+
+## Matchers
+
+System matchers are used to find elements within the system:
+
+- [`by.system.label(label)`]
+- [`by.system.type(type)`]
+
+### `by.system.label(label)`
+
+Match elements with the specified label.
+
+```js
+system.element(by.system.label('Dismiss'));
+```
+
+### `by.system.type(type)`
+
+Match elements with the specified type.
+
+The type value can be any of [`XCUIElement.ElementType`][iOS element-type] values, such as `'button'` or `'textField'`.
+
+```js
+system.element(by.system.type('button'));
+```
+
+## Actions
+
+System actions are used to interact with elements within the system:
+
+- [`tap()`]
+
+### `tap()`
+
+Tap on the element.
+
+```js
+system.element(by.system.label('Allow')).tap();
+```
+
+## Expectations
+
+System expectations are used to assert the state of elements within the system:
+
+- [`toExist()`]
+- [`not`]
+
+### `toExist()`
+
+Asserts that the element exists.
+
+```js
+await system.element(by.system.label('Allow')).toExist();
+```
+
+### `not`
+
+Negates the expectation.
+
+```js
+await system.element(by.system.label('Allow')).not.toExist();
+```
+
+[`by.system.label(label)`]: #bysystemlabellabel
+[`by.system.type(type)`]: #bysystemtypetype
+[`tap()`]: #tap
+[`toExist()`]: #toexist
+[`not`]: #not
+[iOS element-type]: https://developer.apple.com/documentation/xctest/xcuielement/elementtype
diff --git a/website/versioned_docs/version-20.x/cli/build-framework-cache.md b/website/versioned_docs/version-20.x/cli/build-framework-cache.md
@@ -4,15 +4,29 @@
 detox build-framework-cache
 ```
 
-**MacOS only.** Builds a cached version of `Detox.framework` in `~/Library/Detox/ios/*`.
+**MacOS only.**
+Builds cached versions of the Detox framework and XCUITest-runner.
+This command uses the `--detox` and `--xcuitest` flags to selectively build components. By default, both components are built.
 
-Detox stores a cached version of its framework in `~/Library/Detox/ios/*` in unique folders, where the folder name
-is a hash of Xcode and Detox version:
+## Options
+
+- `--detox` - Builds **only** the Detox injected framework. Default is false (build both).
+- `--xcuitest` - Builds **only** the XCUITest runner. Default is false (build both).
+
+Detox stores a cached version of its framework and XCUITest-runner in `~/Library/Detox/ios/*` in unique folders, where the folder name
+is a hash of Xcode and Detox version combination. This cache is used to speed up the build process and avoid unnecessary recompilations.
+
+Here is an example of the cache structure:
 
 ```plain text
 ├── ios
-│   ├── 197a0586bd006583562a5916c969d158133a8c50
-│   ├── …
-│   └── eddcc1edeffdb3533a977b73b667e1b7f106c38f
+│  ├── framework
+│  │   ├── 197a0586bd006583562a5916c969d158133a8c50
+│  │   ├── …
+│  │   └── eddcc1edeffdb3533a977b73b667e1b7f106c38f
+│  ├── xcuitest-runner
+|  │   ├── 197a0586bd006583562a5916c969d158133a8c50
+│  │   ├── …
+│  │   └── eddcc1edeffdb3533a977b73b667e1b7f106c38f
 │…
 ```
diff --git a/website/versioned_docs/version-20.x/cli/clean-framework-cache.md b/website/versioned_docs/version-20.x/cli/clean-framework-cache.md
@@ -4,4 +4,13 @@
 detox clean-framework-cache
 ```
 
-**MacOS only.** Cleans cached versions of `Detox.framework` in `~/Library/Detox/ios/*`.
+**MacOS only.**
+Cleans cached versions of the Detox framework and XCUITest-runner.
+This command uses the `--detox` and `--xcuitest` flags to selectively remove components. By default, both components are cleaned.
+
+## Options
+
+- `--detox` - Cleans **only** the Detox injected framework. Default is false (clean both).
+- `--xcuitest` - Cleans **only** the XCUITest runner. Default is false (clean both).
+
+See also: [`detox build-framework-cache`](build-framework-cache.md)
diff --git a/website/versioned_docs/version-20.x/cli/overview.md b/website/versioned_docs/version-20.x/cli/overview.md
@@ -18,17 +18,17 @@ detox <command> [options]
 
 ## Commands
 
-| Command                   | Description                                                                                                                                                  |
-| ------------------------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [init]                    | Create initial E2E tests folder for Detox.                                                                                                                   |
-| [build]                   | Run the command defined in 'build' property of the specified configuration.                                                                                  |
-| [test]                    | Initiating your test suite.                                                                                                                                  |
-| [recorder]                | Starts a [Detox Recorder](https://github.com/wix/DetoxRecorder) recording.                                                                                   |
-| [build-framework-cache]   | **MacOS only.** Builds Detox.framework to \~/Library/Detox. The framework cache is specific for each combination of Xcode and Detox versions.                |
-| [clean-framework-cache]   | **MacOS only.** Deletes all compiled framework binaries from \~/Library/Detox, they will be rebuilt on 'npm install' or when running 'build-framework-cache'. |
-| [rebuild-framework-cache] | **MacOS only.** Rebuilds the Detox cache.                                                                                                                    |
-| [reset-lock-file]         | Resets Detox lock file completely - all devices are marked as available after that.                                                                          |
-| [run-server]              | Starts a standalone Detox server.                                                                                                                            |
+| Command                   | Description                                                                                                                                                                       |
+| ------------------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [init]                    | Create initial E2E tests folder for Detox.                                                                                                                                        |
+| [build]                   | Run the command defined in 'build' property of the specified configuration.                                                                                                       |
+| [test]                    | Initiating your test suite.                                                                                                                                                       |
+| [recorder]                | Starts a [Detox Recorder](https://github.com/wix/DetoxRecorder) recording.                                                                                                        |
+| [build-framework-cache]   | **MacOS only.** Builds or rebuilds a cached Detox framework and/or XCUITest-runner in ~/Library/Detox. The cache is specific for each combination of Xcode and Detox versions.    |
+| [clean-framework-cache]   | **MacOS only.** Deletes all compiled framework and XCUITest-runner binaries from \~/Library/Detox, they will be rebuilt on 'npm install' or when running 'build-framework-cache'. |
+| [rebuild-framework-cache] | **MacOS only.** Cleans and builds a cached Detox framework and XCUITest-runner in \~/Library/Detox. The cache is specific for each combination of Xcode and Detox versions.       |
+| [reset-lock-file]         | Resets Detox lock file completely - all devices are marked as available after that.                                                                                               |
+| [run-server]              | Starts a standalone Detox server.                                                                                                                                                 |
 
 ## Options
 

diff --git a/website/versioned_docs/version-20.x/cli/rebuild-framework-cache.md b/website/versioned_docs/version-20.x/cli/rebuild-framework-cache.md
@@ -4,7 +4,13 @@
 detox rebuild-framework-cache
 ```
 
-**MacOS only.** This command is a shortcut for calling sequentially:
+**MacOS only.**
+Rebuilds cached versions of the Detox framework and XCUITest-runner.
+This command uses the `--detox` and `--xcuitest` flags to selectively rebuild components. By default, both components are rebuilt.
 
-1. [`detox clean-framework-cache`](clean-framework-cache.md)
-1. [`detox build-framework-cache`](build-framework-cache.md)
+## Options
+
+- `--detox` - Rebuilds **only** the Detox injected framework. Default is false (rebuild both).
+- `--xcuitest` - Rebuilds **only** the XCUITest runner. Default is false (rebuild both).
+
+See also: [`detox build-framework-cache`](build-framework-cache.md)
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
@@ -40,7 +40,9 @@ 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
+## iOS: Rebuilding the Native Code
+
+### Detox Framework
 
 After changing the native code of Detox iOS, you need to rebuild the Detox framework. This is done when running:
 

diff --git a/website/versioned_sidebars/version-20.x-sidebars.json b/website/versioned_sidebars/version-20.x-sidebars.json
@@ -91,6 +91,7 @@
         "api/actions",
         "api/expect",
         "api/webviews",
+        "api/system",
         "api/logger"
       ]
     },