{"id":21917201,"url":"https://github.com/uncommon/rundown","last_synced_at":"2025-03-22T09:45:40.056Z","repository":{"id":263514792,"uuid":"890648263","full_name":"Uncommon/Rundown","owner":"Uncommon","description":"Swift BDD testing framework that leverages result builders and macros.","archived":false,"fork":false,"pushed_at":"2025-02-28T04:27:38.000Z","size":200,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-28T11:59:31.297Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Swift","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/Uncommon.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":"2024-11-18T23:57:01.000Z","updated_at":"2025-02-19T15:25:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"7b96eb9d-e75d-4917-8968-9ac9da0c8280","html_url":"https://github.com/Uncommon/Rundown","commit_stats":null,"previous_names":["uncommon/scaff"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Uncommon%2FRundown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Uncommon%2FRundown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Uncommon%2FRundown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Uncommon%2FRundown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Uncommon","download_url":"https://codeload.github.com/Uncommon/Rundown/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244937740,"owners_count":20535124,"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":[],"created_at":"2024-11-28T19:28:40.984Z","updated_at":"2025-03-22T09:45:40.049Z","avatar_url":"https://github.com/Uncommon.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Rundown\n\nRundown is based on the pattern used in testing libraries such as RSpec, where tests are organized into steps:\n\n```swift\ndescribe(\"this app feature\") {\n  context(\"in one context\") {\n    it(\"does one thing\") {\n      // perform tests\n    }\n  }\n  context(\"in another context\") {\n    beforeAll {\n      // set up the context\n    }\n    it(\"does another thing\") {\n      // perform tests\n    }\n    afterAll {\n      // clean up\n    }\n  }\n}\n```\n\nA Swift result builder is used to assemble the steps into an object that can be executed in a unit test. The result builder also ensures proper ordering of elements:\n\n* `beforeAll`\n* `beforeEach`\n* `describe`/`context`/`it`/`within`\n* `afterEach`\n* `afterAll`\n\nMis-ordered elements produce a compile-time error.\n\n`within` is a new element type for tests that need to run inside a callback, such as `TaskLocal.withValue()`.\n\n## Test framework support\n\nThe goals is for this library to be equally useful in either XCTest or Swift Testing.\n\nXCTest support has the following features:\n\n* Each test element is run using `XCTContext.runActivity()` so that the test structure is evident in the logs.\n* A sub class of `XCTestCase`, named `Rundown.TestCase`, is provided so that test failures include the full name of the test element, including enclosing `Describe` and `Context` elements.\n* `XCTSkip` is handled so that only the remaining elements at that level are skipped.\n* Using `XCTContext.runActivity()` with `async` tests is currently not supported. It is a `@MainActor` function, which complicates things. \n\nSimilar support for Swift Testing is planned, but the Swift Testing APIs do not yet provide for implementing those features. It is still possible to simply run the test elements, though. \n\n## Running tests\n\nThe main way to run tests looks like this:\n\n``` swift\nspec {\n  it(\"works\") {\n    // ···\n  }\n}\n```\n\nThe `spec()` function creates an outer `describe` element, using either the name of the calling function or a provided string, and then executes it. This is a global function.\n\nThere is also an `async` version of `spec()`, so if your test function is `async` then just call `await spec { ··· }`, and then you can use `await` inside your test elements.\n\nWhen working with `XCTest`, there is also `spec()` as a method of `XCTestCase` - or more precisely, a method of the subclass `Rundown.TestCase`. This subclass should always be used so that issues can be logged with the full test element description, and this version of `spec()` uses an `XCTActivity` for each test element. \n\nThe goal is to do something similar for Swift Testing, but it doesn't yet have an equivalent for `XCTActivity`.\n\n## Goals and plans\n\n* Compatibility with XCTest and Swift Testing, with an API that looks the same in either case\n* Flexibility to use it or not for any given test (hence there is no custom test discovery; this may change in the future, especially if framework support improves)\n* Minimal boilerplate at the use site\n* Ease of use during development, such as running (or skipping) specific elements\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funcommon%2Frundown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funcommon%2Frundown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funcommon%2Frundown/lists"}