{"id":13671873,"url":"https://github.com/nextest-rs/datatest-stable","last_synced_at":"2025-05-07T13:07:13.785Z","repository":{"id":39899172,"uuid":"479144653","full_name":"nextest-rs/datatest-stable","owner":"nextest-rs","description":"Data-driven tests on stable Rust","archived":false,"fork":false,"pushed_at":"2025-05-07T04:00:59.000Z","size":398,"stargazers_count":39,"open_issues_count":8,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-07T13:07:03.626Z","etag":null,"topics":["data-driven-tests","datatest","nextest","rust","testing"],"latest_commit_sha":null,"homepage":"https://docs.rs/datatest-stable","language":"Rust","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/nextest-rs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","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,"zenodo":null},"funding":{"github":"sunshowers"}},"created_at":"2022-04-07T20:51:32.000Z","updated_at":"2025-05-07T04:01:01.000Z","dependencies_parsed_at":"2023-10-01T23:37:30.139Z","dependency_job_id":"1113fa67-1781-4a3e-a2e9-2f7b5f51a4ab","html_url":"https://github.com/nextest-rs/datatest-stable","commit_stats":{"total_commits":69,"total_committers":16,"mean_commits":4.3125,"dds":0.7101449275362319,"last_synced_commit":"72db7f6d1bbe36a5407e96b9488a581f763e106f"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextest-rs%2Fdatatest-stable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextest-rs%2Fdatatest-stable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextest-rs%2Fdatatest-stable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextest-rs%2Fdatatest-stable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nextest-rs","download_url":"https://codeload.github.com/nextest-rs/datatest-stable/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252883204,"owners_count":21819160,"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":["data-driven-tests","datatest","nextest","rust","testing"],"created_at":"2024-08-02T09:01:20.711Z","updated_at":"2025-05-07T13:07:13.761Z","avatar_url":"https://github.com/nextest-rs.png","language":"Rust","funding_links":["https://github.com/sponsors/sunshowers"],"categories":["Rust"],"sub_categories":[],"readme":"\u003c!-- cargo-sync-rdme title [[ --\u003e\n# datatest-stable\n\u003c!-- cargo-sync-rdme ]] --\u003e\n\u003c!-- cargo-sync-rdme badge [[ --\u003e\n[![Maintenance: passively-maintained](https://img.shields.io/badge/maintenance-passively--maintained-yellowgreen.svg?)](https://doc.rust-lang.org/cargo/reference/manifest.html#the-badges-section)\n![License: MIT OR Apache-2.0](https://img.shields.io/crates/l/datatest-stable.svg?)\n[![crates.io](https://img.shields.io/crates/v/datatest-stable.svg?logo=rust)](https://crates.io/crates/datatest-stable)\n[![docs.rs](https://img.shields.io/docsrs/datatest-stable.svg?logo=docs.rs)](https://docs.rs/datatest-stable)\n[![Rust: ^1.72.0](https://img.shields.io/badge/rust-^1.72.0-93450a.svg?logo=rust)](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field)\n\u003c!-- cargo-sync-rdme ]] --\u003e\n\u003c!-- cargo-sync-rdme rustdoc [[ --\u003e\n`datatest-stable` is a test harness intended to write *file-driven* or *data-driven* tests,\nwhere individual test case fixtures are specified as files and not as code.\n\nGiven:\n\n* a test `my_test` that accepts a path, and optionally the contents as input\n* a directory to look for files (test fixtures) in\n* a pattern to match files on\n\n`datatest-stable` will call the `my_test` function once per matching file in\nthe directory. Directory traversals are recursive.\n\n`datatest-stable` works with [cargo nextest](https://nexte.st/), and is part\nof the [nextest-rs organization](https://github.com/nextest-rs/) on GitHub.\nWith nextest, each test case is represented as a separate test, and is run\nas a separate process in parallel.\n\n## Usage\n\n1. Configure the test target by setting `harness = false` in `Cargo.toml`:\n\n````toml\n[[test]]\nname = \"\u003ctest target name\u003e\"\nharness = false\n````\n\n2. Call the `datatest_stable::harness!` macro as:\n\n````rust,ignore\ndatatest_stable::harness! {\n    { test = my_test, root = \"path/to/fixtures\", pattern = r\".*\" },\n}\n````\n\n* `test` - The test function to be executed on each matching input. This function can be one\n  of:\n  \n  * `fn(\u0026Path) -\u003e datatest_stable::Result\u003c()\u003e`\n  * `fn(\u0026Utf8Path) -\u003e datatest_stable::Result\u003c()\u003e` ([`Utf8Path`](https://docs.rs/camino/1.1.9/camino/struct.Utf8Path.html) is part of the\n    [`camino`](https://docs.rs/camino/1.1.9/camino/index.html) library, and is re-exported here for convenience.)\n  * `fn(\u0026P, String) -\u003e datatest_stable::Result\u003c()\u003e` where `P` is `Path` or `Utf8Path`. If the\n    extra `String` parameter is specified, the contents of the file will be loaded and passed in\n    as a string (erroring out if that failed).\n  * `fn(\u0026P, Vec\u003cu8\u003e) -\u003e datatest_stable::Result\u003c()\u003e` where `P` is `Path` or `Utf8Path`. If the\n    extra `Vec\u003cu8\u003e` parameter is specified, the contents of the file will be loaded and passed\n    in as a `Vec\u003cu8\u003e` (erroring out if that failed).\n* `root` - The path to the root directory where the input files (fixtures)\n  live. Relative paths are resolved relative to the crate root (the directory where the crate’s\n  `Cargo.toml` is located).\n  \n  `root` is an arbitrary expression that implements\n  [`Display`](https://doc.rust-lang.org/nightly/core/fmt/trait.Display.html), such as `\u0026str`, or a function call that\n  returns a [`Utf8PathBuf`](https://docs.rs/camino/1.1.9/camino/struct.Utf8PathBuf.html).\n\n* `pattern` - a regex used to match against and select each file to be tested. Extended regexes\n  with lookaround and backtracking are supported via the [`fancy_regex`](https://docs.rs/fancy-regex/0.14.0/fancy_regex/index.html) crate.\n  \n  `pattern` is an arbitrary expression that implements [`Display`](https://doc.rust-lang.org/nightly/core/fmt/trait.Display.html), such as\n  `\u0026str`, or a function call that returns a `String`.\n  \n  `pattern` is optional, and defaults to `r\".*\"` (match all files).\n\nThe three parameters can be repeated if you have multiple sets of data-driven tests to be run:\n\n````rust,ignore\ndatatest_stable::harness! {\n    { test = testfn1, root = root1, pattern = pattern1 },\n    { test = testfn2, root = root2 },\n}\n````\n\nTrailing commas are optional.\n\n### Relative and absolute paths\n\nThe `pattern` argument is tested against the **relative** path of each file,\n**excluding** the `root` prefix – not the absolute path.\n\nThe `Path` and `Utf8Path` passed into the test functions are created by\njoining `root` to the relative path of the file.\n\n* If `root` is **relative**, the paths passed in are relative to the crate root.\n* If `root` is **absolute**, the paths passed in are absolute.\n\nFor uniformity, all relative paths use `/` as the path separator,\nincluding on Windows, and all absolute paths use the platform’s native\nseparator throughout.\n\n### Examples\n\nThis is an example test. Use it with `harness = false`.\n\n````rust\nuse datatest_stable::Utf8Path;\nuse std::path::Path;\n\nfn my_test(path: \u0026Path) -\u003e datatest_stable::Result\u003c()\u003e {\n    // ... write test here\n\n    Ok(())\n}\n\nfn my_test_utf8(path: \u0026Utf8Path, contents: String) -\u003e datatest_stable::Result\u003c()\u003e {\n    // ... write test here\n\n    Ok(())\n}\n\ndatatest_stable::harness! {\n    { test = my_test, root = \"path/to/fixtures\" },\n    {\n        test = my_test_utf8,\n        root = \"path/to/fixtures\",\n        pattern = r\"^.*\\.txt$\",\n    },\n}\n````\n\nIf `path/to/fixtures` contains a file `foo/bar.txt`, then:\n\n* The pattern `r\"^.*/*\"` will match `foo/bar.txt`.\n* `my_test` and `my_test_utf8` will be called with `\"path/to/fixtures/foo/bar.txt\"`.\n\n### Embedding directories at compile time\n\nWith the `include-dir` feature enabled, you can use the\n[`include_dir`](https://docs.rs/include_dir) crate’s [`include_dir!`](https://docs.rs/include_dir_macros/0.7.4/include_dir_macros/macro.include_dir.html) macro.\nThis allows you to embed directories into the binary at compile time.\n\nThis is generally not recommended for rapidly-changing test data, since each\nchange will force a rebuild. But it can be useful for relatively-unchanging\ndata suites distributed separately, e.g. on crates.io.\n\nWith the `include-dir` feature enabled, you can use:\n\n````rust\n// The `include_dir!` macro is re-exported for convenience.\nuse datatest_stable::include_dir;\nuse std::path::Path;\n\nfn my_test(path: \u0026Path, contents: Vec\u003cu8\u003e) -\u003e datatest_stable::Result\u003c()\u003e {\n    // ... write test here\n    Ok(())\n}\n\ndatatest_stable::harness! {\n    { test = my_test, root = include_dir!(\"tests/files\"), pattern = r\"^.*\\.json$\" },\n}\n````\n\nYou can also use directories published as `static` items in upstream crates:\n\n````rust\nuse datatest_stable::{include_dir, Utf8Path};\n\n// In the upstream crate:\npub static FIXTURES: include_dir::Dir\u003c'static\u003e =\n    include_dir!(\"$CARGO_MANIFEST_DIR/tests/files\");\n\n// In your test:\nfn my_test(path: \u0026Utf8Path, contents: String) -\u003e datatest_stable::Result\u003c()\u003e {\n    // ... write test here\n    Ok(())\n}\n\ndatatest_stable::harness! {\n    { test = my_test, root = \u0026FIXTURES },\n}\n````\n\nIn this case, the passed-in `Path` and `Utf8Path` are always **relative** to\nthe root of the included directory. Like elsewhere in `datatest-stable`,\nthese relative paths always use forward slashes as separators, including on\nWindows.\n\nBecause the files don’t exist on disk, the test functions must accept their\ncontents as either a `String` or a `Vec\u003cu8\u003e`. If the argument is not\nprovided, the harness will panic at runtime.\n\n### Conditionally embedding directories\n\nIt is also possible to conditionally include directories at compile time via\na feature flag. For example, you might have an internal-only `testing`\nfeature that you turn on locally, but users don’t on crates.io. In that\ncase, you can use:\n\n````rust\nuse datatest_stable::Utf8Path;\n\n// In the library itself:\npub mod fixtures {\n    #[cfg(feature = \"testing\")]\n    pub static FIXTURES: \u0026str = \"tests/files\";\n\n    #[cfg(not(feature = \"testing\"))]\n    pub static FIXTURES: include_dir::Dir\u003c'static\u003e =\n        include_dir::include_dir!(\"$CARGO_MANIFEST_DIR/tests/files\");\n}\n\n// In the test:\nfn my_test(path: \u0026Utf8Path, contents: String) -\u003e datatest_stable::Result\u003c()\u003e {\n    // ... write test here\n    Ok(())\n}\n\ndatatest_stable::harness! {\n    { test = my_test, root = \u0026fixtures::FIXTURES, pattern = r\"^inputs/.*$\" },\n}\n````\n\nIn this case, note that `path` will be relative to the **crate directory**\n(e.g. `tests/files/foo/bar.txt`) if `FIXTURES` is a string, and relative to\nthe **include directory** (e.g. `foo/bar.txt`) if `FIXTURES` is a\n[`Dir`](https://docs.rs/include_dir/0.7.4/include_dir/dir/struct.Dir.html). Your test should be prepared to handle either\ncase.\n\n## Features\n\n* `include-dir`: Enables the `include_dir!` macro, which allows embedding\n  directories at compile time. This feature is disabled by default.\n\n## Minimum supported Rust version (MSRV)\n\nThe minimum supported Rust version is **Rust 1.72**. MSRV bumps may be accompanied by a minor\nversion update; at any time, Rust versions from at least the last 6 months are supported.\n\n## See also\n\n* [`datatest`](https://crates.io/crates/datatest): the original inspiration for this crate, with\n  more features but targeting nightly Rust.\n* [Data-driven testing](https://en.wikipedia.org/wiki/Data-driven_testing)\n\u003c!-- cargo-sync-rdme ]] --\u003e\n\n## License\n\nThis project is available under the terms of either the [Apache 2.0 license](LICENSE-APACHE) or the [MIT\nlicense](LICENSE-MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnextest-rs%2Fdatatest-stable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnextest-rs%2Fdatatest-stable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnextest-rs%2Fdatatest-stable/lists"}