Describe the driver purpose and configuration (VirtusLab#9)

Describe driver purpose and configuration

README.md

@@ -1 +1,18 @@
-By using `ide-probe` you implicitly accept the terms of the Jetbrains Privacy Policy.
+By using this library you implicitly accept the terms of the Jetbrains Privacy Policy.
+
+#### Description
+
+Ide Probe is a framework for testing IntelliJ platform plugins. It can be used both locally and in the CI pipeline. 
+
+The framework itself comprises two components: 
+- driver - responsible for controlling the workspace and IDE startup
+- probe - used to interact with the IDE  
+
+
+#### Configuration
+
+1. [Driver](docs/driver.md)
+2. [Resolvers](docs/custom-resolvers.md)
+3. [Workspace](docs/workspace.md)
+4. [Display](docs/display.md)
+5. [Debugging](docs/debug.md)

docs/custom-resolvers.md

@@ -0,0 +1,28 @@
+#### Custom resolvers
+Ide Probe can download its dependencies from custom repositories. 
+If none of those is specified, official ones will be used.   
+
+##### IntelliJ resolver
+```
+probe.resolvers {
+  intellij.repository {
+    uri = "https://www.jetbrains.com/intellij-repository/snapshots"
+    group = "com.jetbrains.intellij.idea"
+    artifact = "ideaIC"
+  }
+  plugins.repository {
+    uri = "https://plugins.jetbrains.com/plugin/download"
+  }
+}
+```
+
+Ide probe can fetch Intellij from a maven repository or use a custom plugin repository.
+
+##### Resource cache
+```
+probe.resolvers {
+  resourceProvider.cacheDir = "/tmp/ideprobe/cache"
+}
+```
+
+All resources not present on the local machine will be cached in the 'cacheDir' directory.

docs/debug.md

@@ -0,0 +1,8 @@
+### Debug mode
+To debug the probe, set up the `IDEPROBE_DEBUG=true` environment variable.
+
+#### Port 
+By default, user can connect on the `5005` port. To change it, use  the `IDEPROBE_DEBUG_PORT` environment variable.
+
+#### Suspend
+By default, the IDE JVM will **not** wait for the user to connect. To force this behavior, set the `IDEPROBE_DEBUG_SUSPEND=true` environment variable.

docs/display.md

@@ -0,0 +1,7 @@
+#### Display
+
+To configure the display used by the IDE, user must specify the value of the environment variable `IDEPROBE_DISPLAY` to one of:
+1. `native` - used by default, useful, when a user wants to see what happens in the IDE and interact with it during a single scenario. 
+2. `xvfb` - requires the xvfb to be installed on the system - can be used to run tests on CI or just to disable the disrupting windows being open when used on a personal machine
+
+Additionally, unless run in `headless` mode, the driver captures the screenshots of the screen periodically, so it can then be exposed on the CI for the user to inspect the IDE state in case of failures.

docs/driver.md

@@ -0,0 +1,31 @@
+### Driver
+
+Driver controls launching the IDE  
+
+#### launch Command
+`driver.launch.command = ["idea"]`
+
+The command used to launch the IDE. By default, the driver uses the `idea` command, but user can specify a custom command. Note, that the `idea` is available on the `PATH`, if the user wants to wrap it in some custom logic. 
+##### launch Timeout
+`driver.launch.timeout = "30 seconds"`
+
+By default, the driver waits `30 seconds` for the IDE to connect the probe. After exceeding this time, the whole test fails.  
+#### Automatic checks
+```
+driver.checks {
+    errors = false
+    freezes = false
+}
+```
+
+By default, the driver doesn't fail the test upon detecting any errors or freezes during the execution.
+
+
+#### Headless mode
+`driver.headless = true`
+
+By default, the driver launches the IDE in the headless mode. Note, that the behavior of the IDE can differ between headless and non-headless modes.  
+
+#### Virtual Machine options
+`driver.vmOptions = ["-Xmx4096m"]`
+Empty by default. Used by the driver to further customize the IDE. 

docs/workspace.md

@@ -0,0 +1,42 @@
+#### Workspace
+
+User can use workspace to predefine any data required by a single test case.
+
+It can be defined as one of:
+
+1. Directory on the filesystem
+
+`probe.workspace.path = "file://home/foo/bar"`
+
+2. Directory on the classpath
+
+`probe.workspace.path = "classpath:/foo/bar"`
+
+3. Directory within a jar
+
+`probe.workspace.path = "jar:file://foo.jar!/bar/baz"`
+
+4. Github repository
+
+`probe.workspace.path = "https://github.com/foo/bar"`
+
+```
+probe.workspace {
+    path = "https://github.com/foo/bar"`
+    branch = foo
+}
+```
+
+```
+probe.workspace {
+    path = "https://github.com/foo/bar"`
+    tag = foo-1.0
+}
+```
+
+```
+probe.workspace {
+    path = "https://github.com/foo/bar"`
+    commit = 4a2b9edc84b15f4a4707fe75e5036ee5d12f7ac4
+}
+```