{"id":20012574,"url":"https://github.com/dhanak/tidytest.jl","last_synced_at":"2025-05-04T21:31:36.955Z","repository":{"id":150594836,"uuid":"621884623","full_name":"dhanak/TidyTest.jl","owner":"dhanak","description":"An `AbstractTestSet` implementation and a helper macro for test execution with auto discovery and a neater test summary.","archived":false,"fork":false,"pushed_at":"2024-12-06T17:27:35.000Z","size":887,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-08T12:12:06.999Z","etag":null,"topics":["julia","progress","testing-tools","tests"],"latest_commit_sha":null,"homepage":"","language":"Julia","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dhanak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-03-31T15:41:05.000Z","updated_at":"2024-12-16T18:34:15.000Z","dependencies_parsed_at":"2024-02-06T16:51:29.879Z","dependency_job_id":null,"html_url":"https://github.com/dhanak/TidyTest.jl","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhanak%2FTidyTest.jl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhanak%2FTidyTest.jl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhanak%2FTidyTest.jl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhanak%2FTidyTest.jl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dhanak","download_url":"https://codeload.github.com/dhanak/TidyTest.jl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252404116,"owners_count":21742498,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["julia","progress","testing-tools","tests"],"created_at":"2024-11-13T07:31:34.107Z","updated_at":"2025-05-04T21:31:36.940Z","avatar_url":"https://github.com/dhanak.png","language":"Julia","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![CI](https://github.com/dhanak/TidyTest.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/dhanak/TidyTest.jl/actions/workflows/CI.yml)\n[![codecov](https://codecov.io/gh/dhanak/TidyTest.jl/branch/master/graph/badge.svg?token=CQYSC7NLOT)](https://codecov.io/gh/dhanak/TidyTest.jl)\n[![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)\n\n# TidyTest.jl\n\nAn `AbstractTestSet` implementation and a helper macro for test execution with\nauto discovery and a neater test summary.\n\n## Installation\n\nWithin Julia, execute\n\n```julia\nusing Pkg; Pkg.add(\"TidyTest\")\n```\n\n## Usage\n\nFor the simplest use case, write the following lines in your `runtests.jl` file:\n\n```julia\nusing TidyTest\n\n@run_tests\n```\n\nAdd `TidyTest.jl` to the dependencies of your test:\n\n```julia\njulia\u003e using Pkg; pkg\"activate test; add TidyTest\"\n```\n\nAnd then execute your tests:\n\n```bash\njulia --project -e \"using Pkg; Pkg.test()\"\n```\n\nFor example:\n\n![](sample/vhs/sample.gif)\n\nThe [`@run_tests`](#run_tests) macro automatically discovers all Julia source\nfiles in the directory of `runtests.jl`, and includes all of them. The entire\nblock of includes is wrapped in a single toplevel `@testset` using the custom\ntest set type [`SpinnerTestSet`](#spinnertestset). Test progress is reported\nusing [ProgressMeter.jl][], continuously updating the status as tests are\ncompleted. If some tests fail (or throw an error), the issues are reported as\nthey happen, and a detailed test summary is printed upon completion, using the\ndefault test reporting.\n\n### Test filtering\n\nThe macro facilitates running tests selectively. Every command line argument is\ntreated as a pattern that narrows the set of included test files. Specifically,\nonly test files with a name containing any of the arguments as a substring are\nincluded. The search uses smart case matching: if any of the patterns contains\nat least one capital letter, then matching is case-sensitive, otherwise it is\ncase-insensitive. To pass command line arguments to `Pkg.test()`, the\n`test_args` keyword argument must be used:\n\n```bash\n$ alias jlt='julia --project -e \"using Pkg; Pkg.test(test_args=ARGS)\"'\n$ jlt some tests\n# ...runs test files which have \"some\" or \"tests\" occurring in their names\n```\n\nAlternatively, one can filter tests by passing a `filters` keyword argument to\nthe `@run_tests` macro, with a list of strings:\n\n```julia\n@run_tests filters=[\"some\", \"tests\"]\n```\n\n### Migration guide\n\nTo start using `TidyTest.jl` in an existing package, perform the following\nsteps:\n\n1.  add `TidyTest.jl` to the dependencies of your test (as above);\n\n2.  rename your existing `runtests.jl` file (e.g., `MyModule.jl`, but any name\n    other than `runtests.jl` works);\n\n3.  add a new `runtests.jl` file and write `using TidyTest; @run_tests` in it\n    (as above).\n\nAnd you are all set. Optionally, if you want to use the test filtering\nfunctionality, break up your unit tests into multiple files, placing a single\ntest set in every file.\n\n### Running from the REPL\n\nIn order to use the `@run_tests` macro directly from the REPL, you first need to\nchange the working directory to `test`, otherwise the macro won't find your test\nsource files. It's also recommended to add a semicolon (;) to the end of the\ncommand, to suppress printing the value of the\n[`SpinnerTestSet`](#spinnertestset) returned by the macro call.\n\n```julia\njulia\u003e cd(\"test\")\n\njulia\u003e @run_tests verbose=true;\nTest Summary:   | Pass  Total  Time\n...\n```\n\n## Example sessions\n\nHere are some more examples, run in the [`sample`](sample) directory of this\nrepository.\n\nWhen there are some tests that fail and/or throw an error, the issues are\nreported immediately, the progress line is printed in red, and a detailed\nsummary is printed upon completion:\n\n![](sample/vhs/full.gif)\n\nWhen there are passing tests only, no details are shown. The color of the\nprogress line stays green:\n\n![](sample/vhs/oo.gif)\n\nFiltering is case-sensitive when the pattern contains uppercase characters.\nAlso, when there are broken tests, the color of the progress line turns yellow,\nbut still no details are printed:\n\n![](sample/vhs/b.gif)\n\nDetailed reporting can be forced with the `verbose=true` keyword argument even\nfor passing tests:\n\n![](sample/vhs/oo-verbose.gif)\n\n## Reference\n\n### `@run_tests`\n\n```julia\n@run_tests [name] [dir=\".\"] [filters=ARGS] [rest...]\n```\n\nDiscover and include test (Julia) files from the directory of the caller, and\nwrap them in a [`SpinnerTestSet`](#spinnertestset) for reporting. The name of\nthe testset is automatically derived from the package name, if the macro is\ncalled from the `runtests.jl` file.\n\nOptional arguments:\n\n* `name`: explicitly name the testset;\n\n* `dir=\".\"`: discover tests in the provided directory (defaults to the directory\n  of the source file that contains the macro call);\n\n* `filters=[...]`: filter discovered source files - include only those which\n  contain any of the filter strings as a substring (defaults to the command line\n  arguments);\n\n* all other keyword arguments are passed directly to\n  [`SpinnerTestSet`](#spinnertestset).\n\nFiltering uses smart case matching: if any of the patterns contains at least one\ncapital letter, then matching is case-sensitive, otherwise its case-insensitive.\n\n### `SpinnerTestSet`\n\n```julia\nSpinnerTestSet(desc::String; [width::Integer, verbose::Bool, rest...])\n```\n\nAn implementation of `Test.AbstractTestSet`, that reports testing progress using\n`ProgressMeter.ProgressUnknown`, continuously updating the status as tests are\ncompleted.\n\nArguments:\n\n* `desc`: the name of the testset;\n\n* `width`: the display width of the progress line (defaults to the width of the\n  terminal);\n\n* `verbose`: whether to print a detailed summary even when none of the tests\n  fail or throw an error (defaults to `false`);\n\n* all other keyword arguments are passed directly to `Test.DefaultTestSet`.\n\n## Similar packages\n\n* [TestSetExtensions.jl][]\n\n[ProgressMeter.jl]: https://github.com/timholy/ProgressMeter.jl\n[TestSetExtensions.jl]: https://github.com/ssfrr/TestSetExtensions.jl\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhanak%2Ftidytest.jl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdhanak%2Ftidytest.jl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhanak%2Ftidytest.jl/lists"}