From 2f8c31c66c56d7c7626c5193d7386cc280e16322 Mon Sep 17 00:00:00 2001
From: Imran Iqbal <iqbalmy@hotmail.com>
Date: Fri, 26 Mar 2021 14:26:34 +0000
Subject: [PATCH] docs(readme): add `Testing with Vagrant` section

---
 docs/README.rst | 63 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 62 insertions(+), 1 deletion(-)

diff --git a/docs/README.rst b/docs/README.rst
index 5f65482..6acccf1 100644
--- a/docs/README.rst
+++ b/docs/README.rst
@@ -266,7 +266,7 @@ e.g. ``debian-9-2019-2-py3``.
 ``bin/kitchen converge``
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-Creates the docker instance and runs the ``template`` main state, ready for testing.
+Creates the docker instance and runs the ``openssh`` main states, ready for testing.
 
 ``bin/kitchen verify``
 ^^^^^^^^^^^^^^^^^^^^^^
@@ -288,3 +288,64 @@ Runs all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``veri
 
 Gives you SSH access to the instance for manual testing.
 
+Testing with Vagrant
+--------------------
+
+Windows/FreeBSD/OpenBSD testing is done with ``kitchen-salt``.
+
+Requirements
+^^^^^^^^^^^^
+
+* Ruby
+* Virtualbox
+* Vagrant
+
+Setup
+^^^^^
+
+.. code-block:: bash
+
+   $ gem install bundler
+   $ bundle install --with=vagrant
+   $ bin/kitchen test [platform]
+
+Where ``[platform]`` is the platform name defined in ``kitchen.vagrant.yml``,
+e.g. ``windows-81-latest-py3``.
+
+Note
+^^^^
+
+When testing using Vagrant you must set the environment variable ``KITCHEN_LOCAL_YAML`` to ``kitchen.vagrant.yml``.  For example:
+
+.. code-block:: bash
+
+   $ KITCHEN_LOCAL_YAML=kitchen.vagrant.yml bin/kitchen test      # Alternatively,
+   $ export KITCHEN_LOCAL_YAML=kitchen.vagrant.yml
+   $ bin/kitchen test
+
+Then run the following commands as needed.
+
+``bin/kitchen converge``
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Creates the Vagrant instance and runs the ``openssh`` main states, ready for testing.
+
+``bin/kitchen verify``
+^^^^^^^^^^^^^^^^^^^^^^
+
+Runs the ``inspec`` tests on the actual instance.
+
+``bin/kitchen destroy``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Removes the Vagrant instance.
+
+``bin/kitchen test``
+^^^^^^^^^^^^^^^^^^^^
+
+Runs all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``.
+
+``bin/kitchen login``
+^^^^^^^^^^^^^^^^^^^^^
+
+Gives you RDP/SSH access to the instance for manual testing.