{"id":16188992,"url":"https://github.com/fogfish/it","last_synced_at":"2025-10-09T23:09:14.354Z","repository":{"id":51258169,"uuid":"223810729","full_name":"fogfish/it","owner":"fogfish","description":"Human-friendly unit tests assertions for Go","archived":false,"fork":false,"pushed_at":"2025-07-25T12:06:16.000Z","size":77,"stargazers_count":2,"open_issues_count":6,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-25T18:52:51.907Z","etag":null,"topics":["assert","behavior-driven-development","go","golang","human-friendly","test-driven-development","unit-testing"],"latest_commit_sha":null,"homepage":null,"language":"Go","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/fogfish.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2019-11-24T21:11:28.000Z","updated_at":"2025-07-25T12:05:56.000Z","dependencies_parsed_at":"2024-06-20T00:06:23.566Z","dependency_job_id":"ea799214-0457-4fb9-9b3f-d8092f46d60e","html_url":"https://github.com/fogfish/it","commit_stats":{"total_commits":31,"total_committers":1,"mean_commits":31.0,"dds":0.0,"last_synced_commit":"f028be4e1fbc7cf886251b1963a67dcd5cc54457"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/fogfish/it","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fogfish%2Fit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fogfish%2Fit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fogfish%2Fit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fogfish%2Fit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fogfish","download_url":"https://codeload.github.com/fogfish/it/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fogfish%2Fit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269102210,"owners_count":24360118,"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-08-06T02:00:09.910Z","response_time":99,"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":["assert","behavior-driven-development","go","golang","human-friendly","test-driven-development","unit-testing"],"created_at":"2024-10-10T07:33:16.655Z","updated_at":"2025-10-09T23:09:09.329Z","avatar_url":"https://github.com/fogfish.png","language":"Go","readme":"# It Should Be Tested.\n\nThe library implements a human-friendly syntax for assertions to validates correctness of your code. It's style allows to write BDD-like specifications: \"X should Y\", \"A equals to B\", etc.\n\n[![Documentation](https://pkg.go.dev/badge/github.com/fogfish/it)](https://pkg.go.dev/github.com/fogfish/it)\n[![Build Status](https://github.com/fogfish/it/workflows/test/badge.svg)](https://github.com/fogfish/it/actions/)\n[![Git Hub](https://img.shields.io/github/last-commit/fogfish/it.svg)](http://travis-ci.org/fogfish/it)\n[![Coverage Status](https://coveralls.io/repos/github/fogfish/it/badge.svg?branch=master)](https://coveralls.io/github/fogfish/it?branch=master)\n[![Go Report Card](https://goreportcard.com/badge/github.com/fogfish/it)](https://goreportcard.com/report/github.com/fogfish/it)\n\n\n\n## Inspiration\n\nThere is a vision that change of code style in testing helps developers to \"switch gears\". It's sole purpose to write unit tests assertions in natural language. The library is inspired by features of [ScalaTest](http://www.scalatest.org) and tries to adapt similar syntax for Golang. \n\n```\nIt Should /* actual */ Be /* expected */\n\nIt Should X Equal Y\nIt Should X Less Y\nIt Should String X Contain Y\nIt Should Seq X Equal Y¹, ... Yⁿ\n```\n\nThe approximation of the style into Golang syntax:\n\n```go\nit.Then(t).\n  Should(it.Equal(x, y)).\n  Should(it.Less(x, y)).\n  Should(it.String(x).Contain(y)).\n  Should(it.Seq(x).Equal(/* ... */))\n```\n\n## Getting Started\n\n- [It Should Be Tested.](#it-should-be-tested)\n  - [Inspiration](#inspiration)\n  - [Getting Started](#getting-started)\n    - [Style](#style)\n    - [Assertions](#assertions)\n    - [Intercepts](#intercepts)\n    - [Equality and identity](#equality-and-identity)\n    - [Ordering](#ordering)\n    - [String matchers](#string-matchers)\n    - [Slices and Sequence matchers](#slices-and-sequence-matchers)\n    - [Map matchers](#map-matchers)\n    - [JSON matchers](#json-matchers)\n  - [How To Contribute](#how-to-contribute)\n    - [commit message](#commit-message)\n    - [bugs](#bugs)\n  - [License](#license)\n\nThe latest version of the library is available at its `main` branch. All development, including new features and bug fixes, take place on the `main` branch using forking and pull requests as described in contribution guidelines. The stable version is available via Golang modules.\n\n1. Use `go get` to retrieve the library and add it as dependency to your application.\n\n```bash\ngo get -u github.com/fogfish/it\n```\n\n2. Import it in your unit tests\n\n```go\nimport (\n  \"github.com/fogfish/it\"\n)\n```\n\nSee the [go doc](http://godoc.org/github.com/fogfish/it) for api spec.\n\n\n### Style\n\nThe coding style is like standard Golang unit tests but assert are written as a chain of asserts in a specification style: \"X should Y,\" \"A must B,\" etc.\n\n```go\nfunc TestMyFeature(t *testing.T) {\n  /* Given */\n  /*  ...  */\n\n  /* When  */\n  /*  ...  */\n\n  it.Then(t).\n    Should(/* X Equal Y */).\n    Should(/* String X Contain Y */)\n}\n```\n\nThe library support 3 imperative keyword `Must`, `Should` and `May` as defined by [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). Its prohibition variants `MustNot`, `ShouldNot` and `May`. \n\nUse the `Skip` imperative keyword to ignore the assert and its result.\n\n\n### Assertions\n\nA first order logic expression asserts the result of unit test.\n\n```go\nit.Then(t).\n  // Inline logical predicates\n  Should(it.True(x == y \u0026\u0026 x \u003e 10)).\n  // Use closed function\n  Should(it.Be(func() bool { return x == y \u0026\u0026 x \u003e 10})).\n  // X should be same type as Y\n  Should(it.SameAs(x, y)).\n  // X should be nil\n  Should(it.Nil(x))\n```\n\n\n### Intercepts\n\nIntercept any failures in target code block. Intercepts supports actual panics and function that return of errors.\n\n```go\nfunc fWithPanic() {/* ... */}\nfunc fWithError() error {/* ... */}\n\nit.Then(t).\n  // Intercept panic in the code block\n  Should(it.Fail(fWithPanic)).\n  // Intercept error in the code block\n  Should(it.Fail(fWithError)).\n```\n\nAssert error for behavior to check the \"type\" of returned error\n\n```go\nvar err interface { Timeout() }\n\nit.Then(t).\n  // Intercept panic in the code block and assert for behavior\n  Should(it.Fail(fWithPanic).With(\u0026err)).\n  Should(it.Fail(fWithError).With(\u0026err)).\n  //  Intercept panic in the code block and match the error code\n  Should(it.Fail(fWithError).Contain(\"error code\"))\n```\n\nThe `it.Fail` interceptor evaluates code block inside and it is limited to function that return single value. The `it.Error` interceptor captures returns of function.   \n\n```go\nfunc fNaryError() (string, error) {/* ... */}\n\nit.Then(t).\n  Should(it.Error(fNaryError())).\n  Should(it.Error(fNaryError()).With(\u0026err)).\n  Should(it.Error(fNaryError()).Contain(\"error code\"))\n```\n\n\n### Equality and identity\n\nMatch unit test results with equality constraint.\n\n```go\nit.Then(t).Should(\n  // X should be equal Y (equal support only scalar types)\n  it.Equal(x, y),\n  // X should be equivalent Y (supports any product types)\n  it.Equiv(x, y),\n  // X should be like Y (if one of value is interface)\n  it.Like(x, y),\n)\n```\n\n### Ordering\n\nCompare unit test results with ordering constraint.\n\n```go\nit.Then(t).\n  // X should be less than Y\n  Should(it.Less(x, y)).\n  // X should be less or equal to Y\n  Should(it.LessOrEqual(x, y)).\n  // X should be greater than Y\n  Should(it.Greater(x, y)).\n  // X should be greater or equal to Y\n  Should(it.GreaterOrEqual(x, y)) \n```\n\n\n### String matchers\n\n```go\nit.Then(t).\n  // String X should have prefix X\n  Should(it.String(x).HavePrefix(y)).\n  // String X should have suffix X\n  Should(it.String(x).HaveSuffix(y)).\n  // String X should contain X\n  Should(it.String(x).Contain(y)).\n```\n\n### Slices and Sequence matchers\n\n```go\nit.Then(t).\n  // Seq X should be empty\n  Should(it.Seq(x).BeEmpty(y)).\n  // Seq X should equal Y¹, ... Yⁿ\n  Should(it.Seq(x).Equal(y1, ..., yn))\n  // Seq X should contain Y\n  Should(it.Seq(x).Contain(y1, ..., yn))\n  // Seq X should contain one of Y\n  Should(it.Seq(x).Contain().OneOf(y1, ..., yn)).\n  // Seq X should contain all of Y\n  Should(it.Seq(x).Contain().AllOf(y1, ..., yn))\n```\n\n\n### Map matchers\n\n```go\nit.Then(t).\n  // Map X should have key K with value Y\n  Should(it.Map(X).Have(k, y)) \n```\n\n### JSON matchers\n\nThe matcher checks expected value against string pattern. It takes a valid JSON as string and compare it against input object. It matches only defined values and supports wildcard matching. For example:\n\n```go\n// matches anything\n`\"_\"`\n\n// match string to regular expression\n`\"regex:example\"` \n\n// matches any object with key \"site\"\n`{\"site\": \"_\"}`\n\n// matches array of length 1 \n`[\"_\"]`\n\n// matches array of any length with head element equal to \"example.com\"\n`[\"example\", \"...\"]`\n\n// matches any object with key \"site\" equal to \"example.com\"\n`{\"site\": \"example.com\"}`\n\n// matches any array of length 2 with first object having the key \n`[{\"site\": \"_\"}, \"_\"]`\n\n// matches nested objects\n`{\"site\": {\"host\": \"_\"}}`\n```\n\n```go\nit.Then(t).Should(\n  it.Json(obj).Equiv(`{\n    \"foo\": \"bar\"\n  }`)\n)\n```\n\n## How To Contribute\n\nThe library is [MIT](LICENSE) licensed and accepts contributions via GitHub pull requests:\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Added some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\n\nThe build and testing process requires [Go](https://golang.org) version 1.13 or later.\n\n**Build** and **run** service in your development console. The following command boots Erlang virtual machine and opens Erlang shell.\n\n```bash\ngit clone https://github.com/fogfish/gurl\ncd gurl\ngo test -cover\n```\n\n### commit message\n\nThe commit message helps us to write a good release note, speed-up review process. The message should address two question what changed and why. The project follows the template defined by chapter [Contributing to a Project](http://git-scm.com/book/ch5-2.html) of Git book.\n\n### bugs\n\nIf you experience any issues with the library, please let us know via [GitHub issues](https://github.com/fogfish/it/issue). We appreciate detailed and accurate reports that help us to identity and replicate the issue. \n\n## License\n\n[![See LICENSE](https://img.shields.io/github/license/fogfish/it.svg?style=for-the-badge)](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffogfish%2Fit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffogfish%2Fit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffogfish%2Fit/lists"}