From d0a56bae95f0054147af4e27a9109f630affd95b Mon Sep 17 00:00:00 2001 From: Price Hiller Date: Tue, 18 Jul 2023 02:24:00 -0500 Subject: [PATCH 1/4] docs: add documentation for tests --- tests/README.md | 106 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 tests/README.md diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 000000000..18a68249e --- /dev/null +++ b/tests/README.md @@ -0,0 +1,106 @@ +# Neogit Tests + +## Running Tests + +As a base requirement you must have `make` installed. + +Once `make` is installed you can run tests by entering `make test` in the top level directory of Neogit into your command line. + +## Adding a test dependency + +If you're adding a lua plugin dependency to Neogit and wish to test it, open `tests/init.lua` in your editor. + +Look for the following lines: + +```lua +if os.getenv("CI") then + vim.opt.runtimepath:prepend(vim.fn.getcwd()) + vim.cmd([[runtime! plugin/plenary.vim]]) + vim.cmd([[runtime! plugin/neogit.lua]]) +else + ensure_installed("nvim-lua/plenary.nvim") + ensure_installed("nvim-telescope/telescope.nvim") +end +``` + +As an example let's say we want to add [`vim-fugitive`](https://github.com/tpope/vim-fugitive) to our test dependencies. Our new dependency section would look like this: + +```lua +if os.getenv("CI") then + vim.opt.runtimepath:prepend(vim.fn.getcwd()) + vim.cmd([[runtime! plugin/plenary.vim]]) + vim.cmd([[runtime! plugin/neogit.lua]]) + vim.cmd([[runtime! plugin/fugitive.vim]]) +else + ensure_installed("nvim-lua/plenary.nvim") + ensure_installed("nvim-telescope/telescope.nvim") + ensure_installed("tpope/vim-fugitive") +end +``` + +## Test Organization + +### Where do tests go? + +All tests are to be placed within the `tests/specs` directory, and placed mocking the path of the Neogit module the test is responsible for. For instance, say you wanted to test `lua/neogit/config.lua` then you would create the test file in `tests/specs/neogit/config_spec.lua` which mirrors the path in the main Neogit module. + +### Where do utility functions go? + +If you have any utility code that has to do with git, it should be placed in `tests/util/git_harness.lua`. + +If you have a generic utility function _only_ relevant for tests then it should go in `tests/util/util.lua`. If it is generic enough that it could be useful in the general Neogit code then a consideration should be made to place this utility code in `lua/neogit/lib/util.lua`. + +### Where should raw content files go? + +Raw content files that you want to test against should go into `tests/test_files`. If you have a raw file you'd like to use against in git, then you'll need to add it to the git repository within `tests/.repo`. This can be done by changing directory into `tests/.repo` and renaming `.git.orig` to `.git` then adding any relevant changes to that repository. Once you're done, make sure you rename `.git` back to `.git.org`. + +As a note the above is likely to become deprecated when a improved declarative lua git repository creation is made. + +## Writing a test + +Let's write a basic test to validate two things about a variable to get a quick intro to writing tests. + +1. Validate the variable's type +2. Validate the variable's content + +```lua +local our_variable = "Hello World!" +describe("validating a string variable", function () + it("should be of type string", function() + assert.True(type(our_variable) == "string") + end) + + it("should have content 'Hello World!'", function() + assert.are.same("Hello World!", our_varible) + ) +end) +``` + +Nothing too crazy there. + +Now let's take a look at a test for Neogit, specifically our `tests/specs/neogit/lib/git/cli_spec.lua` test. + +```lua +local eq = assert.are.same +local git_cli = require("neogit.lib.git.cli") +local git_harness = require("tests.util.git_harness") +local in_prepared_repo = git_harness.in_prepared_repo + +describe("git cli", function() + describe("root detection", function() + it( + "finds the correct git root for a non symlinked directory", + in_prepared_repo(function(root_dir) + local detected_root_dir = git_cli.git_root() + eq(detected_root_dir, root_dir) + end) + ) + end) +end) +``` + +This test gets the root directory of a git repository. You'll notice something interesting we do in our `it` statement different from the prior example. We're passing `in_prepared_repo` to `it`. This function sets up a simple test bed repository (specifically the repository found with `tests/.repo`) to test Neogit against. If you ever need to test Neogit in a way that requires a git repository, you probably want to use `in_prepared_repo`. + +For more test examples take a look at the tests written within the `tests` directory or our test runner's testing guide: [plenary test guide](https://github.com/nvim-lua/plenary.nvim/blob/master/TESTS_README.md). + +For the assertions available, most assertions from [`luassert`](https://github.com/lunarmodules/luassert) are accessible. From f9c2f5481a1e0a2dfa983934b636139fa408cf22 Mon Sep 17 00:00:00 2001 From: Price Hiller Date: Tue, 18 Jul 2023 11:29:29 -0500 Subject: [PATCH 2/4] test(refactor): rename test_files -> fixtures --- tests/README.md | 2 +- tests/{test_files => fixtures}/a.txt | 0 tests/{test_files => fixtures}/output | 0 tests/{test_files => fixtures}/process_test | 0 tests/specs/neogit/process_spec.lua | 6 +++--- tests/util/util.lua | 4 ++-- 6 files changed, 6 insertions(+), 6 deletions(-) rename tests/{test_files => fixtures}/a.txt (100%) rename tests/{test_files => fixtures}/output (100%) rename tests/{test_files => fixtures}/process_test (100%) diff --git a/tests/README.md b/tests/README.md index 18a68249e..fbdd5aec7 100644 --- a/tests/README.md +++ b/tests/README.md @@ -52,7 +52,7 @@ If you have a generic utility function _only_ relevant for tests then it should ### Where should raw content files go? -Raw content files that you want to test against should go into `tests/test_files`. If you have a raw file you'd like to use against in git, then you'll need to add it to the git repository within `tests/.repo`. This can be done by changing directory into `tests/.repo` and renaming `.git.orig` to `.git` then adding any relevant changes to that repository. Once you're done, make sure you rename `.git` back to `.git.org`. +Raw content files that you want to test against should go into `tests/fixtures`. If you have a raw file you'd like to use against in git, then you'll need to add it to the git repository within `tests/.repo`. This can be done by changing directory into `tests/.repo` and renaming `.git.orig` to `.git` then adding any relevant changes to that repository. Once you're done, make sure you rename `.git` back to `.git.org`. As a note the above is likely to become deprecated when a improved declarative lua git repository creation is made. diff --git a/tests/test_files/a.txt b/tests/fixtures/a.txt similarity index 100% rename from tests/test_files/a.txt rename to tests/fixtures/a.txt diff --git a/tests/test_files/output b/tests/fixtures/output similarity index 100% rename from tests/test_files/output rename to tests/fixtures/output diff --git a/tests/test_files/process_test b/tests/fixtures/process_test similarity index 100% rename from tests/test_files/process_test rename to tests/fixtures/process_test diff --git a/tests/specs/neogit/process_spec.lua b/tests/specs/neogit/process_spec.lua index d65f20d8b..16062b6a7 100644 --- a/tests/specs/neogit/process_spec.lua +++ b/tests/specs/neogit/process_spec.lua @@ -7,7 +7,7 @@ local process = require("neogit.process") describe("process execution", function() it("basic command", function() local result = - process.new({ cmd = { "cat", "process_test" }, cwd = util.get_test_files_dir() }):spawn_blocking(1000) + process.new({ cmd = { "cat", "process_test" }, cwd = util.get_fixtures_dir() }):spawn_blocking(1000) assert(result) assert.are.same(result.stdout, { "This is a test file", @@ -20,7 +20,7 @@ describe("process execution", function() end) it("can cat a file", function() local result = - process.new({ cmd = { "cat", "a.txt" }, cwd = util.get_test_files_dir() }):spawn_blocking(1000) + process.new({ cmd = { "cat", "a.txt" }, cwd = util.get_fixtures_dir() }):spawn_blocking(1000) assert(result) assert.are.same(result.stdout, { @@ -78,7 +78,7 @@ describe("process execution", function() end) it("basic command trim", function() local result = process - .new({ cmd = { "cat", "process_test" }, cwd = util.get_test_files_dir() }) + .new({ cmd = { "cat", "process_test" }, cwd = util.get_fixtures_dir() }) :spawn_blocking(1000) :trim() assert(result) diff --git a/tests/util/util.lua b/tests/util/util.lua index 4f326a5f8..30fb7c29f 100644 --- a/tests/util/util.lua +++ b/tests/util/util.lua @@ -4,8 +4,8 @@ M.project_dir = vim.fn.getcwd() ---Returns the path to the raw test files directory ---@return string The path to the project directory -function M.get_test_files_dir() - return M.project_dir .. "/tests/test_files/" +function M.get_fixtures_dir() + return M.project_dir .. "/tests/fixtures/" end ---Runs a system command and errors if it fails From 6efbaa5faa0140a83fd8f8838daea8856919387f Mon Sep 17 00:00:00 2001 From: Price Hiller Date: Fri, 21 Jul 2023 15:48:07 -0500 Subject: [PATCH 3/4] docs: link to test documentation for more details in contributing --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index de57783e0..63a30587e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,7 +66,7 @@ logger.fmt_debug("This is a verbose log message: %q", status) Neogit is tested using [`Plenary`](https://github.com/nvim-lua/plenary.nvim#plenarytest_harness). -It uses a *Busted* style testing, where each lua file inside [`./tests/{test_name}_spec.lua`] is run. +It uses a *Busted* style testing, where each lua file inside [`./tests/specs/{test_name}_spec.lua`] is run. When adding new functionality we strongly encourage you to add a test spec to ensure that the feature works and remains working when new functionality is tacked on. @@ -78,6 +78,8 @@ A [`Makefile`](./Makefile) is set up to run tests. ```sh make test ``` +See [the test documentation for more details](./tests/README.md). + ### Linting Additionally, linting is enforced using `selene` to catch common errors, most of which are also caught by From b2009f0460123667a2313ca1610ba46dac591ab9 Mon Sep 17 00:00:00 2001 From: Price Hiller Date: Fri, 21 Jul 2023 16:50:39 -0500 Subject: [PATCH 4/4] docs: set contributing `make test` to be multiline fenced block --- CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 63a30587e..4ca2f4729 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -76,8 +76,9 @@ future, and remains *fixed*. A [`Makefile`](./Makefile) is set up to run tests. -```sh make test ``` - +```sh +make test +``` See [the test documentation for more details](./tests/README.md). ### Linting