re-name Input and improve documentation

pkg/integration/README.md

@@ -4,8 +4,71 @@ 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.
 
+## Writing tests
+
+The tests live in pkg/integration/tests. Each test has two important steps: the setup step and the run step.
+
+### Setup step
+
+In the setup step, we prepare a repo with shell commands, for example, creating a merge conflict that will need to be resolved upon opening lazygit. This is all done via the `shell` argument.
+
+### Run step
+
+The run step has four arguments passed in:
+
+1. `shell`
+2. `input`
+3. `assert`
+4. `keys`
+
+`shell` we've already seen in the setup step. The reason it's passed into the run step is that we may want to emulate background events. For example, the user modifying a file outside of lazygit.
+
+`input` is for driving the gui by pressing certain keys, selecting list items, etc.
+
+`assert` is for asserting on the state of the lazygit session. When you call a method on `assert`, the assert struct will wait for the assertion to hold true and then continue (failing the test after a timeout). For this reason, assertions have two purposes: one is to ensure the test fails as soon as something unexpected happens, but another is to allow lazygit to process a keypress before you follow up with more keypresses. If you input a bunch of keypresses too quickly lazygit might get confused.
+
+### Tips
+
+Try to do as much setup work as possible in your setup step. For example, if all you're testing is that the user is able to resolve merge conflicts, create the merge conflicts in the setup step. On the other hand, if you're testing to see that lazygit can warn the user about merge conflicts after an attempted merge, it's fine to wait until the run step to actually create the conflicts. If the run step is focused on the thing you're trying to test, the test will run faster and its intent will be clearer.
+
+Use assertions to ensure that lazygit has processed all your keybindings so far. For example, if you press 'n' on a branch to create a new branch, assert that the confirmation view is now focused.
+
+If you find yourself doing something frequently in a test, consider making it a method in one of the helper arguments. For example, instead of calling `input.PressKey(keys.Universal.Confirm)` in 100 places, it's better to have a method `input.Confirm()`. This is not to say that everything should be made into a method on the input struct: just things that are particularly common in tests.
+
+## Running tests
+
 There are three ways to invoke a test:
 
-1. go run pkg/integration/runner/main.go commit/new_branch
+1. go run pkg/integration/runner/main.go [<testname>...]
-2. go test pkg/integration/integration_test.go
+2. go run pkg/integration/tui/main.go
-3.
+3. go test pkg/integration/integration_test.go
+
+The first, the test runner, is for directly running a test from the command line.
+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.
+
+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.
+
+## 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
+
+## 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.
+
+To run a test in sandbox mode you can press 's' on a test in the test TUI or pass the env var MODE=sandbox to the test runner.
+
+## Migration process
+
+At the time of writing, most tests are created under an old approach, where you would record yourself in a lazygit session and then the test would replay the keybindings with the same timestamps. This old approach is great for writing tests quickly, but is much harder to maintain. It has to rely entirely on snapshots to determining if a test passes or fails, and can't do assertions along the way. It's also harder to grok what's the intention behind certain actions that take place within the test (e.g. was the recorder intentionally switching to another panel or was that just a misclick?).
+
+At the moment, all the deprecated test code lives in pkg/integration/deprecated. Hopefully in the very near future we migrate everything across so that we don't need to maintain two systems.
+
+We should never write any new tests under the old method, and if a given test breaks because of new functionality, it's best to simply rewrite it under the new approach. If you want to run a test for the sake of watching what it does so that you can transcribe it into the new approach, you can run:
+
+```
+go run pkg/integration/deprecated/tui/main.go
+```

pkg/integration/deprecated/tui/main.go

@@ -108,7 +108,7 @@ func main() {
 			return nil
 		}
 
-		cmd := secureexec.Command("sh", "-c", fmt.Sprintf("INCLUDE_SKIPPED=true MODE=record go run test/runner/main.go %s", currentTest.Name))
+		cmd := secureexec.Command("sh", "-c", fmt.Sprintf("INCLUDE_SKIPPED=true MODE=record go run pkg/integration/deprecated/runner/main.go %s", currentTest.Name))
 		app.runSubprocess(cmd)
 
 		return nil
@@ -122,7 +122,7 @@ func main() {
 			return nil
 		}
 
