elastic
diff --git a/‎TESTING.asciidoc‎
Lines changed: 145 additions & 59 deletions b/‎TESTING.asciidoc‎
Lines changed: 145 additions & 59 deletions
diff --git a/‎Vagrantfile‎
Lines changed: 39 additions & 0 deletions b/‎Vagrantfile‎
Lines changed: 39 additions & 0 deletions
@@ -25,6 +25,46 @@ run it using Gradle:
 ./gradlew run
 -------------------------------------
 
+==== Launching and debugging from an IDE
+
+If you want to run Elasticsearch from your IDE, the `./gradlew run` task
+supports a remote debugging option:
+
+---------------------------------------------------------------------------
+./gradlew run --debug-jvm
+---------------------------------------------------------------------------
+
+==== Distribution
+
+By default a node is started with the zip distribution.
+In order to start with a different distribution use the `-Drun.distribution` argument.
+
+To for example start the open source distribution:
+
+-------------------------------------
+./gradlew run -Drun.distribution=oss-zip
+-------------------------------------
+
+==== License type
+
+By default a node is started with the `basic` license type.
+In order to start with a different license type use the `-Drun.license_type` argument.
+
+In order to start a node with a trial license execute the following command:
+
+-------------------------------------
+./gradlew run -Drun.license_type=trial
+-------------------------------------
+
+This enables security and other paid features and adds a superuser with the username: `elastic-admin` and
+password: `elastic-password`.
+
+==== Other useful arguments
+
+In order to start a node with a different max heap space add: `-Dtests.heap.size=4G`
+In order to disable annotations add: `-Dtests.asserts=false`
+In order to set an Elasticsearch setting, provide a setting with the following prefix: `-Dtests.es.`
+
 === Test case filtering.
 
 - `tests.class` is a class-filtering shell-like glob pattern,
@@ -303,15 +343,16 @@ comma separated list of nodes to connect to (e.g. localhost:9300). A transport c
 be created based on that and used for all the before|after test operations, and to extract
 the http addresses of the nodes so that REST requests can be sent to them.
 
-== Testing scripts
+== Testing packaging
 
-The simplest way to test scripts and the packaged distributions is to use
-Vagrant. You can get started by following there five easy steps:
+The packaging tests use Vagrant virtual machines to verify that installing
+and running elasticsearch distributions works correctly on supported operating systems.
+These tests should really only be run in vagrant vms because they're destructive.
 
 . Install Virtual Box and Vagrant.
 
-. (Optional) Install vagrant-cachier to squeeze a bit more performance out of
-the process:
+. (Optional) Install https://github.com/fgrehm/vagrant-cachier[vagrant-cachier] to squeeze
+a bit more performance out of the process:
 
 --------------------------------------
 vagrant plugin install vagrant-cachier
@@ -325,26 +366,39 @@ vagrant plugin install vagrant-cachier
 
 . Download and smoke test the VMs with `./gradlew vagrantSmokeTest` or
 `./gradlew -Pvagrant.boxes=all vagrantSmokeTest`. The first time you run this it will
-download the base images and provision the boxes and immediately quit. If you
-you this again it'll skip the download step.
+download the base images and provision the boxes and immediately quit. Downloading all
+the images may take a long time. After the images are already on your machine, they won't
+be downloaded again unless they have been updated to a new version.
 
 . Run the tests with `./gradlew packagingTest`. This will cause Gradle to build
 the tar, zip, and deb packages and all the plugins. It will then run the tests
 on ubuntu-1404 and centos-7. We chose those two distributions as the default
 because they cover deb and rpm packaging and SyvVinit and systemd.
 
-You can run on all the VMs by running `./gradlew -Pvagrant.boxes=all
-packagingTest`. You can run a particular VM with a command like `./gradlew
--Pvagrant.boxes=oel-7 packagingTest`. See `./gradlew tasks` for a complete list
-of available vagrant boxes for testing. It's important to know that if you
-interrupt any of these Gradle commands then the boxes will remain running and
-you'll have to terminate them with `./gradlew stop`.
+You can choose which boxes to test by setting the `-Pvagrant.boxes` project property. All of
+the valid options for this property are:
+
+* `sample` - The default, only chooses ubuntu-1404 and centos-7
+* List of box names, comma separated (e.g. `oel-7,fedora-26`) - Chooses exactly the boxes listed.
+* `linux-all` - All linux boxes.
+* `windows-all` - All Windows boxes. If there are any Windows boxes which do not
+have images available when this value is provided, the build will fail.
+* `all` - All boxes we test. If there are any boxes (e.g. Windows) which do not have images
+available when this value is provided, the build will fail.
+
+For a complete list of boxes on which tests can be run, run `./gradlew :qa:vagrant:listAllBoxes`.
+For a list of boxes that have images available from your configuration, run
+`./gradlew :qa:vagrant:listAvailableBoxes`
+
+Note that if you interrupt gradle in the middle of running these tasks, any boxes started
+will remain running and you'll have to stop them manually with `./gradlew stop` or
+`vagrant halt`.
 
 All the regular vagrant commands should just work so you can get a shell in a
 VM running trusty by running
 `vagrant up ubuntu-1404 --provider virtualbox && vagrant ssh ubuntu-1404`.
 
