Be able to manually start and stop proxy

README.md

@@ -1,14 +1,14 @@
 # appium-interceptor-plugin
 
 This is an Appium plugin designed to intercept API response and mocking easy.
-This plugin uses mitmproxy
+This plugin uses `mitmproxy`.
 
 ## Prerequisite
 
 1. Appium version 3.0
 2. Intercepting API requests from android requires CA certificate to be installed on the device. Follow the instructions in [How to install CA certificate on android](./docs/certificate-installation.md) section and install the CA certificate.
 
-## Installation - Server
+## Installation - server
 
 Install the plugin using Appium's plugin CLI, either as a named plugin or via NPM:
 
@@ -22,20 +22,79 @@ The plugin will not be active unless turned on when invoking the Appium server:
 
 `appium server -ka 800 --use-plugins=appium-interceptor -pa /wd/hub`
 
-## Custom certificate
+## What does this plugin do?
+
+The **Appium Interceptor Plugin** provides network interception and mocking capabilities specifically for **Android** devices. It manages a local proxy server and automatically configures the device's WiFi settings to route all network traffic through it.
+
+By using this plugin, you can intercept, record, and mock HTTP requests directly within your Appium tests without manually configuring certificates or proxy settings on the device.
+
+## Configuration
+
+### Server Arguments
+
+Custom certificate
 
 If you need to use a custom certificate, it can be done by passing `certdirectory` as an argument of the plugin:
 
-`appium server -ka 800 --use-plugins=appium-interceptor --plugin-appium-interceptor-certdirectory="<YOUR DIRECTORY>" -pa /wd/hub`
+`appium server -ka 800 --use-plugins=appium-interceptor --plugin-appium-interceptor-certdirectory="<path_to_cert_directory>" -pa /wd/hub`
 
 Please keep the same directory structure as the existing certificate folder.
 
-## what does this plugin do?
+### Capabilities
+
+To control the plugin behavior, you can use the following capabilities:
 
-For every appium session, interceptor plugin will start a proxy server and updates the device proxy settings to pass all network traffic to proxy server. Mocking is disabled by default and can be enabled from the test by passing `appium:intercept : true` in the desired capability while creating a new appium session.
+| Capability                       | Type      | Default | Description                                                                                                              |
+| :------------------------------- | :-------- | :------ | :----------------------------------------------------------------------------------------------------------------------- |
+| `appium:startProxyAutomatically` | `boolean` | `false` | When `true`, the plugin initializes the proxy server and configures the device WiFi immediately during session creation. |
+
+---
+
+## Usages
+
+### 1. Automatic lifecycle management
+
+Set `appium:startProxyAutomatically` to `true` in your capabilities. The plugin will handle the proxy **setup** during session creation and the proxy **cleanup** (reverting WiFi settings and closing the server) when the session ends.
+
+```javascript
+// Example with WebdriverIO
+const caps = {
+  "platformName": "Android",
+  "appium:automationName": "UiAutomator2",
+  "appium:startProxyAutomatically": true
+};
+```
+
+### 2. Manual management
+
+If you want to control exactly when the proxy starts (e.g., only for specific test cases), leave the capability at `false` and use the following commands within your test scripts:
+
+* **Start Proxy**: `driver.execute('interceptor: startProxy')`
+* **Stop Proxy**: `driver.execute('interceptor: stopProxy')`
+
+> **Pro tip for troubleshooting**: These commands can be useful for **on-the-fly recovery** during a test session. If you encounter a network glitch or a proxy timeout, you can manually call `stopProxy` followed by `startProxy` to perform a "clean restart" without terminating your entire Appium session.
+
+> **Note**: Even in manual mode, the plugin **automatically handles the cleanup** when the session ends. 
+> Unlike a simple deactivation, the plugin **restores your previous device settings** (such as your original global proxy configuration) instead of just wiping them. This ensures your device returns exactly to the state it was in before the test started.
+
+## Usable commands
 
 Please refer to the [commands](/docs/commands.md) sections for detailed usage.
 
+
+## Logging & debugging
+
+The plugin integrates with the standard Appium logging system. For deep troubleshooting, set the server log level to `debug`:
+
+```json
+{
+  "server": {
+    "log-level": "debug:debug"
+  }
+}
+```
+
+
 ## Supported Platforms
 
 💚 `Android`

docs/commands.md

@@ -1,6 +1,12 @@
 ## Appium interceptor commands
 
-Create the appium session by passing `appium:intercept : true` option in the desired capability. Once the session is successfully created, tests can manage the api mocking using below commands. 
+To enable network interception, configure your Appium session using the `appium:startProxyAutomatically` capability. Depending on your configuration, you can manage the proxy and mocking as follows:
+
+🔸 ***Automatic Mode***: Set `appium:startProxyAutomatically` to `true` in your desired capabilities. The plugin will immediately initialize the proxy and configure the device upon session start.
+
+🔸 ***Manual Mode***: If the capability is set to false (default), you must explicitly trigger the proxy initialization using the `startProxy` command during your test.
+
+👉 Once the proxy is successfully started (either automatically or manually), you can manage API mocking, recording, and sniffing using the commands detailed below.
 
 To route emulator traffic through another proxy, set one of the environment variables UPSTREAM_PROXY, HTTPS_PROXY, or HTTP_PROXY. All traffic from the emulator will then be forwarded to the specified upstream proxy.
 
@@ -38,16 +44,34 @@ Mock configuration is a json object that defines the specification for filtering
 
 ## Commands:
 
-### interceptor: addMock
+### interceptor: startProxy / stopProxy
 
-Add a new mock specification for intercepting and updating the request. The command will returns a unique id for each mock which can be used in future to delete the mock at any point in the test.
+These commands allow you to manually manage the proxy lifecycle during a test session. This is the preferred method when `appium:startProxyAutomatically` is set to `false`, or if you need to reset the network configuration on-the-fly.
 
-#### Example:
+> ***Note:*** Even when using these manual commands, the plugin provides **smart cleanup**: it will automatically stop the proxy and restore your previous device settings when the session ends or crashes.
 
+#### Example:
 
 ***Note:*** Below example uses wedriver.io javascript client. For Java client you need to use `((JavascriptExecutor) driver).executeScript()` for executing commands instead of `driver.execute()`
 
+```javascript
+// Manually starting the proxy
+await driver.execute("interceptor: startProxy");
+
+// ... perform your intercepted tests ...
 
+// Manually stopping the proxy
+// This will revert your device WiFi settings to their original state
+await driver.execute("interceptor: stopProxy");
+```
+
+### interceptor: addMock
+
+Add a new mock specification for intercepting and updating the request. The command will returns a unique id for each mock which can be used in future to delete the mock at any point in the test.
+
+#### Example:
+
+***Note:*** Below example uses wedriver.io javascript client. For Java client you need to use `((JavascriptExecutor) driver).executeScript()` for executing commands instead of `driver.execute()`
 
 ```javascript
  const authorizationMock = await driver.execute("interceptor: addMock", {