From 909dfc4ad3cb47111cf71bf63ff61ee6695e2604 Mon Sep 17 00:00:00 2001 From: wixmobile Date: Wed, 22 May 2024 13:28:47 +0000 Subject: [PATCH] Publish docs version 20.x --- .../versioned_docs/version-20.x/api/system.md | 89 +++++++++++++++++++ .../version-20.x/cli/build-framework-cache.md | 26 ++++-- .../version-20.x/cli/clean-framework-cache.md | 11 ++- .../version-20.x/cli/overview.md | 22 ++--- .../cli/rebuild-framework-cache.md | 12 ++- .../contributing/code/building-and-testing.md | 4 +- .../version-20.x-sidebars.json | 1 + 7 files changed, 143 insertions(+), 22 deletions(-) create mode 100644 website/versioned_docs/version-20.x/api/system.md diff --git a/website/versioned_docs/version-20.x/api/system.md b/website/versioned_docs/version-20.x/api/system.md new file mode 100644 index 0000000000..c1a6c9829b --- /dev/null +++ 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 index e8948476dc..a9020b8dd9 100644 --- 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 index 3ac77aca3b..88bf53bbb7 100644 --- 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 index 89f0a60bf6..0f7a4bd6c2 100644 --- 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 [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 index b13032e99d..2ab059e749 100644 --- 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 index 222f5a5604..d354bb12d5 100644 --- 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 index 6777e9c71e..93f891b5c1 100644 --- 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" ] },