{"id":13478994,"url":"https://github.com/SwiftDocOrg/DocTest","last_synced_at":"2025-03-27T08:31:14.634Z","repository":{"id":45827992,"uuid":"256559480","full_name":"SwiftDocOrg/DocTest","owner":"SwiftDocOrg","description":"An experimental tool for testing Swift example code in documentation.","archived":true,"fork":false,"pushed_at":"2020-11-24T14:49:14.000Z","size":84,"stargazers_count":358,"open_issues_count":7,"forks_count":9,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-10-30T12:48:28.259Z","etag":null,"topics":["documentation","swift","tap","testing"],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SwiftDocOrg.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-17T16:49:57.000Z","updated_at":"2024-07-06T14:28:25.000Z","dependencies_parsed_at":"2022-09-05T04:51:35.090Z","dependency_job_id":null,"html_url":"https://github.com/SwiftDocOrg/DocTest","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SwiftDocOrg%2FDocTest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SwiftDocOrg%2FDocTest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SwiftDocOrg%2FDocTest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SwiftDocOrg%2FDocTest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SwiftDocOrg","download_url":"https://codeload.github.com/SwiftDocOrg/DocTest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245809820,"owners_count":20676061,"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":["documentation","swift","tap","testing"],"created_at":"2024-07-31T16:02:07.290Z","updated_at":"2025-03-27T08:31:14.226Z","avatar_url":"https://github.com/SwiftDocOrg.png","language":"Swift","funding_links":[],"categories":["Swift"],"sub_categories":[],"readme":"# DocTest\n\n![CI][ci badge]\n\n**DocTest** is an experimental tool\nfor testing Swift example code in documentation.\n\n**This is still a work-in-progress, and not yet ready for production**\n\n![DocTest Example Usage](https://user-images.githubusercontent.com/7659/100109718-f76ed880-2e20-11eb-8c8e-2dc655611081.png)\n\n\u003e DocTest is inspired by\n\u003e [Python's `doctest`](https://docs.python.org/3/library/doctest.html).\n\n* * *\n\nThe hardest part of software documentation is writing it in the first place.\nBut once you clear that initial hurdle,\nthe challenge becomes keeping documentation correct and up-to-date.\n\nThere's no built-in feedback mechanism for documentation like there is for code.\nIf you write invalid code,\nthe compiler will tell you.\nIf you write valid but incorrect code,\nyour test suite will tell you.\nBut if you write documentation with invalid or incorrect example code,\nyou may never find out.\n\nDocTest offers a way to annotate Swift code examples in documentation\nwith expectations about its behavior,\nand test that behavior automatically —\njust like a unit test.\n\n## Requirements\n\n- Swift 5.3\n\n\u003e **Note**:\n\u003e When running `swift-doctest` from a Docker container,\n\u003e pass the following options:\n\u003e\n\u003e - `--cap-add=SYS_PTRACE`  \n\u003e   _(allows the launched process to trace system calls from)_\n\u003e - `--security-opt seccomp=unconfined`  \n\u003e   _(runs the container without the [default security profile][seccomp])_\n\u003e - `--security-opt apparmor=unconfined`  \n\u003e   _(runs the container without the [AppArmor security profile][apparmor])_\n\u003e \n\u003e Without these permissions,\n\u003e DocTest cannot launch the Swift REPL to evaluate code statements.\n\n## Installation\n\n### Homebrew\n\nRun the following command to install using [Homebrew](https://brew.sh/):\n\n```terminal\n$ brew install swiftdocorg/formulae/swift-doctest\n```\n\n### Manually\n\nRun the following commands to build and install manually:\n\n```terminal\n$ git clone https://github.com/SwiftDocOrg/DocTest\n$ cd DocTest\n$ make install\n```\n\n## Usage\n\n```\nOVERVIEW: A utility for syntax testing documentation in Swift code.\n\nUSAGE: swift-doctest \u003cinput\u003e [--swift-launch-path \u003cswift-launch-path\u003e] [--package] [--assumed-filename \u003cassumed-filename\u003e]\n\nARGUMENTS:\n  \u003cinput\u003e                 Swift code or a path to a Swift file\n\nOPTIONS:\n  --swift-launch-path \u003cswift-launch-path\u003e\n                          The path to the swift executable. (default:\n                          /usr/bin/swift)\n  -p, --package           Whether to run the REPL through Swift Package Manager\n                          (`swift run --repl`).\n  --assumed-filename \u003cassumed-filename\u003e\n                          The assumed filename to use for reporting when\n                          parsing from standard input. (default: Untitled.swift)\n  -h, --help              Show help information.\n\n```\n\n## How It Works\n\nDocTest launches and interacts with\nthe Swift \u003cabbr title=\"Read-Eval-Print-Loop\"\u003eREPL\u003c/abbr\u003e,\npassing each code statement through standard input\nand reading its result through standard output and/or standard error.\n\nConsider the following function declaration\nwithin a Swift package:\n\n~~~swift\n/**\n    Returns the sum of two integers.\n\n    ```swift\n    add(1 1) // Returns 3.0\n    ```\n*/\nfunc add(_ a: Int, _ b: Int) -\u003e Int { ... }\n~~~\n\nThere are three problems with the example code\nprovided in the documentation for `add(_:_:)`:\n\n1. It doesn't compile\n   (missing comma separator between arguments)\n2. It suggests an incorrect result\n   (one plus one equals two, not three)\n3. It suggests an incorrect type of result\n   (the sum of two integers is an integer,\n   which isn't expressible by a floating-point literal)\n\nWe can use DocTest to identify these problems automatically\nby adding `\"doctest\"` to the start of the fenced code block.\nThis tells the documentation test runner to evaluate the code sample.\n\n```diff\n- ```swift\n+ ```swift doctest\n```\n\nBy adding an annotation in the format\n`=\u003e \u003c#Value#\u003e`,\nwe can test the expected type and value\nof the expression.\n\n```diff\n- add(1 1) // 3.0\n+ add(1 1) // =\u003e 3.0\n```\n\nRun the `swift-doctest` command\nfrom the root directory of the Swift package\nand passing the path to the file containing the `add(_:_:)` function.\nThis will scan for all of code blocks annotated with\n\u003ccode\u003e```swift doctest\u003c/code\u003e,\nrun them through the Swift REPL,\nand test the output with any annotated expectations.\n\n```terminal\n$ swift doctest path/to/file.swift\nTAP version 13\n1..1\nnot ok 1 - `add(1 1)` did not produce `3.0`\n  ---\n  column: 1\n  file: path/to/file.swift.md\n  line: 1\n  ...\n  \n```\n\n\u003e Test results are reported in [TAP format](https://testanything.org).\n\nSeeing the error,\nwe update the documentation to fix the example.\n\n~~~swift\n/**\n    Returns the sum of two integers.\n\n    ```swift doctest\n    add(1, 1) // =\u003e 2\n    ```\n*/\nfunc add(_ a: Int, _ b: Int) -\u003e Int { ... }\n~~~\n\nIf we re-run the same command as before,\nthe tests now pass as expected.\n\n```terminal\n$ swift doctest path/to/file.swift\nTAP version 13\n1..1\nok 1 - `add(1, 1)` produces `2`\n  ---\n  column: 1\n  file: path/to/file.swift.md\n  line: 1\n  ...\n  \n```\n\n\u003e By the way, you can run `swift-doctest` on Markdown files, too —\n\u003e any code blocks starting with\n\u003e \u003ccode\u003e\u0026#96;\u0026#96;\u0026#96;swift doctest\u003c/code\u003e\n\u003e and ending with \u003ccode\u003e\u0026#96;\u0026#96;\u0026#96;\u003c/code\u003e\n\u003e will be processed.\n\n## License\n\nMIT\n\n## Contact\n\nMattt ([@mattt](https://twitter.com/mattt))\n\n[seccomp]: https://docs.docker.com/engine/security/seccomp/\n[apparmor]: https://docs.docker.com/engine/security/apparmor/\n\n[ci badge]: https://github.com/SwiftDocOrg/DocTest/workflows/CI/badge.svg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSwiftDocOrg%2FDocTest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSwiftDocOrg%2FDocTest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSwiftDocOrg%2FDocTest/lists"}