p0deje/yard-doctest is a server-side project on GitHub with 117 stars, written primarily in Gherkin. Doctests from YARD examples
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
Have you ever wanted to turn your amazing code examples into something that really make sense, is always up-to-date and bullet-proof? Were looking at an amazing Python doctest? Well, look no longer!
Meet YARD::Doctest - simple and magical gem, which automatically parses your @example tags and turn them into tests!
Installation
Add this line to your application's Gemfile:
gem 'yard-doctest'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install yard-doctest
Basic usage
Let's imagine you have the following library:
lib/
cat.rb
dog.rb
Each file contains some class and methods:
# cat.rb
class Cat
# @example
# Cat.word #=> 'meow'
def self.word
'meow'
end
def initialize(can_hunt_dogs = false)
@can_hunt_dogs = can_hunt_dogs
end
# @example Usual cat cannot hunt dogs
# cat = Cat.new
# cat.can_hunt_dogs? #=> false
#
# @example Lion can hunt dogs
# cat = Cat.new(true)
# cat.can_hunt_dogs? #=> true
#
# @example Mutated cat can hunt dogs too
# cat = Cat.new
# cat.instance_variable_set(:@can_hunt_dogs, true) # not part of public API
# cat.can_hunt_dogs? #=> true
def can_hunt_dogs?
@can_hunt_dogs
end
end
# dog.rb
class Dog
# @example
# Dog.word #=> 'meow'
def self.word
'woof'
end
# @example Dogs never hunt dogs
# dog = Dog.new
# dog.can_hunt_dogs? #=> false
def can_hunt_dogs?
false
end
end
You can run tests for all the examples you've documented.
First of all, you need to tell YARD to automatically load yard-doctest (as well as other plugins).
To do so, add yard-doctest as an automatically loaded plugin in your .yardops:
# .yardopts
--plugin yard-doctest
Next, you'll need to create test helper, which will be required before each of your test. Think about it as spec_helper.rb in RSpec, test_helper.rb in Minitest, or env.rb in Cucumber. You should require everything necessary for your examples to run there.
$ touch doctest_helper.rb
# or move it into the `support`, `spec`, or `test` directory
Pretty simple, ain't it? Need more details about the way it runs the tests?
It is actually delegated to amazing minitest and each example is an instance of Minitest::Spec.
Advanced usage
Exceptions
If you want to use example that raises exception, this can be achieved by specifying the correct expected value:
class Calculator
# @example
# divide(1, 0) #=> raise ZeroDivisionError, "divided by 0"
def divide(one, two)
one / two
end
end
The comparison of raised exceptions is being done by string containing the class and message of exceptions. With that said, you have to use the same message in expected value as the one that is used in actual.
Test helper
You can define any methods and instance variables in test helper and they will be available in examples.
For example, if we change the examples for Cat#can_hunt_dogs? like that:
# cat.rb
class Cat
# @example Usual cat cannot hunt dogs
# cat.can_hunt_dogs? #=> false
def can_hunt_dogs?
@can_hunt_dogs
end
end
And run the examples - it will fail because cat is undefined:
$ bundle exec yard doctest
# ...
1) Error:
Cat#can_hunt_dogs?#test_0001_Usual cat cannot hunt dogs:
NameError: undefined local variable or method `cat' for Object:Class
# ...
If you don't want to create new instance of class each time (or include module if you're testing it), you can fix this by defining a method in test helper:
In case you need to do some preparations/cleanup between tests, hooks are at your service to be defined in test helper:
YARD::Doctest.configure do |doctest|
doctest.before do
# this is called before each example and
# evaluated in the same context as example
# (i.e. has access to the same instance variables)
end
doctest.after do
# same as `before`, but runs after each example
end
doctest.after_run do
# runs after all the examples and
# has different context
# (i.e. no access to instance variables)
end
end
There is also a way to limit hooks to specific tests based on class/method name:
YARD::Doctest.configure do |doctest|
doctest.before('MyClass') do
# this will only be called for doctests of `MyClass` class
# and all its methods (i.e. `MyClass.foo`, `MyClass#bar`)
end
doctest.after('MyClass#foo') do
# this will only be called for doctests of `MyClass#foo`
end
doctest.before('MyClass#foo@Example one') do
# this will only be called for example `Example one` of `MyClass#foo`
end
end
Skip
You can skip running some of the tests:
YARD::Doctest.configure do |doctest|
doctest.skip 'MyClass' # will skip doctests for `MyClass` and all its methods
doctest.skip 'MyClass#foo' # will skip doctests for `MyClass#foo`
end
Rake
There is also a Rake task for you:
# Rakefile
require 'yard/doctest/rake'
YARD::Doctest::RakeTask.new do |task|
task.doctest_opts = %w[-v]
task.pattern = 'lib/**/*.rb'
end
$ bundle exec rake yard:doctest
Is it really used?
Well, yeah. A great example of using yard-doctest is watir-webdriver.
Testing
There are some system tests implemented with Aruba:
$ bundle install
$ bundle exec rake cucumber
Contributing
Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don't break it in a future version unintentionally.
Commit, do not mess with Rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
Send me a pull request. Bonus points for topic branches.
The most recent commit recorded on p0deje/yard-doctest was 3.3 years ago, based on the GitHub push timestamp. The repository has 17 forks — one of the better signals of community interest.
How does p0deje/yard-doctest compare to other Backend projects?
p0deje/yard-doctest is tracked by TopGit in the Backend category, with 117 GitHub stars and written in Gherkin. Browse the Backend topic page on TopGit to compare it against similar projects by stars and activity.
How many stars does p0deje/yard-doctest have?
p0deje/yard-doctest has 117 GitHub stars — refresh the page for the live number, or check github.com/p0deje/yard-doctest. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
What is p0deje/yard-doctest?
p0deje/yard-doctest (p0deje/yard-doctest) is a Gherkin project on GitHub. From the project's own README: Doctests from YARD examples
What language is p0deje/yard-doctest written in?
p0deje/yard-doctest is written primarily in Gherkin. GitHub's language field is based on the largest share of bytes in the default branch.
What topics is p0deje/yard-doctest associated with?
GitHub's repository topics for p0deje/yard-doctest: "doctest", "ruby", "yard". TopGit's editorial category is Backend.
Why is p0deje/yard-doctest categorized under Backend?
TopGit places p0deje/yard-doctest in the Backend category based on its GitHub topics and description (tagged: "doctest", "ruby", "yard"). Categories are assigned from real repository metadata, not editorial guesswork.
Read full README in the tab above.
Want a second opinion on yard-doctest?
Ask an AI that can read this page — one click and you get its take on yard-doctest.
/yard-doctest
