Publish docs version 20.x

website/versioned_docs/version-20.x/api/copilot.md

@@ -0,0 +1,97 @@
+# Detox Copilot
+
+Detox Copilot is an AI-powered plugin that allows you to write Detox tests using natural language commands, powered by large language models (LLMs). It simplifies the process of writing end-to-end tests by translating human-readable instructions into Detox actions and assertions.
+
+:::note
+
+Detox Copilot is based on a core library called [detox-copilot](https://github.com/wix-incubator/detox-copilot), which is designed for Detox but can be extended to work with other testing frameworks.
+
+:::
+
+:::caution Work in Progress
+
+Detox Copilot is in active development, and APIs are subject to change in future releases.
+
+:::
+
+## Overview
+
+Detox Copilot exposes a simple API that integrates seamlessly with your Detox tests. It requires minimal setup and allows you to perform complex testing operations by simply describing them in natural language.
+
+For a more detailed guide on integrating Detox Copilot in your tests, refer to the [Detox Copilot Guide].
+
+## Methods
+
+- [`copilot.init()`](#copilotinitprompthandler)
+- [`copilot.perform()`](#copilotperformsteps)
+
+## `copilot.init(promptHandler)`
+
+Initializes Detox Copilot with the given prompt handler. Must be called before any other Copilot methods.
+
+**Parameters:**
+
+- `promptHandler` (PromptHandler): An object implementing the [`PromptHandler`](#prompthandler-interface) interface.
+
+**Example:**
+
+```javascript
+const { copilot } = require('detox');
+const OpenAIPromptHandler = require('./OpenAIPromptHandler');
+
+beforeAll(() => {
+  const promptHandler = new OpenAIPromptHandler('YOUR_OPENAI_API_KEY');
+  copilot.init(promptHandler);
+});
+```
+
+## `copilot.perform(...steps)`
+
+Performs a testing operation or series of operations based on the given steps.
+
+**Parameters:**
+
+- `steps` (string[]): One or more natural language instructions specifying the actions or assertions to perform.
+
+**Returns:**
+
+- A promise that resolves when all steps have been executed.
+
+**Example:**
+
+```javascript
+await copilot.perform(
+  'Start the application',
+  'Tap on the "Login" button',
+  'Enter "[email protected]" into the email field',
+  'Enter "password123" into the password field',
+  'Press the "Submit" button',
+  'The welcome message "Hello, User!" should be displayed'
+);
+```
+
+## `PromptHandler` Interface
+
+The `PromptHandler` interface defines how Detox Copilot communicates with the LLM service.
+
+```typescript
+interface PromptHandler {
+  /**
+   * Sends a prompt to the LLM service and returns the response.
+   * @param prompt The prompt to send.
+   * @param image Optional path to an image capturing the current UI state.
+   * @returns A promise resolving to the LLM's response.
+   */
+  runPrompt(prompt: string, image?: string): Promise<string>;
+
+  /**
+   * Indicates whether the LLM service supports snapshot images.
+   * @returns A boolean value.
+   */
+  isSnapshotImageSupported(): boolean;
+}
+```
+
+You can refer to the [Detox Copilot Guide] for an example of implementing a `PromptHandler` for OpenAI's service.
+
+[Detox Copilot Guide]: ../copilot/testing-with-copilot.md

website/versioned_docs/version-20.x/contributing/code/overview.md

@@ -28,7 +28,6 @@ The other projects are the Detox CLI, the Detox test app, example apps, and the
 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-copilot** - Detox plugin that leverages large language models (LLM) to seamlessly invoke Detox actions (**work in progress**)
 - 📁 **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)

website/versioned_docs/version-20.x/copilot/best-practices.md

@@ -0,0 +1,69 @@
+# Detox Copilot Best Practices
+
+Detox Copilot allows you to write tests using natural language commands. Each step corresponds to a specific action or assertion within your app. In case you're wondering how to make the most out of this feature, here are some best practices to follow when writing your Copilot intents.
+
+## Step-by-Step Instructions
+
+- **Write Sequential Steps**: Describe your test steps in a clear and sequential manner.
+- **Example**:
+
+```javascript
+it('should navigate and add a product to the cart', async () => {
+  await copilot.perform(
+    'Navigate to the "Products" page',
+    'Tap on the "Add to Cart" button for the first product',
+    'Verify that the "Added to Cart" pop-up is displayed'
+  );
+});
+```
+
+## Be Specific and Clear
+
+- **Provide Clear Instructions**: The clearer your instructions, the better Copilot can interpret them.
+- **Example**:
+  - **Good**: `'Tap on the "Login" button'`
+  - **Better**: `'Tap on the "Login" button located at the top right corner'`
+
+## One Action per Step
+
+- **Avoid Combining Multiple Actions**: Keep each step focused on a single action or assertion.
+- **Example**:
+  - **Avoid**: `'Tap on the "Login" button and enter credentials'`
+  - **Prefer**:
+
+  ```javascript
+  'Tap on the "Login" button',
+  'Enter "[email protected]" into the "Email" field'
+  ```
+
+## Use Exact Labels
+
+- **Refer to UI Elements Precisely**: Use the exact text or identifiers as they appear in the app.
+- **Example**:
+  - **Good**: `'Enter "password123" into the "Password" field'`
+  - **Avoid**: `'Enter password into its field'`
+
+## Keep Assertions Simple
+
+- **Focus on Specific Outcomes**: Make assertions straightforward and specific.
+- **Example**:
+  - **Good**: `'Verify that the "Welcome" message is displayed'`
+  - **Avoid**: `'Check if the welcome message appears correctly on the screen'`
+
+## Leverage Visual Context
+
+- **Utilize Visual Descriptions**: If your LLM supports image snapshots, include visual context in your intents.
+- **Example**: `'Ensure the profile picture is visible at the top of the screen'`
+
+## Avoid Ambiguity
+
+- **Specify Elements Precisely**: If multiple elements could match, provide additional details.
+- **Example**:
+  - **Ambiguous**: `'Tap on the "Submit" button'`
+  - **Specific**: `'Tap on the "Submit" button in the registration form'`
+
+## General Recommendations
+
+- **Flexibility**: While it's best to provide clear instructions, Copilot is designed to interpret a variety of phrasing. Different approaches can work, and you are encouraged to experiment.
+- **Feedback Loop**: Observe how Copilot interprets your instructions and adjust accordingly.
+- **Model Selection**: Choose an LLM model that best suits your application's complexity and language requirements. We recommend advanced models like **Sonnet 3.5** or **GPT-4o** for better performance.

website/versioned_docs/version-20.x/copilot/technical-overview.mdx

@@ -0,0 +1,44 @@
+import OverviewSVG from '../img/copilot/copilot-overview.svg';
+
+# Technical Overview
+
+Detox Copilot integrates seamlessly with your testing environment by combining natural language processing with Detox's robust testing capabilities.
+
+## Building Blocks of Detox Copilot
+
+To enable Detox Copilot to work harmoniously with Detox and your app, it relies on several building blocks:
+
+- **Dynamic Code Generation**: Copilot generates Detox code on-the-fly to perform actions or assertions based on your instructions.
+- **Visual Analysis**: Copilot can analyze the app's screen to verify the presence of specific elements or text, enabling assertions beyond standard UI checks.
+- **App View Hierarchy**: Detox generates an XML representation of the app's view hierarchy, helping Copilot interact with all UI elements, even those not directly visible.
+- **Snapshot Images**: Optional snapshot images provide Copilot with visual context for more precise understanding and analysis.
+- **Injected Test IDs**: When necessary, Detox injects unique test IDs to ensure reliable access to UI elements.
+- **Caching Mechanism**: Copilot caches execution results to optimize performance and reduce unnecessary LLM calls (see [Performance Optimization](#performance-optimization)).
+- **Test Context Awareness**: Copilot maintains awareness of previously executed steps, ensuring continuity and readability in the test flow.
+
+## Copilot's Execution Flow
+
+<OverviewSVG
+  style={{
+    backgroundColor: '#f5f5f5',
+    borderRadius: '10px'
+  }}
+/>
+
+The execution flow of Detox Copilot can be broken down into six main steps:
+
+1. **Gather Context**: Collect relevant app state, view hierarchy, and previous step results.
+2. **Interpret Intent**: Use the LLM to interpret the natural language instruction.
+3. **Generate Code**: Create the appropriate Detox commands.
+4. **Execute Action**: Run the generated Detox code.
+5. **Cache Results**: Store execution results to optimize future runs.
+6. **Provide Feedback**: Return values or confirm actions for subsequent steps.
+
+By combining these steps, Detox Copilot effectively bridges the gap between natural language instructions and concrete test actions.
+
+### Performance Optimization
+
+Detox Copilot is designed to avoid unnecessary calls to the LLM service and optimize performance using static cache that is based on the current state of the app.
+This minimizes the number of calls to the LLM service and reduces latency.
+However, you can optimize your `PromptHandler` implementation to reduce latency and improve response times (e.g., by reducing the image size or implementing a server-side cache).
+We have plans to optimize even further by introducing more advanced caching mechanisms for better performance.