{"id":13413888,"url":"https://github.com/corbym/gogiven","last_synced_at":"2025-03-14T20:30:45.497Z","repository":{"id":57496924,"uuid":"115888361","full_name":"corbym/gogiven","owner":"corbym","description":"gogiven - BDD testing framework for go that generates readable output directly from source code","archived":false,"fork":false,"pushed_at":"2023-04-03T15:45:21.000Z","size":233,"stargazers_count":14,"open_issues_count":4,"forks_count":3,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-07-31T20:52:57.273Z","etag":null,"topics":["bdd","bdd-framework","bdd-specs","bdd-tests","generate-html-files","golang","html","spec","specification","testing"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/corbym.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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-12-31T22:33:37.000Z","updated_at":"2023-09-08T17:34:35.000Z","dependencies_parsed_at":"2024-06-20T19:24:31.387Z","dependency_job_id":null,"html_url":"https://github.com/corbym/gogiven","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corbym%2Fgogiven","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corbym%2Fgogiven/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corbym%2Fgogiven/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corbym%2Fgogiven/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/corbym","download_url":"https://codeload.github.com/corbym/gogiven/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243641999,"owners_count":20323947,"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":["bdd","bdd-framework","bdd-specs","bdd-tests","generate-html-files","golang","html","spec","specification","testing"],"created_at":"2024-07-30T20:01:52.027Z","updated_at":"2025-03-14T20:30:45.196Z","avatar_url":"https://github.com/corbym.png","language":"Go","readme":"# gogiven\nAn alternative BDD spec framework for go. Builds on \"go test\" tool and builds on the go testing package.\n\n[![Build status](https://travis-ci.org/corbym/gogiven.svg?branch=master)](https://travis-ci.org/corbym/gogiven/builds)\n[![Go Report Card](https://goreportcard.com/badge/github.com/corbym/gogiven)](https://goreportcard.com/report/github.com/corbym/gogiven)\n[![GoDoc](https://godoc.org/github.com/corbym/gogiven?status.svg)](http://godoc.org/github.com/corbym/gogiven)\n[![Coverage Status](https://coveralls.io/repos/github/corbym/gogiven/badge.svg?branch=master)](https://coveralls.io/github/corbym/gogiven?branch=master)\n\nInspired by [YATSPEC](https://github.com/bodar/yatspec). Another similar idea is [JGiven](http://jgiven.org), although both are Java based.\n\nCheck out the HTML output generator used as a default here: [htmlspec](https://github.com/corbym/htmlspec) - using go's own template/html package.\n\nFeel free to contact me and help improve the code base or let me know if you have any issues or questions!\n\nTo contribute, please read [this first.](https://github.com/corbym/gogiven/blob/master/CONTRIBUTING.md)\n\n## Table of Contents\n1. [Introduction](#introduction)\n2. [Example One - GoGivens in practice](#example)\n3. [Example Two - Table Tests](#tabletest-example)\n4. [Content Generation](#content-gen)\n5. [List of pre-written output generators](#output-generator-list)\n\n## Introduction \u003ca name=\"introduction\"\u003e\u003c/a\u003e\n\nGo Givens is a lightweight BDD framework for producing test specifications directly from the code you write.\n\nGo Givens parses your test file and produces a human-readable output in a specified directory, containing all the tests, captured data and other related information regarding your test such as success or failure.\n\nGo Givens was inspired by YATSPEC, a BDD framework employed extensively by Sky Network Services (part of Sky, a UK tv company). As mentioned above, another similar product is [JGiven](http://jgiven.org).\n\n### Why?\n\nCapturing your test method as test output is the only real way to show it's intention. You can refactor a test, and have the output update accordingly when the test runs. Unlike other go BDD frameworks, you can use function names to declare intent, and refactoring the function will affect the test. E.g.\n\n```go\n\n//Hello, spec world!\nfunc TestMyTest(...){\n\tGiven(testing, someData()). // This is a test\n\tWhen(fooBarBaz()).\n\tThen(baz())\n}\n\n```\n\n.. will be rendered as (but in html, or json, or whatever):\n\n```\nMy Test\nHello, spec world!\n\nSpecification\n\nGiven testing some data noting that this is a test\nWhen foo bar baz\nThen baz \n```\n\nTest data (set by the func ```someData``` in the example above) can be captured in a map of interesting givens, and as the test progresses, the actuals can be captured in a map of captured inputs and outputs.\n\n\n### Interesting whats?\n\nInteresting givens are data points that you want to use in your tests that are important for it to function correctly. \"Given\" data is then used by your application to fulfil some sort of request or process.\n\nInteresting givens are generated as output along side your test output in a table so interested parties can examine them.\n\n### Captured Whos??\n\nCaptured inputs and outputs are data points that are registered by either your system under test (stubs, mocks etc) or the output from your system its self.\n\nCaptured inputs and outputs are logged along side your test, for each test, so that interested parties can view them.\n\n### That's all great, but still.. WHY would I want to log this stuff??\n\nIn BDD, a system's inputs and outputs are important to the business. Capturing the relationships between your data and the way the system handles can be demonstrated to your client. For example, your system could call a 3rd party, and you might want to model the interaction with stubs. \n\nGoGivens gives you a standardised way of rendering captured data alongside your tests so you don't have to worry about it.\n\n\n### Rendered how?\n\nThe test framework parses your test file, and grabs the content. It strips all non-interesting parts out and leaves the Given/When/Then format in plain text ready for a GoGivensOutputGenerator to process the text. Interesting givens and Captured inputs and outputs are maps, which are rendered alongside your test givens as table data -- interesting givens are tablulated, and captured IO is listed.\n\nA complete example of how to write a GoGivensOutputGenerator is given in the sister project [html spec](https://github.com/corbym/htmlspec) - written in Go.\n\n## Example One - GoGivens in Practice \u003ca name=\"example\"\u003e\u003c/a\u003e\n```go\nimport (\n\t\"github.com/corbym/gocrest/has\"\n\t\"github.com/corbym/gocrest/then\"\n\t\"github.com/corbym/gogiven/base\"\n\t\"github.com/corbym/gogiven/testdata\"\n\t\"testing\"\n\t\"github.com/corbym/gocrest/is\"\n)\n\nfunc TestMain(testmain *testing.M) {\n\trunOutput := testmain.Run()\n\tGenerateTestOutput() // You only need test main GenerateTestOutput() if you want to produce HTML output.\n\tos.Exit(runOutput)\n}\n\nfunc TestMyFirst(testing *testing.T) {\n\tGiven(testing, someDataSetup).\n\n\t\tWhen(somethingHappens).\n\n\t\tThen(func(testing base.TestingT, actual testdata.CapturedIO, givens testdata.InterestingGivens) { // passed in testing should be used for assertions\n\t\t//do assertions\n\t\tthen.AssertThat(testing, actual[\"actual\"], is.EqualTo(\"some output\"))\n\t})\n}\n```\nNote you do not have to use \"gocrest\" assertions, you can still call all of testing.T's functions to fail the test or you can use any go testing assertion package compatible with testing.T.\n\nWhen run, the above will produce an HTML output:\n\n[Example Html](https://corbym.github.io/gogiven/example_test.shtml#github.com%2fcorbym%2fgogiven.TestMyFirst)\n\n## Example Two - Table Tests \u003ca name=\"tabletest-example\"\u003e\u003c/a\u003e\n\nTable tests work the same way as normal go table tests. GoGivens will then mark which test failed, if they do, in your test output. \n\nExample:\n\n```go\n...\nfunc TestMyFirst(testing *testing.T){\n   var someRange = []struct {\n\t\tactual   string\n\t\texpected int\n\t}{\n\t\t{actual: \"\", expected: 0},\n\t\t{actual: \"a\", expected: 2},\n\t}\n\tfor _, test := range someRange {\n\t   tst.Run(test.actual, func(weAreTesting *testing.T) {\n\t   \tGiven(weAreTesting, someDataSetup).\n\t\t\tWhen(someAction).\n\t\t\tThen(func(t TestingT, actual CapturedIO, givens InterestingGivens) {\n\t\t\t//do assertions\n\t\tAssertThat(t, actual.CapturedIO[\"actual\"], is.EqualTo(\"some output\"))\n\t   \t})\n\t   }\t\n\t}\n}\n...\n```\n\nThe above test will still fail the test function as far as Go is concerned, but the test output will note that the iteration failed like this:\n\n[Ranged Example Html](https://corbym.github.io/gogiven/example_test.shtml#github.com%2fcorbym%2fgogiven.TestMyFirst_Ranged)\n\n**Note that comments are now rendered. Test function comments appear as part of the spec, and inline comments appear as \"Noting that ..\". In the above, the comment //do assertions would become \"Noting that do assertions\".**\n\n### More Examples\n\n* [Full Index](https://corbym.github.io/gogiven/index.shtml) of all tests generated by GoGiven build\n* [Skipped test](https://corbym.github.io/gogiven/example_test.shtml#github.com%2fcorbym%2fgogiven.TestMyFirst_Skipped.func1)\n* [Without a Given](https://corbym.github.io/gogiven/example_test.shtml#github.com%2fcorbym%2fgogiven.TestWithoutGiven)\n\n# Content Generation \u003ca name=\"content-gen\"\u003e\u003c/a\u003e\n\nGogivens comes defaultly configured with an html generator (```htmlspec.NewTestOutputGenerator```) that is consumed by a file generator (```generator.FileOutputGenerator```) (see the godoc for more information). The content generator implements the following interface:\n\n```go\ntype GoGivensOutputGenerator interface {\n\tGenerate(data *PageData) (output io.Reader)\n\t//ContentType is text/html, application/json or other mime type\n\tContentType() string\n}\n```\n\nThe generated content ```(output io.Reader)``` is then consumed by an OutputListener:\n\n\n```go\ntype OutputListener interface {\n\tNotify(testFilePath string, contentType string, output io.Reader)\n}\n```\n\nIf you want your own output listener just create your own and replace and/or append to the default listeners in your TestMain:\n\nGoGiven's html spec now generates an index file, which is always stored along side the test html output.\n\n```go\nfunc TestMain(testmain *testing.M) {\n\tgogiven.OutputListeners = []generator.OutputListener{new(MyFooListener)}\n\t// or alternately (or inclusively!)\n\tgogiven.OutputListeners = append(OutputListeners, new(MyBarListener))\n\trunOutput := testmain.Run()\n\tgogiven.GenerateTestOutput() // generates the output after the test is finished.\n\tos.Exit(runOutput)\n}\n```\n\n## Setting the test file output (for the ```generator.FileOutputGenerator```)\n\nYou can add the environment variable GOGIVENS_OUTPUT_DIR to your env properties that points to a directory you want goGivens to report the test output to.\n\nDefault is the os's tmp directory.\n\n## List of Pre-written Ouput Generators \u003ca name=\"output-generator-list\"\u003e\u003c/a\u003e\n\nGoGiven comes with the following output generators:\n\n* HTML Spec: https://github.com/corbym/htmlspec - generates the output used in the test example. \n* JSON Spec: https://github.com/corbym/jsonspec - generates the output in JSON format.\n","funding_links":[],"categories":["测试","Testing","Template Engines","测试相关`测试库和测试数据集生成库`","Testing Frameworks","测试相关"],"sub_categories":["HTTP客户端","Testing Frameworks","Advanced Console UIs","HTTP Clients","交流","查询语"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorbym%2Fgogiven","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcorbym%2Fgogiven","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorbym%2Fgogiven/lists"}