{"id":22980953,"url":"https://github.com/rubyworks/qed","last_synced_at":"2025-10-05T22:57:44.198Z","repository":{"id":638632,"uuid":"280186","full_name":"rubyworks/qed","owner":"rubyworks","description":"Quality Ensured Documentation","archived":false,"fork":false,"pushed_at":"2015-03-01T22:09:33.000Z","size":3048,"stargazers_count":31,"open_issues_count":17,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-06T16:43:06.848Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://rubyworks.github.com/qed","language":"Ruby","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/rubyworks.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2009-08-17T18:28:26.000Z","updated_at":"2024-09-21T18:16:46.000Z","dependencies_parsed_at":"2022-07-07T13:40:45.410Z","dependency_job_id":null,"html_url":"https://github.com/rubyworks/qed","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyworks%2Fqed","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyworks%2Fqed/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyworks%2Fqed/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyworks%2Fqed/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rubyworks","download_url":"https://codeload.github.com/rubyworks/qed/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229773540,"owners_count":18122031,"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-12-15T01:46:16.621Z","updated_at":"2025-10-05T22:57:39.175Z","avatar_url":"https://github.com/rubyworks.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ruby Q.E.D.\n\n[Homepage](http://rubyworks.github.com/qed) /\n[Documentation](http://rubydoc.info/gems/qed/frames) /\n[Report Issue](http://github.com/rubyworks/qed/issues) /\n[Development](http://github.com/rubyworks/qed) /\n[Mailing list](http://groups.google.com/group/rubyworks-mailinglist) \u0026nbsp; \u0026nbsp;\n[![Build Status](https://secure.travis-ci.org/rubyworks/qed.png)](http://travis-ci.org/rubyworks/qed)\n[![Gem Version](https://badge.fury.io/rb/qed.png)](http://badge.fury.io/rb/qed)\n\n\n## Introduction\n\nQ.E.D. is an abbreviation for the well known Latin phrase \"Quod Erat Demonstrandum\",\nliterally \"which was to be demonstrated\", which is oft written in its abbreviated\nform at the end of a mathematical proof or philosophical argument to signify\na successful conclusion. And so it is too for Ruby Q.E.D., though it might as easily\nbe taken to stand for \"Quality Ensured Documentation\". \n\nQED is in fact both a test framework and a documentation system for Ruby\ndevelopers. QED sits somewhere between lower-level testing tools like Test::Unit\nand grandiose requirement specifications systems like Cucumber. In practice it\nworks exceptionally well for \u003ci\u003eAPI-Driven Design\u003c/i\u003e, which is especially\nuseful when designing reusable libraries, but it can be used to test code at\nany level of abstraction, from unit test to systems tests.\n\n\n## Features\n\n* Write tests and documentation in the same breath!\n* Demos can be RDoc, Markdown or any other conforming text format.\n* Can use any BRASS compliant assertion framework, such as the the excellent AE (Assertive Expressive) library.\n* Data and Table macros allows large sets of data to be tested by the same code.\n* Documentation tool provides nice output with jQuery-based TOC.\n\n\n## Synopsis\n\n### Assertion Syntax\n\nQED can use any BRASS compliant assertions framework. Simply require the library in\nones applique (see below). Traditionally this has been the AE (Assertive Expressive) library,\nwhich provides an elegant means to make assertions. To give a quick overview, assertion\ncan be written as:\n\n    4.assert == 5\n\nIn this example, because 4 != 5, this expression will raise an Assertion\nexception. QED's Runner class is thus just a means of running and capturing\ncode blocks containing such assertions.\n\nYou can learn more about BRASS and AE at http://rubyworks.github.com/brass and\nhttp://rubyworks.github.com/ae, repectively.\n\n### Document Structure\n\nQED documents are simply text files called *demonstrandum* (demos for short).\nBecause they largely consist of free-form descriptive text, they are a practice\npure Literate Programming. For example:\n\n    = Example\n\n    Shows that the number 5 does not equal 4.\n\n        5.assert! == 4\n\n    But in fact equals 5.\n\n        5.assert == 5\n\nIn this example RDoc was chosen for the document format. However, almost any\ntext format can be used. The only necessary distinction is that description text\nalign to the left margin and all code be indented, although QED does recognize\nRDoc and Markdown single-line style headers, so any format that supports\nthose (which covers many markup formats in use today) will have mildly\nimproved console output. In any case, the essential take away here is that\nQED *demonstrandum* are simply descriptive documents with interspersed \nblocks of example code.\n\nGive this design some thought. It should become clear that this approach is\nespecially fruitful in that it allows *documentation* and *specification*\nto seamlessly merge into a unified *demonstration*. \n\n### Running Demonstrations\n\nIf we were to run the above document through QED in verbatim mode the output\nwould be identical (assuming we did not make a typo and the assertions passed).\nIf there were errors or failures, we would see information detailing each.\n\nTo run a document through QED, simply use the +qed+ command.\n\n  $ qed -v demo/01_example.rdoc\n\nThe `-v` option specifies verbatim mode, which outputs the entire\ndocument.\n\nNotice we placed the QED document in a `demo/` directory. This is the\ncanonical location, but there is no place that demonstrations have to go. They\ncan be placed anywhere that is preferred. However, the `qed` command\nwill look for `qed/`, `demo/`, `demos/` and `spec/`, in that order, if no\npath is given.\n\nAlso notice the use of ``01_`` prefix in front of the file name.\nWhile this is not strictly necessary, QED sorts the documents, so it helps order\nthe documents nicely, in particular when generating QED documentation (\"QEDocs\").\n\n### Utilizing Applique\n\nQED demonstrandum descriptive text is not strictly passive explanation. Using\npattern matching techniques, document phrases can trigger underlying actions.\nThese actions provide a support structure for running tests called the *applique*.\n\nCreating an applique is easy. Along with your QED scripts, to which the \napplique will apply, create an `applique/` directory. In this\ndirectory add Ruby scripts. When you run your demos every Ruby script in \nthe directory will be automatically loaded.\n\nWithin these applique scripts *advice* can be defined. Advice can be\neither *event advice*, which is simply triggered by some fixed cycle\nof running, such as `Before :each` or `After :all`,\nand *pattern advice* which are used to match against descriptive\nphrases in the QED demos. An example would be:\n\n    When \"a new round is started\" do\n      @round = []\n    end\n\nSo that whenever the phrase \"a new round is started\" appears in a demo,\nthe @round instance variable with be reset to an empty array.\n\nIt is rather amazing what can be accomplished with such a system,\nbe sure to look at QED's own demonstrandum to get a better notion of\nhow you can put the the system to use.\n\n### Configuration\n\nConfiguration for `qed` can be placed in a `etc/qed.rb` file, or if\nyou are using Rails, in `config/qed.rb`. Here's a generally useful\nexample of using SimpleCov to generate a test coverage report when\nrunning your QED demos.\n\n    QED.configure 'coverage' do\n      require 'simplecov'\n      SimpleCov.start do\n        coverage_dir 'log/coverage'\n      end\n    end\n\nYou can then use the profile via the `-p/--profile` option on the command line:\n\n    $ qed -p coverage\n\nOr by setting the `profile` environment variable.\n\n    $ profile=coverage qed\n\nQED can also use the [RC](http://rubyworks.github.com/rc) gem to handle\nconfiguration. Be sure to `gem install rc` and then add this to `.rubyrc`\nor `Config.rb` file of the same effect as given above.\n\n    config :qed, :profile=\u003e:coverage do\n      require 'simplecov'\n      SimpleCov.start do\n        coverage_dir 'log/coverage'\n      end\n    end\n\n### Generating Documentation\n\nTo generate documentation from QED documents, use the +qedoc+ command.\n\n    $ qedoc --output doc/qedoc --title \"Example\" demo/*.rdoc\n\nWhen documenting, QED recognizes the format by the file extension and \ntreats it accordingly. An extension of `.qed` is treated the same\nas `.rdoc`.\n\nUse the `--help` options on each command to get more information\non the use of these commands.\n\n\n## Requirements\n\nQED depends on the following external libraries:\n\n* [BRASS](http://rubyworks.github.com/brass) - Assertions System\n* [ANSI](http://rubyworks.github.com/ansi) - ANSI Color Codes\n* [RC](http://rubyworks.github.com/rc) - Runtime Configuration\n* [Facets](http://rubyworks.github.com/facets) - Core Extensions\n\nThese will be automatically installed when installing QED via RubyGems,\nif they are not already installed.\n\nOptional libraries that are generally useful with QED.\n\n* [AE](http://rubyworks.github.com/ae) - Assertions Framework\n\nInstall these individually and require them in your applique to use.\n\n\n## Development\n\n### Testing\n\nQED uses itself for testing, which can be a bit tricky. But works fine for\nthe most part. In the future we may add some addition tests via another\ntest framework to ensure full coverage. But for now QED is proving sufficient.\n\nTo run the tests, use `qed` command line tool --ideally use `$ ruby -Ilib bin/qed`\nto ensure the current version of QED is being used.\n\nFor convenience, use `$ fire spec` to run the test specifications. To also \ngenerate a test coverage report use `$ fire spec:cov`.\n\n\n## Copyrights\n\n(BSD-2-Clause license)\n\nCopyright (c) 2009 Rubyworks. All rights reserved.\n\nSee LICENSE.txt for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubyworks%2Fqed","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frubyworks%2Fqed","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubyworks%2Fqed/lists"}