-		cmd := secureexec.Command("sh", "-c", fmt.Sprintf("INCLUDE_SKIPPED=true MODE=sandbox go run test/runner/main.go %s", currentTest.Name))
+		cmd := secureexec.Command("sh", "-c", fmt.Sprintf("INCLUDE_SKIPPED=true MODE=sandbox go run pkg/integration/deprecated/runner/main.go %s", currentTest.Name))
 		app.runSubprocess(cmd)
 
 		return nil
@@ -136,7 +136,7 @@ func main() {
 			return nil
 		}
 
-		cmd := secureexec.Command("sh", "-c", fmt.Sprintf("INCLUDE_SKIPPED=true go run test/runner/main.go %s", currentTest.Name))
+		cmd := secureexec.Command("sh", "-c", fmt.Sprintf("INCLUDE_SKIPPED=true go run pkg/integration/deprecated/runner/main.go %s", currentTest.Name))
 		app.runSubprocess(cmd)
 
 		return nil
@@ -150,7 +150,7 @@ func main() {
 			return nil
 		}
 
-		cmd := secureexec.Command("sh", "-c", fmt.Sprintf("INCLUDE_SKIPPED=true MODE=updateSnapshot go run test/runner/main.go %s", currentTest.Name))
+		cmd := secureexec.Command("sh", "-c", fmt.Sprintf("INCLUDE_SKIPPED=true MODE=updateSnapshot go run pkg/integration/deprecated/runner/main.go %s", currentTest.Name))
 		app.runSubprocess(cmd)
 
 		return nil
@@ -164,7 +164,7 @@ func main() {
 			return nil
 		}
 
-		cmd := secureexec.Command("sh", "-c", fmt.Sprintf("INCLUDE_SKIPPED=true SPEED=1 go run test/runner/main.go %s", currentTest.Name))
+		cmd := secureexec.Command("sh", "-c", fmt.Sprintf("INCLUDE_SKIPPED=true SPEED=1 go run pkg/integration/deprecated/runner/main.go %s", currentTest.Name))
 		app.runSubprocess(cmd)
 
 		return nil

pkg/integration/helpers/input.go

@@ -10,15 +10,15 @@ import (
 	integrationTypes "github.com/jesseduffield/lazygit/pkg/integration/types"
 )
 
