{"id":13484732,"url":"https://github.com/aaronabramov/k9","last_synced_at":"2025-04-15T03:49:35.624Z","repository":{"id":37075476,"uuid":"256895746","full_name":"aaronabramov/k9","owner":"aaronabramov","description":"Rust testing library","archived":false,"fork":false,"pushed_at":"2024-01-02T23:35:24.000Z","size":259,"stargazers_count":343,"open_issues_count":7,"forks_count":22,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-15T03:49:16.555Z","etag":null,"topics":["assertion-library","assertions","rust","snapshots","testing"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/aaronabramov.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}},"created_at":"2020-04-19T02:19:40.000Z","updated_at":"2025-03-21T05:56:25.000Z","dependencies_parsed_at":"2024-01-13T19:18:43.049Z","dependency_job_id":"793be973-6b77-49fe-a56f-4e7de028075d","html_url":"https://github.com/aaronabramov/k9","commit_stats":{"total_commits":159,"total_committers":17,"mean_commits":9.352941176470589,"dds":0.679245283018868,"last_synced_commit":"eb37b7ab9145712c22af26cffac7a828ecc0838d"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronabramov%2Fk9","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronabramov%2Fk9/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronabramov%2Fk9/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronabramov%2Fk9/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaronabramov","download_url":"https://codeload.github.com/aaronabramov/k9/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249003942,"owners_count":21196794,"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":["assertion-library","assertions","rust","snapshots","testing"],"created_at":"2024-07-31T17:01:31.932Z","updated_at":"2025-04-15T03:49:35.607Z","avatar_url":"https://github.com/aaronabramov.png","language":"Rust","readme":"# K9 - Rust Testing Library\n\n[![Crates.io][crates-badge]][crates-url]\n[![Docs.rs][docs-badge]][docs-url]\n![Rust CI](https://github.com/aaronabramov/k9/workflows/Rust%20CI/badge.svg)\n\n[crates-badge]: https://img.shields.io/crates/v/k9.svg\n[crates-url]: https://crates.io/crates/k9\n[docs-badge]: https://docs.rs/k9/badge.svg\n[docs-url]: https://docs.rs/k9\n\n![k9_header](https://user-images.githubusercontent.com/940133/98482607-2140c200-21c8-11eb-84f0-af488323a49a.png)\n\n## Snapshot testing + better assertions\n\n### Available test macros\n\n- `snapshot`\n- `assert_equal`\n- `assert_greater_than`\n- `assert_greater_than_or_equal`\n- `assert_lesser_than`\n- `assert_lesser_than_or_equal`\n- `assert_matches_regex`\n- `assert_err_matches_regex`\n- `assert_matches_snapshot`\n- `assert_matches_inline_snapshot`\n- `assert_ok`\n- `assert_err`\n\nSee [https://docs.rs/k9](https://docs.rs/k9) for API documentation\n\n\n## `snapshot!()` macro\n\nSnapshot macro provides the functionality to capture the `Debug` representation\nof any value and make sure it does not change over time. \n\nIf it does change, the test will fail and print the difference between \"old\" and\n\"new\" values.\n\nIf the change is expected and valid, running `cargo test` with\n`K9_UPDATE_SNAPSHOTS=1` env variable set will automatically take the new value\nand insert it into the test source code file as a second argument, after which\nall subsequent test runs should start passing again.\n\n![inline_snapshot_demo](https://user-images.githubusercontent.com/940133/102737400-ed030a00-430c-11eb-90ac-66d4d24c9acd.gif)\n\n\n## `assert_equal!()` macro\n\nRust already provides a good built-in test runner and a set of assertion macros like `assert!` and `assert_eq!`.\nThey work great for for quick unit tests, but once the codebase and test suites grows to a certain point it gets\nharder and harder to test things and keep tests readable.\n\n\nFor example, when testing that two structs are equal using `assert_eq!` macro the output does not provide a lot of help\nin understanding why exactly this test failed.\n\n```rust\n\n#[derive(PartialEq, Debug)]\nstruct Person {\n    name: \u0026'static str,\n    age: usize,\n}\n\n#[test]\nfn test_eq() {\n    let person1 = Person {name: \"Bob\", age: 12 };\n    let person2 = Person {name: \"Alice\", age: 20 };\n    assert_eq!(person1, person2, \"These two must be the same person!\");\n}\n```\n\nAll we get is usually a wall of text collapsed into a single line and you have to find the difference between two structs yourself. Which becomes very time consuming when structs are 10+ fields.\n\n```\n---- eq::test_eq stdout ----\nthread 'eq::test_eq' panicked at 'assertion failed: `(left == right)`\n  left: `Person { name: \"Bob\", age: 12 }`,\n right: `Person { name: \"Alice\", age: 20 }`: These two must be the same person!', src/eq.rs:13:5\n```\n\nusing `k9::assert_equal` macro improves this output and prints the difference between two structs:\n\n```rust\nuse k9::assert_equal;\nassert_equal!(person1, person2, \"These two must be the same person!\");\n```\n\n![assert_equal_example](https://user-images.githubusercontent.com/940133/84608052-35310380-ae76-11ea-97fe-751ee76a7735.png)\n\n# Non-equality based assertions\n\nTesting equality is very simple and can definitely work for most of the cases, but one of the disadvantages of only using `assert!` and `assert_eq!` is the error messages when something fails.\nFor example, if you're testing that your code produces valid URL\n\n```rust\nlet url = generate_some_url();\nassert_eq!(URL_REGEX.is_match(url), true);\n```\n\nWhat you get is\n\n```\nthread 'eq::test_eq3' panicked at 'assertion failed: `(left == right)`\n  left: `false`,\n right: `true`', src/eq.rs:19:5\n```\n\nWhich doesn't help much. Especially, if you're new to the code base, seeing things like `expected 'true' but got 'false'` will make you go and look at the code before you even know what the problem can be, which can be very time consuming.\n\nWhat we probably want to see is:\n\n![assert_matches_regex_example](https://user-images.githubusercontent.com/940133/84608051-35310380-ae76-11ea-87c8-c7c8b9ee3903.png)\n\nWhich gives us enough context on what the problem is and how to fix it without for us having to go and run/debug the test first.\n","funding_links":[],"categories":["Rust","Crates"],"sub_categories":["Matchers"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronabramov%2Fk9","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronabramov%2Fk9","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronabramov%2Fk9/lists"}