{"id":24319407,"url":"https://github.com/btskinner/stata_unit_test","last_synced_at":"2026-03-14T05:08:01.233Z","repository":{"id":84089716,"uuid":"189060850","full_name":"btskinner/stata_unit_test","owner":"btskinner","description":"Unit testing user-written commands in Stata","archived":false,"fork":false,"pushed_at":"2019-05-29T13:54:43.000Z","size":10,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-10T20:43:51.307Z","etag":null,"topics":["stata","unit-testing"],"latest_commit_sha":null,"homepage":null,"language":"Stata","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/btskinner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"publiccode":null,"codemeta":null}},"created_at":"2019-05-28T16:01:59.000Z","updated_at":"2023-01-08T06:45:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"52d670fe-00e8-457d-b6f9-5b226afc6bd8","html_url":"https://github.com/btskinner/stata_unit_test","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/btskinner/stata_unit_test","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/btskinner%2Fstata_unit_test","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/btskinner%2Fstata_unit_test/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/btskinner%2Fstata_unit_test/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/btskinner%2Fstata_unit_test/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/btskinner","download_url":"https://codeload.github.com/btskinner/stata_unit_test/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/btskinner%2Fstata_unit_test/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27759599,"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","status":"online","status_checked_at":"2025-12-16T02:00:10.477Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["stata","unit-testing"],"created_at":"2025-01-17T15:33:02.884Z","updated_at":"2025-12-16T04:55:44.556Z","avatar_url":"https://github.com/btskinner.png","language":"Stata","readme":"In the course of putting together code for a large project, I wrote a\nnumber of project-specific commands to reduce repeated blocks of\ncode. I wanted to perform unit tests to confirm they worked as\nexpected, but was unable to find an existing process for doing so.\n\nThese helper functions and the process I ended up with are loosely\nbased on R's [testthat](https://testthat.r-lib.org) package /\nprocess. The idea is basically the same:\n\n1. For every command, create a file called `test-*.do` where `*` is\n   the name of the function: *e.g.*, `test-my_command.do`. Store all\n   these files in a single directory.  \n1. Within each `test-*.do` file, use the twin helper commands,\n   `test_command` and `test_assert` to first run your command and then\n   test the results with `assert`-like expressions.  \n1. Batch process all `test-*.do` scripts using `run_tests` in a\n   primary test script. Results from passed and failed tests will be\n   printed in a nice fashion in the results window. If the\n   `stopiferror` option is used, errors will halt the test script and\n   the problem can be investigated.  \n   \nMore information about these commands and an outline of an example\nprocess are below. These commands are not part of a proper `ado` file,\nbut rather should just be `run` or `include`d at the top of the\ntesting script. Someone more adept with writing Stata programs can\ndefinitely improve on them.\n\n## Helper functions\n\nThe following helper functions are found in `test_commands.do`. Simply\n`include` the script to use them.\n\n#### `test_command`\n\nUse `test_command` just before your user-written command. It is a\nsimple wrapper that displays a message before running your command as\nif you had typed it directly.\n\n**USAGE**\n```stata\n. test_command \u003c command to test \u003e\n```\n\n**EXAMPLE**\n```stata\n// EXAMPLE: to test \"my_command x y, gen(z)\"\n. test_command my_command x y, gen(z)\n\nVALIDATING: my_command x y, gen(z)\n```\n\n#### `test_assert`\n\nAfter running your command, use `test_assert` to see that your command\nworked as expected.\n\n**USAGE**\n```stata\ntest_assert \" \u003c testing message string \u003e \" \u003c assertion to test \u003e\n```\n\nThe first argument is a string that should be an informative message\nabout your test. The second argument should be an expression like you\nwould use with Stata's `assert` command. In fact, `test_assert` is\njust a wrapper for the `assert` command that displays cleaner output\nand by default captures error codes rather than halting.\n\n**EXAMPLE**\n```stata\n// EXAMPLE: expect that new variable z is x + y\n. test_assert \"New variable z equals x plus y\" z = x + y \n\n\u003e PASS: New variable z equals x plus y\n```\n\nIf the test fails, the font color will change to that of error codes\n(red by default). The return message simply repeats the assertion\nexpression you used, which should be helpful in tracking down the\nbug.\n\n#### `run_tests`\n\nRun all tests by calling `run_tests` from a separate do file. If you\nadd the `stopiferror` option, then Stata will halt if a test\nfails. Otherwise, the font color and output will change as noted\nabove, but Stata will not stop.\n\n**USAGE**\n```stata\nrun_tests, testfiledirectory(path/to/test-*.do) [ stopiferror ]\n```\n\n## Example process\n\nSee the scripts in the `example` directory for an example testing\nprocess. The user-written command converts a school system-specific\nterm code into a four-digit year. Two versions of the code are\nincluded: one that is correct and one that has a bug (indicated with\n`_bug` at the end of the file name). Normally, the buggy version of\nthe command would be overwritten by the patched version, but both are\nincluded so you can see how `run_tests` handles both passing and\nfailing tests.\n\nTo run:\n\n```stata\n// change into example directy\ncd ./examples\n\n// run\ndo tests\n```\n\n## Templates\n\nThe `template` directory has two template files:  \n\n1. `test-example.do`  \n1. `tests.do`  \n\nThese can be used to build command-specific test files and the main\nprocessing script, respectively.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbtskinner%2Fstata_unit_test","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbtskinner%2Fstata_unit_test","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbtskinner%2Fstata_unit_test/lists"}