-These are the linux flavors the Vagrantfile currently supports:
+These are the linux flavors supported, all of which we provide images for
 
 * ubuntu-1404 aka trusty
 * ubuntu-1604 aka xenial
@@ -364,9 +418,42 @@ quality boxes available in vagrant atlas:
 
 * sles-11
 
-We're missing the following because our tests are very linux/bash centric:
+=== Testing packaging on Windows
+
+The packaging tests also support Windows Server 2012R2 and Windows Server 2016.
+Unfortunately we're not able to provide boxes for them in open source use
+because of licensing issues. Any Virtualbox image that has WinRM and Powershell
+enabled for remote users should work.
+
+Testing on Windows requires the https://github.com/criteo/vagrant-winrm[vagrant-winrm] plugin.
+
+------------------------------------
+vagrant plugin install vagrant-winrm
+------------------------------------
+
+Specify the image IDs of the Windows boxes to gradle with the following project
+properties. They can be set in `~/.gradle/gradle.properties` like
 
-* Windows Server 2012
+------------------------------------
+vagrant.windows-2012r2.id=my-image-id
+vagrant.windows-2016.id=another-image-id
+------------------------------------
+
+or passed on the command line like `-Pvagrant.windows-2012r2.id=my-image-id`
+`-Pvagrant.windows-2016=another-image-id`
+
+These properties are required for Windows support in all gradle tasks that
+handle packaging tests. Either or both may be specified. Remember that to run tests
+on these boxes, the project property `vagrant.boxes` still needs to be set to a
+value that will include them.
+
+If you're running vagrant commands outside of gradle, specify the Windows boxes
+with the environment variables
+
+* `VAGRANT_WINDOWS_2012R2_BOX`
+* `VAGRANT_WINDOWS_2016_BOX`
+
+=== Testing VMs are disposable
 
 It's important to think of VMs like cattle. If they become lame you just shoot
 them and let vagrant reprovision them. Say you've hosed your precise VM:
@@ -399,54 +486,62 @@ vagrant destroy -f
 `vagrant up` would normally start all the VMs but we've prevented that because
 that'd consume a ton of ram.
 
-== Testing scripts more directly
+=== Iterating on packaging tests
 
-In general its best to stick to testing in vagrant because the bats scripts are
-destructive. When working with a single package it's generally faster to run its
-tests in a tighter loop than Gradle provides. In one window:
+Running the packaging tests through gradle can take a while because it will start
+and stop the VM each time. You can iterate faster by keeping the VM up and running
+the tests directly.
 
---------------------------------
-./gradlew :distribution:packages:rpm:assemble
---------------------------------
+The packaging tests use a random seed to determine which past version to use for
+testing upgrades. To use a single past version fix the test seed when running
+the commands below (see <<Seed and repetitions.>>)
 
-and in another window:
+First build the packaging tests and their dependencies
 
