{"id":16115279,"url":"https://github.com/iafan/agenda","last_synced_at":"2026-03-16T20:04:32.465Z","repository":{"id":146407841,"uuid":"91775354","full_name":"iafan/agenda","owner":"iafan","description":"Approval testing micro-framework for Go","archived":false,"fork":false,"pushed_at":"2020-01-08T21:21:01.000Z","size":21,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-28T08:46:03.136Z","etag":null,"topics":["approval-test","go","golang","golden-master","table-driven-test","testing"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iafan.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,"publiccode":null,"codemeta":null}},"created_at":"2017-05-19T06:55:54.000Z","updated_at":"2020-01-08T21:21:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"332f17ef-fa1d-4127-ae1b-bc7ebbbf31ef","html_url":"https://github.com/iafan/agenda","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iafan%2Fagenda","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iafan%2Fagenda/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iafan%2Fagenda/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iafan%2Fagenda/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iafan","download_url":"https://codeload.github.com/iafan/agenda/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243918620,"owners_count":20368745,"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":["approval-test","go","golang","golden-master","table-driven-test","testing"],"created_at":"2024-10-09T20:18:24.950Z","updated_at":"2026-03-16T20:04:32.394Z","avatar_url":"https://github.com/iafan.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"Agenda (Auto-GENerated DAta) Testing in Go\n==========================================\n\n[![build status](https://travis-ci.org/iafan/agenda.svg)](https://travis-ci.org/iafan/agenda)\n[![documentation](https://godoc.org/github.com/iafan/agenda?status.svg)](http://godoc.org/github.com/iafan/agenda)\n[![report card](https://goreportcard.com/badge/github.com/iafan/agenda)](https://goreportcard.com/report/github.com/iafan/agenda)\n\nAgenda testing is an approach where you store your tests in external data files\n(usually JSON), and the same test infrastructure can be used to generate\nyour reference output data files (in initialization mode), or to compare\npreviously created reference files with current test results (in regular mode).\n\nAgenda allows you to focus on business logic of your tests (making sure you\nrun your business code with all required combination of input data), and spare\nyourself from writing value/type/structure comparison logic. In some sense,\nthe core code for agenda-based tests somewhat resembles functional programming approach,\nas your tests just take the input data, do the computation, and return\ntheir artifacts. Agenda package takes care of data storage, retrieval and comparison.\n\nWhile all this might sound complicated, Agenda is a very small package\nwith more documentation (and tests) than code.\n\nAgenda works on top of standard 'testing' package and can be mixed together\nwith traditionally written unit tests; the test directory structure and file naming\nare configurable as well. You can choose any file formats to store your input data,\nand use any serialization format of the output data.\n\nStoring both input data and test computation artifacts as external files,\nalong with the ability to re-generate all reference files and do e.g. `git diff`\nafterwards, can bring better understanding on how your code behaves. As you commit\nupdated test artifacts along with the corresponding code changes, the diffs\nwill also help others during code review.\n\nStatus\n======\n\nThis project, while being 'feature-complete' in the sense that it has everything\nto be successfully used for testing purposes, is still in its infancy, so its API\nand Test interface signature may change in the future. Your feedback is welcome!\n\nUsage\n=====\n\nInstall the Go package:\n```\ngo get -u github.com/iafan/agenda\n```\n\nNow create the `example_test.go` file in any directory:\n\n```go\npackage example\n\nimport \"github.com/iafan/agenda\"\n\n// Sum is the function we are testing\nfunc Sum(a int, b int) int {\n    return a + b\n}\n\n// TestSum is the test for Sum()\nfunc TestSum(t *testing.T) {\n    agenda.Run(t, \"testdata/sum\", func(path string, data []byte) ([]byte, error) {\n        // input data structure\n        in := struct {\n            A int `json:\"a\"`\n            B int `json:\"b\"`\n        }{}\n\n        // output data structure\n        out := struct {\n            Result int `json:\"result\"`\n        }{}\n\n        // deserialize provided input data\n        if err := json.Unmarshal(data, \u0026in); err != nil {\n            return nil, err\n        }\n\n        // run the test and populate output data structure\n        out.Result = Sum(in.A, in.B)\n\n        // return serialized output data\n        return json.Marshal(out)\n    })\n}\n```\n\nNow run the test in initialization mode:\n```\n$ go test -args init\n```\n\nThis will create the test directory structure for you (`testdata`-\u003e`sum`).\n\nIt's time to create some test data:\n```\necho '{\"a\":1,\"b\":2}' \u003etestdata/sum/1.json\necho '{\"a\":2,\"b\":3}' \u003etestdata/sum/2.json\necho '{\"a\":-4,\"b\":5}' \u003etestdata/sum/3.json\n```\n\nRun the test in initialization mode again to compute the results and save them as files:\n```\n$ go test -args init\n```\n\nLet's see what we've got:\n```\n$ cat testdata/sum/1.json.result\n{\"result\":3}\n\n$ cat testdata/sum/2.json.result\n{\"result\":5}\n\n$ cat testdata/sum/3.json.result\n{\"result\":1}\n```\n\nNow these results are the artifacts that you can commit to version control\nalong with test data (*.json files).\n\nNext time you change your code, you can run tests in a regular mode:\n```\n$ go test\n```\n\nIn this mode, the freshly computed results of your tests will be\ncompared with the contents of previously saved .result files, and tests will fail\nif they differ.\n\nNow imagine that you changed your business logic, and this also brings\nsome expected changes to test results. Just run `go test -args init` again\nand then analyze the diff using e.g. `git diff` or other favorite diffing tool.\nThis diff will give you a clear picture of how your new code behaves.\nIf everything looks good, commit your changed test results along with the change\nto the code.\n\nMore Examples\n=============\n\n[example/](https://github.com/iafan/agenda/tree/master/example) directory contains a very simple project that has both traditional and agenda tests.\n\nTests for Agenda are written in Agenda as well. See [agenda_test.go](https://github.com/iafan/agenda/blob/master/agenda_test.go).\n\nPros\n====\n- Test code and test data are separated. When working in teams, this means one can add tests and analyze their output without modifying the code.\n- Output data files help you visualize the data that you work with.\n- You can quickly re-generate all reference files and do e.g. `git diff` afterwards to see what exact changes your modified code introduces.\n- As you commit reference result files along with the corresponding code changes, the diffs will help others so code reviews.\n- The approach works best for complex input and output data structures which are hard to maintain inside table-driven tests.\n- Since the entire output snapshot is validated, it ensures that you won't miss some assertions. You automatically test every field of every structure.\n- While your test coverage grows, your supporting test code can stay simple.\n\nCons\n====\n- You will have more files to work with and to commit to the repo.\n- The approach might be an overkill for testing simple functions that accept basic input and output data types, and when the number of edge cases to test doesn't grow over time. In such cases, consider [table-driven tests](https://github.com/golang/go/wiki/TableDrivenTests) approach.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiafan%2Fagenda","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiafan%2Fagenda","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiafan%2Fagenda/lists"}