{"id":19493298,"url":"https://github.com/negrel/assert","last_synced_at":"2025-04-25T20:31:09.848Z","repository":{"id":205376051,"uuid":"713611793","full_name":"negrel/assert","owner":"negrel","description":"0️⃣ Zero cost debug assertions for Go.","archived":false,"fork":false,"pushed_at":"2024-11-01T08:51:13.000Z","size":78,"stargazers_count":27,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-01T09:20:32.358Z","etag":null,"topics":["assert","debug","go","golang"],"latest_commit_sha":null,"homepage":"","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/negrel.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":"2023-11-02T22:00:29.000Z","updated_at":"2024-11-01T09:07:56.000Z","dependencies_parsed_at":"2024-11-01T09:19:30.735Z","dependency_job_id":"3921c272-9753-4485-ba65-c45613d1426d","html_url":"https://github.com/negrel/assert","commit_stats":null,"previous_names":["negrel/assert"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/negrel%2Fassert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/negrel%2Fassert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/negrel%2Fassert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/negrel%2Fassert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/negrel","download_url":"https://codeload.github.com/negrel/assert/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224016050,"owners_count":17241605,"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":["assert","debug","go","golang"],"created_at":"2024-11-10T21:25:14.368Z","updated_at":"2025-04-25T20:31:09.843Z","avatar_url":"https://github.com/negrel.png","language":"Go","funding_links":["https://www.buymeacoffee.com/negrel"],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n    \u003cimg alt=\"gopher illustration\" src=\"https://spirited.io/wp-content/uploads/elementor/thumbs/1-prc44rwae7cvpfcnuotwqkc46fiz99oyv9553ip1tc.jpg\"\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n\t\u003ca href=\"https://pkg.go.dev/github.com/negrel/assert\"\u003e\n\t\t\u003cimg alt=\"PkgGoDev\" src=\"https://pkg.go.dev/badge/github.com/negrel/assert\"\u003e\n\t\u003c/a\u003e\n\t\u003ca href=\"https://goreportcard.com/report/github.com/negrel/assert\"\u003e\n\t\t\u003cimg alt=\"Go Report Card\" src=\"https://goreportcard.com/badge/github.com/negrel/assert\"\u003e\n\t\u003c/a\u003e\n\u003c/p\u003e\n\n# `assert` - Zero cost debug assertions.\n\nThis package provides zero cost debug assertions to your Go programs. It is based\non the excellent [`github.com/stretchr/testify/assert`](https://github.com/stretchr/testify)\npackage and provide the same API (minus `t testing.T` parameter).\n\n## Why?\n\nThis is a complete rewrite of [`debuggo`](https://github.com/negrel/debuggo) that aims\nto be up to date and more maintainable.\n\nIt aims to provide the same API as [`github.com/stretchr/testify/assert`](https://github.com/stretchr/testify).\n* Prints friendly, easy to read failure descriptions\n* Allows for very readable code\n* Optionally annotate each assertion with a message\n* No performance impact on production build (see benchmarks)\n\nDebug assertions main use is to assert invariant that can't be encoded in the\ntype systems. For example, a method that should be called only when mutex is\nlocked:\n\n```go\npackage mypkg\n\nimport (\n\t\"sync\"\n\t\"github.com/negrel/assert\"\n)\n\ntype myType struct {\n\tmu sync.Mutex\n\t// other fields...\n}\n\n// doWork perform internal work. Caller must hold mutex while calling this\n// function.\nfunc (mt *myType) doWork(k string) {\n\tassert.Locked(\u0026mt.mu) // panic if assertions are enabled and mutex isn't locked\n\n\t// Do work...\n}\n```\n\n## How does it works?\n\n[Read my blog post](https://www.negrel.dev/blog/zero-cost-debug-assertions-in-go/)\nabout to understand how `assert` works and why it is designed that way.\n\n## Getting started\n\nHere is our example program:\n\n```go\npackage main\n\nimport (\n\t\"github.com/negrel/assert\"\n)\n\nfunc main() {\n\tassert.True(false)\n\tprintln(\"Hello world!\")\n}\n```\n\nA simple `go run .` will simply print `Hello world!` as all `assert` functions\nare removed by the compiler.\n\nNow, if we compile and run it with assertions enabled `go run -tags assert .`,\nit will output something like:\n\n```\npanic:\n        Error Trace:    /home/anegrel/code/go/assert/example/main.go:8\n                                                /usr/share/go/src/runtime/proc.go:267\n                                                /usr/share/go/src/runtime/asm_amd64.s:1650\n        Error:          Should be true\n\n\ngoroutine 1 [running]:\ngithub.com/negrel/assert.Fail({0x568dc2, 0xe}, {0x0, 0x0, 0x0})\n        /home/anegrel/code/go/assert/assertions.go:349 +0x168\ngithub.com/negrel/assert.True(...)\n        /home/anegrel/code/go/assert/assertions.go:754\nmain.main()\n        /home/anegrel/code/go/assert/example/main.go:8 +0x27\nexit status 2\n```\n\nNote that most `go` subcommands (build, run, test, ...) supports `-tags` flag.\nYou may want to set `GOFLAGS` environment variable to `-tags assert` make it\npermanent and avoid specifying it on each command.\n\n## Benchmarks\n\nAs we've seen previously, assertions are hidden behind a compilation flag. If\nthe flag is absent, all assertions functions will be empty/noop function that\nthe compiler will optimize.\n\n**WITH** `-tags assert`:\n\n```\ngoos: linux\ngoarch: amd64\npkg: github.com/negrel/assert/tests\ncpu: Intel(R) Core(TM) i5-8250U CPU @ 1.60GHz\nBenchmarkSliceIndexWithoutBoundCheckAssertions\nBenchmarkSliceIndexWithoutBoundCheckAssertions-8        728439501                1.407 ns/op\nBenchmarkSliceIndexWithBoundCheckAssertions\nBenchmarkSliceIndexWithBoundCheckAssertions-8           27423670                40.80 ns/op\nPASS\nok      github.com/negrel/assert/tests  3.338s\n```\n\n**WITHOUT** `-tags assert`:\n\n```\ngoos: linux\ngoarch: amd64\npkg: github.com/negrel/assert/tests\ncpu: Intel(R) Core(TM) i5-8250U CPU @ 1.60GHz\nBenchmarkSliceIndexWithoutBoundCheckAssertions\nBenchmarkSliceIndexWithoutBoundCheckAssertions-8        772181695                1.399 ns/op\nBenchmarkSliceIndexWithBoundCheckAssertions\nBenchmarkSliceIndexWithBoundCheckAssertions-8           802181890                1.412 ns/op\nPASS\nok      github.com/negrel/assert/tests  2.531s\n```\n\nHowever, keep in mind that `assert` may slightly increase binary size (~100 KiB)\nas it imports `net/http` and `reflect`.\n\n## Contributing\n\nIf you want to contribute to `assert` to add a feature or improve the code contact\nme at [negrel.dev@protonmail.com](mailto:negrel.dev@protonmail.com), open an\n[issue](https://github.com/negrel/assert/issues) or make a\n[pull request](https://github.com/negrel/assert/pulls).\n\n## :stars: Show your support\n\nPlease give a :star: if this project helped you!\n\n[![buy me a coffee](.github/images/bmc-button.png)](https://www.buymeacoffee.com/negrel)\n\n## :scroll: License\n\nMIT © [Alexandre Negrel](https://www.negrel.dev/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnegrel%2Fassert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnegrel%2Fassert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnegrel%2Fassert/lists"}