-----------------------------------------------------
-vagrant up centos-7 --provider virtualbox && vagrant ssh centos-7
-cd $PACKAGING_ARCHIVES
-sudo -E bats $BATS_TESTS/*rpm*.bats
-----------------------------------------------------
+--------------------------------------------
+./gradlew :qa:vagrant:setupPackagingTest
+--------------------------------------------
 
-If you wanted to retest all the release artifacts on a single VM you could:
+Then choose the VM you want to test on and bring it up. For example, to bring
+up Debian 9 use the gradle command below. Bringing the box up with vagrant directly
+may not mount the packaging test project in the right place. Once the VM is up, ssh
+into it
 
--------------------------------------------------
-./gradlew setupPackagingTest
-cd qa/vagrant; vagrant up ubuntu-1404 --provider virtualbox && vagrant ssh ubuntu-1404
+--------------------------------------------
+./gradlew :qa:vagrant:vagrantDebian9#up
+vagrant ssh debian-9
+--------------------------------------------
+
+Now inside the VM, to run the https://github.com/sstephenson/bats[bats] packaging tests
+
+--------------------------------------------
 cd $PACKAGING_ARCHIVES
-sudo -E bats $BATS_TESTS/*.bats
--------------------------------------------------
 
-You can also use Gradle to prepare the test environment and then starts a single VM:
+# runs all bats tests
+sudo bats $BATS_TESTS/*.bats
 
--------------------------------------------------
-./gradlew vagrantFedora27#up
--------------------------------------------------
+# you can also pass specific test files
+sudo bats $BATS_TESTS/20_tar_package.bats $BATS_TESTS/25_tar_plugins.bats
+--------------------------------------------
 
-Or any of vagrantCentos6#up, vagrantCentos7#up, vagrantDebian8#up,
-vagrantDebian9#up, vagrantFedora26#up, vagrantFedora27#up, vagrantOel6#up, vagrantOel7#up,
-vagrantOpensuse42#up,vagrantSles12#up, vagrantUbuntu1404#up, vagrantUbuntu1604#up.
+To run the Java packaging tests, again inside the VM
 
-Once up, you can then connect to the VM using SSH from the elasticsearch directory:
+--------------------------------------------
+bash $PACKAGING_TESTS/run-tests.sh
+--------------------------------------------
 
--------------------------------------------------
-vagrant ssh fedora-27
--------------------------------------------------
+or on Windows
 
-Or from another directory:
+--------------------------------------------
+powershell -File $Env:PACKAGING_TESTS/run-tests.ps1
+--------------------------------------------
 
--------------------------------------------------
-VAGRANT_CWD=/path/to/elasticsearch vagrant ssh fedora-27
--------------------------------------------------
+When you've made changes you want to test, keep the VM up and reload the tests and
+distributions inside by running (on the host)
+
+--------------------------------------------
+./gradlew :qa:vagrant:clean :qa:vagrant:setupPackagingTest
+--------------------------------------------
 
 Note: Starting vagrant VM outside of the elasticsearch folder requires to
 indicates the folder that contains the Vagrantfile using the VAGRANT_CWD
@@ -517,15 +612,6 @@ as its build system. Since the switch to Gradle though, this is no longer possib
 the code currently used to build Elasticsearch does not allow JaCoCo to recognize its tests.
 For more information on this, see the discussion in https://github.com/elastic/elasticsearch/issues/28867[issue #28867].
 
-== Launching and debugging from an IDE
-
-If you want to run Elasticsearch from your IDE, the `./gradlew run` task
-supports a remote debugging option:
-
----------------------------------------------------------------------------
-./gradlew run --debug-jvm
----------------------------------------------------------------------------
-
 == Debugging remotely from an IDE
 
 If you want to run Elasticsearch and be able to remotely attach the process
 
@@ -121,6 +121,26 @@ Vagrant.configure(2) do |config|
       sles_common config, box
     end
   end
+
+  windows_2012r2_box = ENV['VAGRANT_WINDOWS_2012R2_BOX']
+  if windows_2012r2_box && windows_2012r2_box.empty? == false
+    'windows-2012r2'.tap do |box|
+      config.vm.define box, define_opts do |config|
+        config.vm.box = windows_2012r2_box
+        windows_common config, box
+      end
+    end
+  end
+
+  windows_2016_box = ENV['VAGRANT_WINDOWS_2016_BOX']
+  if windows_2016_box && windows_2016_box.empty? == false
+    'windows-2016'.tap do |box|
+      config.vm.define box, define_opts do |config|
+        config.vm.box = windows_2016_box
+        windows_common config, box
+      end
+    end
+  end
 end
 
 def deb_common(config, name, extra: '')
@@ -353,3 +373,22 @@ SUDOERS_VARS
     chmod 0440 /etc/sudoers.d/elasticsearch_vars
   SHELL
 end
+
+def windows_common(config, name)
+  config.vm.provision 'markerfile', type: 'shell', inline: <<-SHELL
+    $ErrorActionPreference = "Stop"
+    New-Item C:/is_vagrant_vm -ItemType file -Force | Out-Null
+  SHELL
+
+  config.vm.provision 'set prompt', type: 'shell', inline: <<-SHELL
+    $ErrorActionPreference = "Stop"
+    $ps_prompt = 'function Prompt { "#{name}:$($ExecutionContext.SessionState.Path.CurrentLocation)>" }'
+    $ps_prompt | Out-File $PsHome/Microsoft.PowerShell_profile.ps1
+  SHELL
+
+  config.vm.provision 'set env variables', type: 'shell', inline: <<-SHELL
+    $ErrorActionPreference = "Stop"
+    [Environment]::SetEnvironmentVariable("PACKAGING_ARCHIVES", "C:/project/build/packaging/archives", "Machine")
+    [Environment]::SetEnvironmentVariable("PACKAGING_TESTS", "C:/project/build/packaging/tests", "Machine")
+  SHELL
+end