diff options
| -rw-r--r-- | CONTRIBUTING.md | 13 | ||||
| -rw-r--r-- | docs/Integration_Tests.md | 123 | ||||
| -rw-r--r-- | pkg/integration/README.md | 18 | ||||
| -rw-r--r-- | pkg/integration/deprecated/integration.go | 4 | ||||
| -rw-r--r-- | pkg/integration/deprecated/runner/main.go | 2 | ||||
| -rw-r--r-- | pkg/integration/deprecated/tui/main.go | 2 | ||||
| -rw-r--r-- | pkg/integration/runner/main.go | 10 | ||||
| -rw-r--r-- | pkg/integration/tui/main.go | 2 | ||||
| -rwxr-xr-x | scripts/bisect.sh | 2 |
9 files changed, 25 insertions, 151 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 11fb75202..c6a68feae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -63,9 +63,9 @@ by setting [`formatting.gofumpt`](https://github.com/golang/tools/blob/master/go ```jsonc // .vscode/settings.json { - "gopls": { - "formatting.gofumpt": true - } + "gopls": { + "formatting.gofumpt": true + } } ``` @@ -82,6 +82,7 @@ From most places in the codebase you have access to a logger e.g. `gui.Log.Warn( If you find that the existing logs are too noisy, you can set the log level with e.g. `LOG_LEVEL=warn go run main.go -debug` and then only use `Warn` logs yourself. If you need to log from code in the vendor directory (e.g. the `gocui` package), you won't have access to the logger, but you can easily add logging support by adding the following: + ```go func newLogger() *logrus.Entry { // REPLACE THE BELOW PATH WITH YOUR ACTUAL LOG PATH (YOU'LL SEE THIS PRINTED WHEN YOU RUN `lazygit --logs` @@ -118,9 +119,7 @@ If you want to trigger a debug session from VSCode, you can use the following sn "request": "launch", "mode": "auto", "program": "main.go", - "args": [ - "--debug" - ], + "args": ["--debug"], "console": "externalTerminal" // <-- you need this to actually see the lazygit UI in a window while debugging } ] @@ -129,7 +128,7 @@ If you want to trigger a debug session from VSCode, you can use the following sn ## Testing -Lazygit has two kinds of tests: unit tests and integration tests. Unit tests go in files that end in `_test.go`, and are written in Go. Lazygit has its own integration test system where you can build a sandbox repo with a shell script, record yourself doing something, and commit the resulting repo snapshot. It's pretty damn cool! To learn more see [here](https://github.com/jesseduffield/lazygit/blob/master/docs/Integration_Tests.md) +Lazygit has two kinds of tests: unit tests and integration tests. Unit tests go in files that end in `_test.go`, and are written in Go. For integration tests, see [here](https://github.com/jesseduffield/lazygit/blob/master/pkg/integration/README.md) ## Updating Gocui diff --git a/docs/Integration_Tests.md b/docs/Integration_Tests.md index 2cbf8064a..bbc2ebe9f 100644 --- a/docs/Integration_Tests.md +++ b/docs/Integration_Tests.md @@ -1,122 +1 @@ -# 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": "Open a confirmation, then open a menu over that, then close the menu. Verify that the confirmation popup also closes automatically", "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" -``` - -Be sure to: - -- ensure that by the end of the test you've got at least one commit in the repo, as we've had issues in the past when that wasn't the case. -- set the git user email and name as above so that your own user details aren't included in the snapshot. - -## Running tests - -### From a TUI - -You can run/record/sandbox tests via a TUI with the following command: - -``` -go run test/lazyintegration/main.go -``` - -This TUI makes much of the following documentation redundant, but feel free to read through anyway! - -### From command line - -To run all tests - assuming you're at the project root: - -``` -go test ./pkg/gui/ -``` - -To run them in parallel - -``` -PARALLEL=true go test ./pkg/gui -``` - -To run a single test - -``` -go test ./pkg/gui -run /<test name> -# For example, to run the `tags` test: -go test ./pkg/gui -run /tags -``` - -To run a test at a certain speed - -``` -SPEED=2 go test ./pkg/gui -run /<test name> -``` - -To update a snapshot - -``` -MODE=updateSnapshot go test ./pkg/gui -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: - -``` -MODE=record go test ./pkg/gui -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(s) after running the test, ignored by git) -expected/ (the 'snapshot' repo(s)) -config/ (need not be present) -test.json -setup.sh -recording.json -``` - -## Sandboxing - -The integration tests serve a secondary purpose of providing a setup for easy sandboxing. If you want to run a test in sandbox mode (meaning the session won't be recorded and we won't create/update snapshots), go: - -``` -MODE=sandbox go test ./pkg/gui -run /<test name> -``` - -## Feedback - -If you think this process can be improved, let me know! It shouldn't be too hard to change things. +see pkg/integration/README.md diff --git a/pkg/integration/README.md b/pkg/integration/README.md index e8df3f190..c38bef931 100644 --- a/pkg/integration/README.md +++ b/pkg/integration/README.md @@ -1,8 +1,6 @@ # Integration Tests -There's a lot happening in this package so it's worth a proper explanation. - -This package is for integration testing: that is, actually running a real lazygit session and having a robot pretend to be a human user and then making assertions that everything works as expected. +The pkg/integration pacakge is for integration testing: that is, actually running a real lazygit session and having a robot pretend to be a human user and then making assertions that everything works as expected. ## Writing tests @@ -43,19 +41,19 @@ There are three ways to invoke a test: 2. go run pkg/integration/tui/main.go 3. go test pkg/integration/integration_test.go -The first, the test runner, is for directly running a test from the command line. +The first, the test runner, is for directly running a test from the command line. If you pass no arguments, it runs all tests. The second, the TUI, is for running tests from a terminal UI where it's easier to find a test and run it without having to copy it's name and paste it into the terminal. This is the easiest approach by far. The third, the go-test command, intended only for use in CI, to be run along with the other `go test` tests. This runs the tests in headless mode so there's no visual output. -The name of a test is based on its path, so the name of the test at `pkg/integration/tests/commit/new_branch.go` is commit/new_branch. +The name of a test is based on its path, so the name of the test at `pkg/integration/tests/commit/new_branch.go` is commit/new_branch. So to run it with our test runner you would run `go run pkg/integration/runner/main.go commit/new_branch`. -You can pass the KEY_PRESS_DELAY env var to the first command in order to set a delay in milliseconds between keypresses, which helps for watching a test at a realistic speed to understand what it's doing. +You can pass the KEY_PRESS_DELAY env var to the test runner in order to set a delay in milliseconds between keypresses, which helps for watching a test at a realistic speed to understand what it's doing. Or in the tui you can press 't' to run the test with a pre-set delay. -## Snapshots +### Snapshots -At the moment (this is subject to change) each test has a snapshot repo created after running for the first time. These snapshots live in `test/integration_new`. Whenever you run a test, the resultant repo will be compared against the snapshot repo and if they're different, you'll be asked whether you want to update the snapshot. If you want to update a snapshot without being prompted you can pass MODE=updateSnapshot to the test runner or the go test command. This is useful when you've made a change to +At the moment (this is subject to change) each test has a snapshot repo created after running for the first time. These snapshots live in `test/integration_new`, in folders named 'expected' (alongside the 'actual' folders which contain the resulting repo from the last test run). Whenever you run a test, the resultant repo will be compared against the snapshot repo and if they're different, you'll be asked whether you want to update the snapshot. If you want to update a snapshot without being prompted you can pass MODE=updateSnapshot to the test runner or the go test command. This is useful when you've made a change to -## Sandbox mode +### Sandbox mode Say you want to do a manual test of how lazygit handles merge-conflicts, but you can't be bothered actually finding a way to create merge conflicts in a repo. To make your life easier, you can simply run a merge-conflicts test in sandbox mode, meaning the setup step is run for you, and then instead of the test driving the lazygit session, you're allowed to drive it yourself. @@ -72,3 +70,5 @@ We should never write any new tests under the old method, and if a given test br ``` go run pkg/integration/deprecated/tui/main.go ``` + +The tests in the old format live in test/integration. In the old format, test definitions are co-located with the snapshots. The setup step is done in a `setup.sh` shell script and the `recording.json` file contains the recorded keypresses to be replayed during the test. diff --git a/pkg/integration/deprecated/integration.go b/pkg/integration/deprecated/integration.go index 761c978e0..5f597fc81 100644 --- a/pkg/integration/deprecated/integration.go +++ b/pkg/integration/deprecated/integration.go @@ -18,9 +18,9 @@ import ( "github.com/jesseduffield/lazygit/pkg/secureexec" ) -// This package is for running our integration test suite. See docs/Integration_Tests.md for more info. +// Deprecated: This file is part of the old way of doing things. See pkg/integration/integration.go for the new way -// Deprecated: This file is part of the old way of doing things. See integration.go for the new way +// This package is for running our integration test suite. See https://github.com/jesseduffield/lazygit/blob/master/pkg/integration/README.mdfor more info. type Test struct { Name string `json:"name"` diff --git a/pkg/integration/deprecated/runner/main.go b/pkg/integration/deprecated/runner/main.go index 18398a450..904cdbeab 100644 --- a/pkg/integration/deprecated/runner/main.go +++ b/pkg/integration/deprecated/runner/main.go @@ -13,7 +13,7 @@ import ( // Deprecated: This file is part of the old way of doing things. See pkg/integration/runner/main.go for the new way -// see docs/Integration_Tests.md +// see https://github.com/jesseduffield/lazygit/blob/master/pkg/integration/README.md // This file can be invoked directly, but you might find it easier to go through // test/lazyintegration/main.go, which provides a convenient gui wrapper to integration tests. // diff --git a/pkg/integration/deprecated/tui/main.go b/pkg/integration/deprecated/tui/main.go index b455c53bd..9830f4229 100644 --- a/pkg/integration/deprecated/tui/main.go +++ b/pkg/integration/deprecated/tui/main.go @@ -16,7 +16,7 @@ import ( // Deprecated. See lazy_integration for the new approach. -// this program lets you manage integration tests in a TUI. See docs/Integration_Tests.md for more info. +// this program lets you manage integration tests in a TUI. See https://github.com/jesseduffield/lazygit/blob/master/pkg/integration/README.md for more info. type App struct { tests []*deprecated.Test diff --git a/pkg/integration/runner/main.go b/pkg/integration/runner/main.go index 217ca9cb0..ed30c63b8 100644 --- a/pkg/integration/runner/main.go +++ b/pkg/integration/runner/main.go @@ -10,13 +10,9 @@ import ( "github.com/jesseduffield/lazygit/pkg/integration/helpers" ) -// see docs/Integration_Tests.md -// This file can be invoked directly, but you might find it easier to go through -// test/lazyintegration/main.go, which provides a convenient gui wrapper to integration tests. -// -// If invoked directly, you can specify a test by passing it as the first argument. -// You can also specify that you want to record a test by passing MODE=record -// as an env var. +// see pkg/integration/README.md + +// If invoked directly, you can specify tests to run by passing them as positional arguments. func main() { mode := integration.GetModeFromEnv() diff --git a/pkg/integration/tui/main.go b/pkg/integration/tui/main.go index 023c764b5..af118918b 100644 --- a/pkg/integration/tui/main.go +++ b/pkg/integration/tui/main.go @@ -15,7 +15,7 @@ import ( "github.com/jesseduffield/lazygit/pkg/secureexec" ) -// this program lets you manage integration tests in a TUI. See docs/Integration_Tests.md for more info. +// this program lets you manage integration tests in a TUI. See pkg/integration/README.md for more info. type App struct { tests []*helpers.Test diff --git a/scripts/bisect.sh b/scripts/bisect.sh index 0e5f404cb..a3bc5f19e 100755 --- a/scripts/bisect.sh +++ b/scripts/bisect.sh @@ -2,7 +2,7 @@ # How to use: # 1) find a commit that is working fine. -# 2) Create an integration test capturing the fact that it works (Don't commit it). See https://github.com/jesseduffield/lazygit/blob/master/docs/Integration_Tests.md +# 2) Create an integration test capturing the fact that it works (Don't commit it). See https://github.com/jesseduffield/lazygit/blob/master/pkg/integration/README.md # 3) checkout the commit that's known to be failing # 4) run this script supplying the commit sha / tag name that works and the name of the newly created test |