-type Impl struct {
+type Input struct {
 	gui          integrationTypes.GuiAdapter
 	keys         config.KeybindingConfig
 	assert       *Assert
 	pushKeyDelay int
 }
 
-func NewInput(gui integrationTypes.GuiAdapter, keys config.KeybindingConfig, assert *Assert, pushKeyDelay int) *Impl {
+func NewInput(gui integrationTypes.GuiAdapter, keys config.KeybindingConfig, assert *Assert, pushKeyDelay int) *Input {
-	return &Impl{
+	return &Input{
 		gui:          gui,
 		keys:         keys,
 		assert:       assert,
@@ -28,89 +28,89 @@ func NewInput(gui integrationTypes.GuiAdapter, keys config.KeybindingConfig, ass
 
 // key is something like 'w' or '<space>'. It's best not to pass a direct value,
 // but instead to go through the default user config to get a more meaningful key name
-func (self *Impl) PressKeys(keyStrs ...string) {
+func (self *Input) PressKeys(keyStrs ...string) {
 	for _, keyStr := range keyStrs {
 		self.pressKey(keyStr)
 	}
 }
 
-func (self *Impl) pressKey(keyStr string) {
+func (self *Input) pressKey(keyStr string) {
 	self.Wait(self.pushKeyDelay)
 
 	self.gui.PressKey(keyStr)
 }
 
-func (self *Impl) SwitchToStatusWindow() {
+func (self *Input) SwitchToStatusWindow() {
 	self.pressKey(self.keys.Universal.JumpToBlock[0])
 }
 
-func (self *Impl) SwitchToFilesWindow() {
+func (self *Input) SwitchToFilesWindow() {
 	self.pressKey(self.keys.Universal.JumpToBlock[1])
 }
 
-func (self *Impl) SwitchToBranchesWindow() {
+func (self *Input) SwitchToBranchesWindow() {
 	self.pressKey(self.keys.Universal.JumpToBlock[2])
 }
 
-func (self *Impl) SwitchToCommitsWindow() {
+func (self *Input) SwitchToCommitsWindow() {
 	self.pressKey(self.keys.Universal.JumpToBlock[3])
 }
 
-func (self *Impl) SwitchToStashWindow() {
+func (self *Input) SwitchToStashWindow() {
 	self.pressKey(self.keys.Universal.JumpToBlock[4])
 }
 
-func (self *Impl) Type(content string) {
+func (self *Input) Type(content string) {
 	for _, char := range content {
 		self.pressKey(string(char))
 	}
 }
 
 // i.e. pressing enter
-func (self *Impl) Confirm() {
+func (self *Input) Confirm() {
 	self.pressKey(self.keys.Universal.Confirm)
 }
 
 // i.e. pressing escape
-func (self *Impl) Cancel() {
+func (self *Input) Cancel() {
 	self.pressKey(self.keys.Universal.Return)
 }
 
 // i.e. pressing space
-func (self *Impl) Select() {
+func (self *Input) Select() {
 	self.pressKey(self.keys.Universal.Select)
 }
 
 // i.e. pressing down arrow
-func (self *Impl) NextItem() {
+func (self *Input) NextItem() {
 	self.pressKey(self.keys.Universal.NextItem)
 }
 
 // i.e. pressing up arrow
-func (self *Impl) PreviousItem() {
+func (self *Input) PreviousItem() {
 	self.pressKey(self.keys.Universal.PrevItem)
 }
 
-func (self *Impl) ContinueMerge() {
+func (self *Input) ContinueMerge() {
 	self.PressKeys(self.keys.Universal.CreateRebaseOptionsMenu)
 	self.assert.SelectedLineContains("continue")
 	self.Confirm()
 }
 
-func (self *Impl) ContinueRebase() {
+func (self *Input) ContinueRebase() {
 	self.ContinueMerge()
 }
 
 // for when you want to allow lazygit to process something before continuing
-func (self *Impl) Wait(milliseconds int) {
+func (self *Input) Wait(milliseconds int) {
 	time.Sleep(time.Duration(milliseconds) * time.Millisecond)
 }
 
-func (self *Impl) LogUI(message string) {
+func (self *Input) LogUI(message string) {
 	self.gui.LogUI(message)
 }
 
-func (self *Impl) Log(message string) {
+func (self *Input) Log(message string) {
 	self.gui.LogUI(message)
 }
 
@@ -125,7 +125,7 @@ func (self *Impl) Log(message string) {
 // If this changes in future, we'll need to update this code to first attempt to find the item
 // in the current page and failing that, jump to the top of the view and iterate through all of it,
 // looking for the item.
-func (self *Impl) NavigateToListItemContainingText(text string) {
+func (self *Input) NavigateToListItemContainingText(text string) {
 	self.assert.InListContext()
 
 	currentContext := self.gui.CurrentContext().(types.IListContext)

pkg/integration/helpers/test.go

@@ -21,7 +21,7 @@ type Test struct {
 	setupConfig  func(config *config.AppConfig)
 	run          func(
 		shell *Shell,
-		input *Impl,
+		input *Input,
 		assert *Assert,
 		keys config.KeybindingConfig,
 	)
@@ -30,11 +30,17 @@ type Test struct {
 var _ integrationTypes.IntegrationTest = &Test{}
 
 type NewTestArgs struct {
+	// Briefly describes what happens in the test and what it's testing for
 	Description string
+	// prepares a repo for testing
 	SetupRepo func(shell *Shell)
+	// takes a config and mutates. The mutated context will end up being passed to the gui
 	SetupConfig func(config *config.AppConfig)
-	Run          func(shell *Shell, input *Impl, assert *Assert, keys config.KeybindingConfig)
+	// runs the test
+	Run func(shell *Shell, input *Input, assert *Assert, keys config.KeybindingConfig)
+	// additional args passed to lazygit
 	ExtraCmdArgs string
+	// for when a test is flakey
 	Skip bool
 }
 

pkg/integration/runner/main.go

@@ -5,6 +5,7 @@ import (
 	"os"
 	"os/exec"
 
+	"github.com/jesseduffield/generics/slices"
 	"github.com/jesseduffield/lazygit/pkg/integration"
 	"github.com/jesseduffield/lazygit/pkg/integration/helpers"
 )
@@ -20,27 +21,33 @@ import (
 func main() {
 	mode := integration.GetModeFromEnv()
 	includeSkipped := os.Getenv("INCLUDE_SKIPPED") == "true"
-	selectedTestName := os.Args[1]
+	var testsToRun []*helpers.Test
 
+	if len(os.Args) > 1 {
+	outer:
+		for _, testName := range os.Args[1:] {
 			// check if our given test name actually exists
-	if selectedTestName != "" {
-		found := false
 			for _, test := range integration.Tests {
-			if test.Name() == selectedTestName {
+				if test.Name() == testName {
-				found = true
+					testsToRun = append(testsToRun, test)
-				break
+					continue outer
 				}
 			}
-		if !found {
+			log.Fatalf("test %s not found. Perhaps you forgot to add it to `pkg/integration/integration_tests/tests.go`?", testName)
-			log.Fatalf("test %s not found. Perhaps you forgot to add it to `pkg/integration/integration_tests/tests.go`?", selectedTestName)
 		}
+	} else {
+		testsToRun = integration.Tests
 	}
 
+	testNames := slices.Map(testsToRun, func(test *helpers.Test) string {
+		return test.Name()
+	})
+
 	err := integration.RunTestsNew(
 		log.Printf,
 		runCmdInTerminal,
 		func(test *helpers.Test, f func() error) {
-			if selectedTestName != "" && test.Name() != selectedTestName {
+			if !slices.Contains(testNames, test.Name()) {
 				return
 			}
 			if err := f(); err != nil {

pkg/integration/tests/branch/suggestions.go

@@ -20,7 +20,7 @@ var Suggestions = helpers.NewTest(helpers.NewTestArgs{
 			NewBranch("other-new-branch-2").
 			NewBranch("other-new-branch-3")
 	},
-	Run: func(shell *helpers.Shell, input *helpers.Impl, assert *helpers.Assert, keys config.KeybindingConfig) {
+	Run: func(shell *helpers.Shell, input *helpers.Input, assert *helpers.Assert, keys config.KeybindingConfig) {
 		input.SwitchToBranchesWindow()
 
 		input.PressKeys(keys.Branches.CheckoutBranchByName)

pkg/integration/tests/commit/commit.go

@@ -14,7 +14,7 @@ var Commit = helpers.NewTest(helpers.NewTestArgs{
 		shell.CreateFile("myfile", "myfile content")
 		shell.CreateFile("myfile2", "myfile2 content")
 	},
-	Run: func(shell *helpers.Shell, input *helpers.Impl, assert *helpers.Assert, keys config.KeybindingConfig) {
+	Run: func(shell *helpers.Shell, input *helpers.Input, assert *helpers.Assert, keys config.KeybindingConfig) {
 		assert.CommitCount(0)
 
 		input.Select()

pkg/integration/tests/commit/new_branch.go

@@ -16,7 +16,7 @@ var NewBranch = helpers.NewTest(helpers.NewTestArgs{
 			EmptyCommit("commit 2").
 			EmptyCommit("commit 3")
 	},
-	Run: func(shell *helpers.Shell, input *helpers.Impl, assert *helpers.Assert, keys config.KeybindingConfig) {
+	Run: func(shell *helpers.Shell, input *helpers.Input, assert *helpers.Assert, keys config.KeybindingConfig) {
 		assert.CommitCount(3)
 
 		input.SwitchToCommitsWindow()

pkg/integration/tests/interactive_rebase/one.go

@@ -14,7 +14,7 @@ var One = helpers.NewTest(helpers.NewTestArgs{
 		shell.
 			CreateNCommits(5) // these will appears at commit 05, 04, 04, down to 01
 	},
-	Run: func(shell *helpers.Shell, input *helpers.Impl, assert *helpers.Assert, keys config.KeybindingConfig) {
+	Run: func(shell *helpers.Shell, input *helpers.Input, assert *helpers.Assert, keys config.KeybindingConfig) {
 		input.SwitchToCommitsWindow()
 		assert.CurrentViewName("commits")