{"id":15406788,"url":"https://github.com/dannyben/docspec","last_synced_at":"2025-04-18T03:15:48.711Z","repository":{"id":59152981,"uuid":"214802712","full_name":"DannyBen/docspec","owner":"DannyBen","description":"Inline tests in Markdown documents","archived":false,"fork":false,"pushed_at":"2025-02-18T12:49:54.000Z","size":301,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-18T13:39:56.316Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","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/DannyBen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2019-10-13T10:46:27.000Z","updated_at":"2025-02-18T12:49:56.000Z","dependencies_parsed_at":"2024-07-31T06:19:26.827Z","dependency_job_id":null,"html_url":"https://github.com/DannyBen/docspec","commit_stats":{"total_commits":53,"total_committers":1,"mean_commits":53.0,"dds":0.0,"last_synced_commit":"28a4a21315a815e37b5e60dac3f44942d67f404f"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fdocspec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fdocspec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fdocspec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fdocspec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DannyBen","download_url":"https://codeload.github.com/DannyBen/docspec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241367916,"owners_count":19951444,"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-10-01T16:25:23.389Z","updated_at":"2025-03-01T12:33:11.137Z","avatar_url":"https://github.com/DannyBen.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Docspec\n\n[![Gem Version](https://badge.fury.io/rb/docspec.svg)](https://badge.fury.io/rb/docspec)\n[![Build Status](https://github.com/DannyBen/docspec/workflows/Test/badge.svg)](https://github.com/DannyBen/docspec/actions?query=workflow%3ATest)\n[![Maintainability](https://api.codeclimate.com/v1/badges/e0c15c1f33fa4aa45f70/maintainability)](https://codeclimate.com/github/DannyBen/docspec/maintainability)\n\nDocspec lets you reuse your Markdown documents as the unit tests for your\nRuby library.\n\n---\n\n\n## Installation\n\n```\n$ gem install docspec\n```\n\n\n## Demo\n\n![Demo](demo/cast.gif)\n\n\n## Usage\n\nDocspec expects one or more Markdown files with embedded code snippets to \ntest.\n\nCode snippets should be enclosed in a `ruby` or `shell` code fence:\n\n```ruby\nputs \"code to test (should output something)\"\n#=\u003e code to test (should output something)\n```\n\nThis document itself serves as the test suite for this gem, so you can take a\nlook at its source.\n\n\n### Testing with the `docspec` command line\n\n- Running `docspec` without arguments will run on `./README.md`\n- Running `docspec` with a filename, will run on that filename\n- Running `docspec` with a directory, will run on all the markdown files in\n  that directory.\n\nIf your bundle includes the `simplecov` gem, it will be automatically loaded\nand generate coverage report in the `coverage` directory.\n\n\n### Testing from Ruby code\n\n```ruby\n# Running from Ruby code\ndocument = Docspec::Document.from_file 'test/sample.md'\ndocument.test\n#=\u003e pass : Sample Test\n\nputs document.success?\n#=\u003e true\n```\n\n\n\n\n```ruby\n# Test a file using the CLI class\nrunner = Docspec::CLI.new 'test/sample.md'\nsuccess = runner.run\n#=\u003e file : test/sample.md\n#=\u003e pass : Sample Test\n#=\u003e \n#=\u003e 1 tests, 0 failed\n```\n\n\n```ruby\n# Test multiple folders/files using the CLI class\nrunner = Docspec::CLI.new 'test', 'test/sample.md'\nsuccess = runner.run\n#=\u003e file : test/folder/another.md\n#=\u003e pass : Another Sample Test\n#=\u003e \n#=\u003e file : test/sample.md\n#=\u003e pass : Sample Test\n#=\u003e \n#=\u003e file : test/sample2.md\n#=\u003e pass : echo shell\n#=\u003e void : echo shell\n#=\u003e pass : puts \"ruby\"\n#=\u003e void : puts \"ruby\"\n#=\u003e \n#=\u003e file : test/sample.md\n#=\u003e pass : Sample Test\n#=\u003e\n#=\u003e 7 tests, 0 failed\n\n```\n\n\n\n## Examples\n\nCode examples that you want to test, should output something to stdout. \nSpecify the expected output by prefixing it with `#=\u003e`:\n\n```ruby\n# The first comment line is an optional label\nputs 'hello world'.upcase\n#=\u003e HELLO WORLD\n```\n\nIf an example raises an exception, the captured output will be the `#inspect`\nstring of that exception:\n\n```ruby\n# Exceptions are captured\nputs \"hello\".camel_case\n#=\u003e #\u003cNoMethodError: undefined method ...\n```\n\nUsing three dots at the beginning or end of the expected output (like in the\nabove example) will perform a partial match:\n\n```ruby\n# Ellipsis match\nputs \"the beginning will be ignored as well as the end\"\n#=\u003e ... will be ignored ...\n```\n\nYour code and expected output can contain multiple lines of code:\n\n```ruby\n# Multiple lines of code\nstring = \"hello\"\n3.times do \n  puts string\nend\n#=\u003e hello\n#=\u003e hello\n#=\u003e hello\n```\n\nand you can alternate between code and expected output:\n\n```ruby\n# Interleaving code and output \nputs 2 + 3\n#=\u003e 5\n\nputs 2 - 3\n#=\u003e -1\n```\n\nor have the expected output in the same line as its code:\n\n```ruby\nputs 2 * 3    #=\u003e 6\nputs 'works'  #=\u003e works\n```\n\nThe first line of the example may contain specially formatted flags. Flags \nare always formatted like this: `[:flag_name]`. \n\nThe `[:ignore_failure]` flag allows the example to fail. It will show the \nfailure in the output, but will not elevate the exit status to a failure \nstate:\n\n```ruby\n# This example may fail [:ignore_failure]\n# Due to the :ignore_failure flag, it will show the failure diff, but will\n# not be considered a failure in the exit status.\nputs 'hello world'.upcase\n#=\u003e hello world\n```\n\nAnother available flag, is the `[:skip]` flag, which will omit the example\nfrom the test run:\n\n```ruby\n# [:skip]\nthis will not be executed\n```\n\nSometimes it is useful to build the example over several different code \nblocks. To help achieve this, docspec will treat any example that does not \nexpect any output (no `#=\u003e markers`) as a code that needs to be executed\nbefore all subsequent examples:\n\n```ruby\n# Define functions or variables for later use\ndef create_caption(text)\n  [text.upcase, (\"=\" * text.length)].join \"\\n\"\nend\n\nmessage = 'tada!'\n```\n\nAll the examples below this line, will have the above function available:\n\n```ruby\n# Use a previously defined function or variable\nputs create_caption message\n#=\u003e TADA!\n#=\u003e =====\n```\n\n\nExamples marked with a `shell` code fence will be executed by the\nshell, and not by ruby:\n\n```shell\n# Shell commands\necho hello world\n#=\u003e hello world\n```\n\nand they also support chaining of examples:\n\n```shell\n# Prepend shell example to all subsequent shell examples\n# (since this example does not define an expected output)\nSOME_ENV_VAR=yes\n```\n\n```shell\necho $SOME_ENV_VAR\n#=\u003e yes\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdannyben%2Fdocspec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdannyben%2Fdocspec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdannyben%2Fdocspec/lists"}