Create Integration_Tests.md

1 files changed, 88 insertions, 0 deletions

diff --git a/docs/Integration_Tests.md b/docs/Integration_Tests.md
new file mode 100644
index 000000000..9e550ece8
--- /dev/null
+++ b/docs/Integration_Tests.md
@@ -0,0 +1,88 @@
+# How To Make And Run Integration Tests For lazygit
+
+Integration tests are located in `test/integration`. Each test will run a bash script to prepare a test repo, then replay a recorded lazygit session from within that repo, and then the resultant repo will be compared to an expected repo that was created upon the initial recording. Each integration test lives in its own directory, and the name of the directory becomes the name of the test. Within the directory must be the following files:
+
+### `test.json`
+
+An example of a `test.json` is:
+
+```
+{ "description": "stage a file and commit the change", "speed": 20 }
+```
+
+The `speed` key refers to the playback speed as a multiple of the original recording speed. So 20 means the test will run 20 times faster than the original recording speed. If a test fails for a given speed, it will drop the speed and re-test, until finally attempting the test at the original speed. If you omit the speed, it will default to 10.
+
+### `setup.sh`
+
+This is a bash script containing the instructions for creating the test repo from scratch. For example:
+
+```
+#!/bin/sh
+
+cd $1
+
+git init
+
+git config user.email "CI@example.com"
+git config user.name "CI"
+
+echo test1 > myfile1
+git add .
+git commit -am "myfile1"
+```
+
+## Running tests
+
+To run all tests
+```
+go test pkg/gui/gui_test.go
+```
+
+To run them in parallel
+```
+PARALLEL=true go test pkg/gui/gui_test.go
+```
+
+To run a single test
+```
+go test pkg/gui/gui_test.go -run /<test name>
+```
+
+To run a test at a certain speed
+```
+SPEED=2 go test pkg/gui/gui_test.go -run /<test name>
+```
+
+To update a snapshot
+```
+UPDATE_SNAPSHOTS=true go test pkg/gui/gui_test.go -run /<test name>
+```
+
+## Creating a new test
+
+To create a new test:
+1) Copy and paste an existing test directory and rename the new directory to whatever you want the test name to be. Update the test.json file's description to describe your test.
+2) Update the `setup.sh` any way you like
+3) If you want to have a config folder for just that test, create a `config` directory to contain a `config.yml` and optionally a `state.yml` file. Otherwise, the `test/default_test_config` directory will be used.
+4) From the lazygit root directory, run:
+```
+RECORD_EVENTS=true go test pkg/gui/gui_test.go -run /<test name>
+```
+5) Feel free to re-attempt recording as many times as you like. In the absence of a proper testing framework, the more deliberate your keypresses, the better!
+6) Once satisfied with the recording, stage all the newly created files: `test.json`, `setup.sh`, `recording.json` and the `expected` directory that contains a copy of the repo you created.
+
+The resulting directory will look like:
+```
+actual/ (the resulting repo after running the test, ignored by git)
+expected/ (the 'snapshot' repo)
+config/ (need not be present)
+test.json
+setup.sh
+recording.json
+```
+
+Feel free to create a hierarchy of directories in the `test/integration` directory to group tests by feature.
+
+## Feedback
+
+If you think this process can be improved, let me know! It shouldn't be too hard to change things.