reference.conf

// Default configuration for the org.virtuslab.ideprobe.config.IdeProbeConfig
// Comments starting with the # sign are for non-default configs which can be used by users.
// Comments starting with the // signs are for descriptions and guides.
probe {

  // `intellij` is for org.virtuslab.ideprobe.config.IntellijConfig - default values below:
  intellij {
    // `plugins` array contains IntelliJ plugins which should be installed and enabled on IntelliJ run. Here you can add
    // your IntelliJ plugin for tests (amongst other plugins). There are a few ways to provide a proper entry pointing
    // to a plugin:
    // 1. By using a direct URI pointing to the plugin (could be from a website or from a local file). For example:
    #     { uri = "https://packages.jetbrains.team/maven/p/ij/intellij-dependencies/com/intellij/remoterobot/robot-server-plugin/0.11.15/robot-server-plugin/0.11.15.zip" }
    // 2. By using default IntelliJ plugins repository (as defined in `probe.resolvers.plugins.repository.uri`)
    //    with additional id (pluginId), version and (optional) channel parameters which is translated
    //    into a URL with a query string. For example:
    #       { id = "org.intellij.scala", version = "2020.3.369", channel = "nightly" }
    //      will be resolved into following URL with query string (from where ide-probe should download the plugin):
    //      https://plugins.jetbrains.com/plugin/download?pluginId=org.intellij.scala&version=2020.3.369&channel=nightly
    //    and without the optional "channel" parameter:
    #       { id = "org.intellij.scala", version = "2020.3.369" }
    //      will be resolved into following URL with query string (from where ide-probe should download the plugin):
    //      https://plugins.jetbrains.com/plugin/download?pluginId=org.intellij.scala&version=2020.3.369
    // 3. By using a bundled IntelliJ plugin. Such plugin should be bundled in your project as a module/subproject and
    //    available on the classpath when IntelliJ instance should run. For example - such plugin subproject should be
    //    built and published to a `target` directory before performing tests (during compilation).
    //    There are two ways to point to a bundled IntelliJ plugin:
    //    a) By providing plugin's resource file name (probably plugin subproject's name followed by version and file extension).
    //       For example:
    #        { bundle = "driver-test-plugin_2.13-0.45.0-SNAPSHOT.zip" }
    //       which will be resolved properly if mentioned .zip file is available on the classpath.
    //    b) By providing three plugin coordinates: name, scalaVersion (major) and version. For example:
    #        { bundle = "driver-test-plugin", scalaVersion = "2.13", version = "0.45.0-SNAPSHOT" }
    //       which will be resolved the same as the earlier example (so, `.zip` extension is th default one).
    plugins = []

    // `version.release` is the "Version" and connected `version.build` is the "Build Number" of IntelliJ IDEA version.
    // You can search for proper string pairs here:
    // https://www.jetbrains.com/intellij-repository/releases/ under "com.jetbrains.intellij.idea" heading.
    // Moreover - builds from https://www.jetbrains.com/intellij-repository/snapshots/ can be used by default as well.
    // If you want to change the default IntelliJ version, provide both parameters in your .conf file.
    // Notes:
    // - `version.release` takes precedence over `version.build`. If both values point to two different builds, then
    //    the build corresponding to `version.release` will be used.
    // - It is allowed to provide only one of two values (build or release). In order to do so, you have to
    //    do as follows.
    //    If you want to specify only the `version.release` string - you can just do it and your version
    //    will be used.
    //    If you want to specify only the `version.build` string - you have to additionally override
    //    `version.release` and set it to a `null` value. In such scenario, ide-probe will treat the `version.build`
    //    as the "Version" and download it properly.
    //    Nevertheless, best if you provide both values that match because ide-probe uses `version.release`
    //    to choose the version and `version.build` number for naming cache directories etc.
    version {
      build = "212.5080.55"
      release = "2021.2.1"

      // `ext` stands for the file extension (file format). This config specifies which extension should be
      // downloaded and installed. By default, ".zip" distributions of IntelliJ IDEA are downloaded. For now
      // two extensions are supported: ".zip" and ".dmg". ".zip" is the default one whereas ".dmg" should be used
      // for Mac OS X only.
      ext = ".zip"
      # ext = ".dmg"

    }

    // Use `path` config with proper path if you want to use an existing IntelliJ instead of downloading a version.
    // Example path from IntelliJ installed on macOs:
    # path = "/Applications/IntelliJ IDEA CE.app/Contents"

  }

  // `workspace` is for `Option[org.virtuslab.ideprobe.config.WorkspaceConfig]` - default None,
  // hence comments added as a reference. You can specify the workspace by using the below configurations.
  # workspace {

  // First option is to use a Default workspace - by just specifying `probe.workspace.path` with a valid string.
  //
  // `probe.workspace.path` can point to:
  // a) a directory on the filesystem:
  // `probe.workspace.path = "file:///home/foo/bar"`
  // b) a directory within a jar:
  // `probe.workspace.path = "jar:file://foo.jar!/bar/baz"`
  // c) a directory on the classpath:
  // `probe.workspace.path = "classpath:/foo/bar"`
  // d) an online resource (http/https) - which can be for example a github repository as below:
  //
  #   path = "https://github.com/VirtusLab/git-machete.git"

  // If `probe.workspace.path` is set and points to a git repository - you can choose one of three additional options:
  // `branch`, `tag` or `commit` - to specify the reference which should be checked out on the workspace setup.
  // Only one of them can be specified. You can as well not use any of these 3 options - in such scenario the default
  // branch will be checked out just like with a plain `git clone` command. Examples below:
  #   branch = "develop"
  #   tag = "v0.41.0"
  #   commit = "a1861fc3b70588acfa171000eb365bf75c143472"

  // Another option is to use an Existing workspace by passing a proper path to its directory
  // - use only `existing` config. In this case, `probe.workspace.path` MUST NOT be defined.
  // `probe.workspace.existing` can be used for scenarios where you want to reuse an existing workspace instead of
  // copying a workspace each time when tests run. It might be beneficial for big projects / repos.
  #   existing = "/Users/my_username/code/my_repository"
  # }

  // `resolvers` is for `org.virtuslab.ideprobe.config.DependenciesConfig.Resolvers` - default values below
  resolvers {

    // `intellij.repositories` contain patterns which should be resolved by ide-probe to download proper IntelliJ IDEA
    // edition (Community or Ultimate) from proper intelliJ repository. Words inside square brackets
    // are parts of the pattern that are replaced with proper values before download attempt. Current replacements
    // are as follows:
    //
    // "[orgPath]" -> for now it is always replaced by "com/jetbrains/intellij"
    // "[organisation]" -> for now it is always replaced by "com.jetbrains.intellij"
    // "[module]" -> for now it is always replaced by "idea"
    // "[artifact]" -> by default replaced by "ideaIC" (to use IntelliJ IDEA Community edition).
    //     You can use the IntelliJ IDEA Ultimate edition in two ways:
    //     - either replace "[artifact]" with "ideaIU" in your pattern (change the default config)
    //     - or use `IntelliJZipResolver.ultimate` directly from your code (no need to change default config)
    // "[ext]" -> value from `probe.intellij.version.ext` (".zip" by default)
    // "[revision]" -> value from `probe.intellij.version.release` - or from `probe.intellij.version.build` if `release` not found
    // "[build]" -> value from `probe.intellij.version.build`
    // "[version]" -> value from `probe.intellij.version.release` - or from `probe.intellij.version.build` if `release` not found
    // "[release]" -> value from `probe.intellij.version.release` if exists. If not - "[release]" will be replaced with
    //    the "snapshot-release" string. This replacement can be used to make sure that IntelliJ will be downloaded only
    //    based on IntelliJVersion's "release" - and NOT based on "build".
    //
    // You can use a custom IntelliJ repository pattern(s) instead of the default ones by defining your patterns
    // in the `intellij.repositories` config.
    //
    // You can also add a custom IntelliJ repository pattern(s) on top of the 6 default repositories, so that
    // ide-probe will first try using the IntelliJs downloaded from your repositories if present. If ide-probe doesn't
    // find the IntelliJ distribution by your patterns, it will use the default 6 repository patterns listed below.
    // To achieve that, specify a custom repository pattern and add the `official` or `default` keyword on another line.
    // Example below:
    // intellij.repositories = [
    //   "file:///"${HOME}"/.my_intellij_idea_downloads/[revision]/[artifact]-[revision][ext]",
    //   official
    // ]
    //
    // Moreover, you can add a pattern pointing to a directory of an installed IntelliJ instance instead of
    // pattern pointing to a .zip (or .dmg) file. ide-probe will recognize if the pattern points to a directory with
    // installed IntelliJ or to a .zip (or .dmg) file. For example, if you run the IntelliJ Plugin Verifier on your
    // repository (https://plugins.jetbrains.com/docs/intellij/tools-gradle-intellij-plugin.html#tasks-runpluginverifier),
    // then you could use following configuration:
    // intellij.repositories = [
    //   "file:///"${HOME}"/.pluginVerifier/ides/IC-[revision]/",
    //   official
    // ]
    //
    // Such config will make ide-probe use an installed IntelliJ from local filesystem from the
    // ~/.pluginVerifier/ides/IC-[revision]/ directory (if exists). If it does not exist under specified path,
    // then ide-probe will download it from one of the 6 official repositories.
    //
    // If your config contains a pattern pointing to an IntelliJ instance that exists on local filesystem, then you
    // can use globs (* widcard characters) as parts of the pattern. One * wildcard character replaces
    // one atomic directory on the path. Multiple * wildcards can be used in one pattern. For example - this can
    // be useful if you want to use .zip OR installed IntelliJ downloaded earlier by some gradle task:
    // intellij.repositories = [
    //   "file:///"${HOME}"/.gradle/caches/modules-2/files-2.1/com.jetbrains.intellij.idea/ideaIC/[revision]/*/ideaIC-[revision]/"
    // ]
    // - as you can see - the * wildcard is handy as it replaces a hash that could not be known easily. There could be
    // multiple different directories in the * place - but not all of them lead to a valid IntelliJ resource. ide-probe
    // deals with such situations and finds the correct path to a valid IntelliJ resource. The pattern must start with
    // "file:" if resolving * wildcards should be used.
    // Note: example below would work as good as the previous one. Multiple * wildcards in one path are handled properly:
    // intellij.repositories = [
    //   "file:///"${HOME}"/.gradle/*/modules-2/*/*/ideaIC/[revision]/*/ideaIC-[revision]/"
    // ]
    // Note: you can NOT use the * wildcard in place of the last element of the pattern (as that would lead to ambiguous results).
    //
    // Note: if you use the `intellij.repositories` config with a value pointing to an installed
    // IntelliJ instance directory - then DO NOT use the `probe.intellij.path` config in the same time.
    // The `probe.intellij.path` config takes precedence over `intellij.repositories` in such case, so the path
    // from `intellij.repositories` would be ignored.
    //
    intellij.repositories = [
      "https://download.jetbrains.com/[module]/nightly/[artifact]-[revision][ext]",
      "https://download.jetbrains.com/[module]/[artifact]-[revision][ext]",
      "https://download.jetbrains.com/[module]/nightly/[artifact]-[revision].portable[ext]",
      "https://download.jetbrains.com/[module]/[artifact]-[revision].portable[ext]",
      "https://www.jetbrains.com/intellij-repository/releases/[orgPath]/[module]/[artifact]/[revision]/[artifact]-[revision][ext]",
      "https://www.jetbrains.com/intellij-repository/snapshots/[orgPath]/[module]/[artifact]/[revision]-EAP-SNAPSHOT/[artifact]-[revision]-EAP-SNAPSHOT[ext]",
      "https://www.jetbrains.com/intellij-repository/snapshots/[orgPath]/[module]/[artifact]/[revision]-EAP-CANDIDATE-SNAPSHOT/[artifact]-[revision]-EAP-CANDIDATE-SNAPSHOT[ext]",
      "https://www.jetbrains.com/intellij-repository/snapshots/[orgPath]/[module]/[artifact]/[revision]/[artifact]-[revision][ext]"
    ]

    // `plugins.repository.uri` is the URI of the plugin repository. Use this config if you want to use a non-standard
    // plugin repository. The standard one is defined below:
    plugins.repository.uri = "https://plugins.jetbrains.com/plugin/download"

    // `jbr.repositories` contains patterns for JBR versions which should be downloaded and used for tests.
    // ide-probe replaces words in square brackets with replacements as follows:
    // "[major]" -> the "major" part of the JBR release's version number - e.g. "17.0.4" from "17.0.4b469.53"
    // "[minor]" -> the "minor" part of the JBR release's version number - e.g. "b469.53" from "17.0.4b469.53"
    // "[platform]" -> value connected to the detected OS - "linux", "osx" or "windows"
    //
    // You can define your own `jbr.repositories` if you want to use a non-standard JBR repository pattern
    // instead of the 2 standard ones defined below.
    //
    // You can also add a custom JBR repository on top of the 2 default repositories, so that ide-probe will
    // first try using the JBRs downloaded from your repository if present. If ide-probe doesn't find the JBR
    // package in your repository, it will use the default 2 repositories listed below. To achieve that, specify
    // your custom repository pattern and add the `official` or `default` keyword on another line. Example below:
    // jbr.repositories = [
    //   "https://repositories.my-company.com/intellij-jbr/jbr-[major]-[platform]-x64-b[minor].tar.gz",
    //   official
    // ]
    //
    // The `jbr_dcevm` pattern applies only to versions of IntelliJ older than 2022.2 release, whereas
    // `jbr` pattern applies to newer versions where DCEVM is bundled by default.
    // Another important note: currently we are using only JBR packages with `x64` architecture support. During tests
    // it turned out that using `aarch64` packages on processors with `aarch64` architecture (Mac M1 Pro chip) results
    // in "Cannot load JVM bundle:" error. For some reason only `x64` packages work well (both for `x64` and `aarch64`
    // processor architectures). Hence `x64` should stay hardcoded in the `jbr.repositories` elements.
    //
    jbr.repositories = [
      "https://cache-redirector.jetbrains.com/intellij-jbr/jbr_dcevm-[major]-[platform]-x64-b[minor].tar.gz",
      "https://cache-redirector.jetbrains.com/intellij-jbr/jbr-[major]-[platform]-x64-b[minor].tar.gz"
    ]

    // The maximal number of retries that should be performed by resolvers when resolving a pattern to a resource.
    retries = 0
  }

  // `driver` is for `org.virtuslab.ideprobe.config.DriverConfig` - default values below
  driver {

    // `driver.launch` contains settings that define how IDE should be started.
    launch {

      // `driver.launch.command` is a string array transformed into the command used to launch the IDE (each string
      // from the array is a single element of the command). By default, the driver uses the "idea" command, which
      // runs the default "idea" script/executable file (`idea` for macOs, `idea.sh` for Linux). You can specify
      // a custom command by using this config. For example, you can add command line options that should be
      // appended to the command. You can also use a totally different command, like starting your own script, which
      // starts IDE in a custom way.
      // Note, that the "idea" command is available on the PATH. If you want to provide your custom command -
      // make sure it is available on the PATH as well.
      command = ["idea"]

      // `driver.launch.timeout` is the maximum time the driver will wait for the IDE to connect the probe.
      // After exceeding this time, the whole test fails. Note: format for `timeout` should be compatible with
      // possible formats for `scala.concurrent.duration.Duration`.
      timeout = "30.seconds"
    }

    // `driver.check` defines how ide-probe should react to IDE errors and freezes. By defeault, the driver doesn't
    // fail the test upon detecting any errors or freezes during the execution. This behavior can be chenged here.
    check {

      // `driver.check.errors` defines how ide-probe should react to IDE errors.
      errors {

        // `driver.check.errors.enabled` decides if ide-probe should throw an exception (and in result - fail the test)
        // if IDE errors have been detected. By default, it is disabled. Set to `true` to enable this functionality.
        enabled = false

        // `driver.check.errors.includeMessages` defines which IDE error messages should make ide-probe throw an exception
        // and fail the test. By default, `includeMessages` contains one regular expression, that matches
        // all IDE errors messages. So, any IDE error will make the test fail if `driver.check.errors.enabled`
        // is set to `true`. If you want to include only a subset of errors whose substrings match certain
        // `includeMessages` entries, you have to put them into this field.
        //
        // `driver.check.errors.excludeMessages` defines which IDE error messages should NOT make ide-probe
        // throw an exception and fail the test. In other words, here you can define, which IDE errors
        // should be ignored even if `driver.check.errors.enabled` is set to `true`.
        //
        // Both for `includeMessages` and for `excludeMessages` you can define an entry in one of two possible ways:
        // 1. By using a regex-based string. For example: ".*at com.intellij.uast.UastMetaLanguage.*" will match
        //    any error message that contains "at com.intellij.uast.UastMetaLanguage". Note: your regex-based string
        //    CAN NOT be a multi-line string.
        // 2. By using a raw string without regular expressions. In such case ide-probe just checks if IDE error message
        //    contains your raw string. The benefit of this option is that you can use a multi-line string (part of
        //    stacktrace). You don't have to worry about line indentations here as each line is trimmed before performing
        //    the check. If you want to use a multi-line string, use triple quotes: """<your multi-line string...>""".
        //
        // If an IDE error matches both an entry from `includeMessages` and another entry from `excludeMessages`,
        // then such IDE error will be ignored (`excludeMessages` takes precedence).
        includeMessages = [".*"]
        excludeMessages = []
      }

      // `driver.check.freezes.enabled` defines if ide-probe should throw an exception and fail the test if IDE freezes
      // have occured during test. By default, this functionality is disabled. Set to `true` to enable.
      freezes.enabled = false
    }

    // `driver.display` defines the display mode which should be used for the IDE run.
    // - By default, it is "native", which means that everything is displayed on the screen and you can interact
    //   with the IDE during test.
    // - Second possible value is "xvfb" which makes the IDE run in the xvfb mode (using virtual display; only available
    //   under X Window System).
    // - Third possible value is "headless" which runs IDE in a headless mode (without a graphical user interface).
    //   It adds " headless" option to the basic launch command ("idea").
    //
    // This config can be set either with a raw string value or by setting the IDEPROBE_DISPLAY
    // environment variable which overrides the default value.
    //
    // Note: unless run in headless mode, the driver captures 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.
    // If you run in the headless mode - then no screenshots will be captured.
    display = "native" # OR "xvfb" OR "headless" - these are three possible values
    display = ${?IDEPROBE_DISPLAY}

    // `driver.xvfb` contains parameters that are used if IDE runs in the xvfb mode. Basically, it contains three
    // screen size parameters that are passed to the "−screen" command line switch of Xvfb.
    // See https://www.x.org/releases/X11R7.6/doc/man/man1/Xvfb.1.xhtml for more details.
    xvfb {
      screen {
        width = 1920
        height = 1080
        depth = 24
      }
    }

    // `driver.vmOptions` are Java Virtual Machine (JVM) options that are used by the driver to further customize the IDE.
    // Each entry in the `vmOptions` array is a raw string. You can add your configurations for the Java Virtual Machine,
    // like "-Xmx4096m" or "-XX:ReservedCodeCacheSize=240m". These entries are saved by ide-probe into the
    // `IDE_HOME/bin/ideprobe.vmoptions` file (one entry per line) which is later on used by IntelliJ to configure JVM.
    // See https://intellij-support.jetbrains.com/hc/en-us/articles/206544869-Configuring-JVM-options-and-platform-properties
    // for more details.
    vmOptions = []

    // `driver.env` allows you to add other environment variables that should be available during the IDE run.
    // `env` is a Map with string keys and string values (Map[String, String]), so you can add entries like this:
    // { "MY_ENV_VARIABLE" : "some important value" }
    env = {}

    // `driver.debug` is for the usage of the Java Debugger. If enabled, it adds the `-agentlib:jdwp` JVM option
    // which attaches a remote debugger to the JVM. JVM debug mode is disabled by default. If `enabled = true`
    // then the following option is used by default:
    // -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005
    // You can choose another `driver.debug.port` value. It affects the "address=" part of the option which specifies
    // the port, on which you can connect.
    // By default, the IDE JVM will not wait for you to connect. If you want to change this behavior and tell the JVM
    // to wait until debugger is attached to begin execution, set `driver.debug.suspend` to `true`. Then mentioned
    // `-agentlib:jdwp=...` option will be changed so that it uses "suspend=y" option.
    // You can read more about the Java debugger usage here: https://www.ibm.com/docs/en/sdk-java-technology/8?topic=applications-debugging-java
    //
    // All three values can be set directly in the .conf file OR by setting following environment variables, which do
    // override the default values:
    // IDEPROBE_DEBUG - for `driver.debug.enabled`
    // IDEPROBE_DEBUG_PORT - for `driver.debug.port`
    // IDEPROBE_DEBUG_SUSPEND - for `driver.debug.suspend`
    debug {
      enabled = false
      enabled = ${?IDEPROBE_DEBUG}
      port = 5005
      port = ${?IDEPROBE_DEBUG_PORT}
      suspend = false
      suspend = ${?IDEPROBE_DEBUG_SUSPEND}
    }
  }

  // `paths` is for `org.virtuslab.ideprobe.config.PathsConfig` - default values below
  paths {
    // all parameters below are Options and are None by default - hence commented out

    // `base` is the base directory used by ide-probe. All files and directories used by ide-probe in runtime
    // should be under the `base` directory. By default, it gets resolved by java methods as follows:
    // Paths.get(System.getProperty("java.io.tmpdir")).resolve("ide-probe").
    // You can specify a custom directory by using this config.
    # base = "/tmp/ide-probe-tests"

    // `instances` is a directory, where IntelliJ instances are installed in runtime. By default, instances
    // directory is a direct subdirectory of the base dir: `base/instances`.
    # instances = "/tmp/ide-probe-tests/instances"

    // `workspaces` is  a directory, where workspaces (testing repositories) are copied into in runtime.
    // By default, workspaces directory is a direct subdirectory of the base dir: `base/workspaces`.
    # workspaces = "/tmp/ide-probe-tests/workspaces"

    // `screenshots` is  a directory, where screenshots made by ide-probe are saved.
    // By default, screenshots directory is a direct subdirectory of the base dir: `base/screenshots`.
    # screenshots = "/tmp/ide-probe-tests/screenshots"

    // `cache` is  a directory, where IntelliJ instances, plugins and JBR binaries are unpacked and saved into (for
    // later installation and usage). By default, cache directory is a direct subdirectory of the base dir: `base/cache`.
    # cache = "/tmp/ide-probe-tests/cache"

    // `trusted` is a directory passed to IntelliJ as a "trusted" directory. It means that IntelliJ instance will
    // treat all projects/repositories under the `trusted` directory as "safe" and will run the code without alerts.
    // By default, `trusted` is resolved as the root directory: "/".
    # trusted = "/"

    // `logExport` is a directory where logs from the intelliJ instance can be copied into before cleanup
    // of the IntelliJ instance. Specify proper path if you want to have access to IDEA logs after tests finish.
    // By default, `logExport` directory is NOT created and such data is deleted from the disk with all other files
    // from the IntelliJ instance directory. If you use this parameter, the `logExport` directory will be created
    // and it will NOT be removed/cleared. Example path below:
    # logExport = "/tmp/ide-probe/idea-logs"
  }
}