methadone 1.9.5 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 16b7b785cbc498169dcd41650a52eba9aba67e33
-  data.tar.gz: 3d1177ef34caba30beb4808ba3615d82cb0cadf4
+SHA256:
+  metadata.gz: b21a9100411d2fd3589c39cd7e9db9f90712eb37d40748556dcfe33d760bcdaa
+  data.tar.gz: db454cb7ccda0705702cc4cbd888dad9b920b50a15e8d3026450239227e303aa
 SHA512:
-  metadata.gz: cb015a80a55b3a454b59872ab84890de5ce89000009bf81137a0ca97724ad73601080bd7e431376797347f5ecd53e82749b9a4e051bd742f30e76dd649aea2f6
-  data.tar.gz: 2198036125cd7af64763e7d59a77fe561cd7e8dd4e7be45dc171c7a2bae4f0970ee6ee346a85b1a7aa03651013776827e6b57c5e4c5e96b62be98f2dc4b1fe11
+  metadata.gz: f7add29c4a7a948f22e98d04f364591b602f96665f4451005dd2d0b6ef8dab0a8ebf01a54b177d04224b8e1e88e500f7e26b756e5451ea5491fd70ba20c54e8d
+  data.tar.gz: 31afecc9be7254afc979904629684ac3af7fa5b49d3189247e5f073964ce8c1a86cabfe1edd5b1aacb76fbcad3ca9a9e57d0f58498cf453d484cac22b15fdc38

data/.gitignore

@@ -13,3 +13,4 @@ T_KICK_THE_BASH_HABIT_WITH_RUBY_AND_METHADONE.itmsp
 bin/cukedoc
 methadone.wiki
 tut
+.idea

data/.ruby-version

@@ -1 +1 @@
-2.3.1
+2.5.1

data/.travis.yml

@@ -3,8 +3,5 @@ notifications:
     on_success: always
 script: 'bundle exec rake'
 rvm:
-  - 2.1.10
-  - 2.2.6
-  - 2.3.3
-  - 2.4.0
-  - jruby-19mode
+  - 2.4.3
+  - 2.5.1

data/README.rdoc

@@ -16,10 +16,12 @@ Toward that end, this gem provides:
 * A lightweight DSL to create your command-line interface, that loses none of <tt>OptionParser</tt>'s power.
 * A simplified means of running external commands that has better error handling and diagnostics.
 * Simplified zero-config logging that is a better-than-<tt>puts</tt> <tt>puts</tt>.
-* Cucumber Steps, built on Aruba, to allow you to test-drive your command-line app development.
+* Support for integration-testing your CLI using Test::Unit
 
 == Tutorial
 
+**This tutorial is somewhat outdated, but generally still applies**
+
 http://a1.mzstatic.com/us/r30/Publication/v4/2c/f7/90/2cf7902f-f709-9125-c73d-87311216527d/MethadoneTutorial.225x225-75.jpg
 
 {Tutorial for your iPad}[http://itunes.apple.com/us/book/kick-bash-habit-ruby-methadone/id515825242?ls=1] - This is a *free* iBooks interactive ebook that contains a step-by-step tutorial on making an awesome app with Methadone, including screencasts.
@@ -31,11 +33,13 @@ http://a1.mzstatic.com/us/r30/Publication/v4/2c/f7/90/2cf7902f-f709-9125-c73d-87
 
 == Platforms
 
-In general, we try to support {supported MRI Rubies}[https://www.ruby-lang.org/en/downloads/] as well as JRuby, however see the {Travis config file}[./.travis.yml] for specifics.
+This library only supports the latest versions of Ruby. JRuby support has been too difficult to keep up with, though the library should work for JRuby.
+
+See the {Travis config file}[./.travis.yml] for specifics.
 
 == Bootstrapping a new CLI App
 
-The +methadone+ command-line app will bootstrap a new command-line app, setting up a proper gem structure, unit tests, and cucumber-based tests with aruba.
+The +methadone+ command-line app will bootstrap a new command-line app, setting up a proper gem structure, unit tests, and integration tests.
 
 It assumes you are using a standard Ruby development environment, which includes:
 
@@ -47,41 +51,83 @@ _(Note that apps *powered* by this gem have no particular runtime dependencies a
 
 
     $ methadone --help
+    Usage: methadone [options] app_name
+
+    Kick the bash habit by bootstrapping your Ruby command-line apps
+
+    v2.0.0
+
+    Options:
+        -h, --help                       Show command line help
+            --force                      Overwrite files if they exist
+            --[no-]readme                [Do not ]produce a README file
+            --rspec                      Generate RSpec unit tests instead of Test::Unit
+        -l, --license LICENSE            Specify the license for your project
+                                         (mit|apache|gplv2|gplv3|custom|NONE)
+            --log-level LEVEL            Set the logging level
+                                         (debug|info|warn|error|fatal)
+                                         (Default: info)
+            --version                    Show help/version info
+
+    Arguments:
+
+        app_name
+            Name of your app, which is used for the gem name and executable name
+
+
+
+
+
     Usage: methadone [options] app_name
             --force                      Overwrite files if they exist
-    $ methadone newgem
-    $ cd newgem
-    $ bundle
-    $ rake
-    1 tests, 1 assertions, 0 failures, 0 errors, 0 skips
-    1 scenario (1 passed)
-    3 steps (3 passed)
-    $ cat features/newgem.feature
-    Feature: My bootstrapped app kinda works
-      In order to get going on coding my awesome app
-      I want to have aruba and cucumber setup
-      So I don't have to do it myself
-
-      Scenario: App just runs
-        When I run `newgem --help`
-        Then the exit status should be 0
-        And the output should contain:
-        """
-        Usage: newgem [options]
-        """
+    $ methadone myapp -l mit
+    $ cd myapp
+    $ bundle install
+    ...
+    $ bundle exec rake
+    Started
+    .
+    Finished in 0.000499 seconds.
+    -----------------------------------------------------------------------------------------
+    1 tests, 1 assertions, 0 failures, 0 errors, 0 pendings, 0 omissions, 0 notifications
+    100% passed
+    -----------------------------------------------------------------------------------------
+    2004.01 tests/s, 2004.01 assertions/s
+    Started
+    .
+    Finished in 0.298281 seconds.
+    -----------------------------------------------------------------------------------------
+    1 tests, 8 assertions, 0 failures, 0 errors, 0 pendings, 0 omissions, 0 notifications
+    100% passed
+    -----------------------------------------------------------------------------------------
+    3.35 tests/s, 26.82 assertions/s
+
+    $ cat test/integration/test_cli.rb
+    require "methadone/test/base_integration_test"
+
+    class TestSomething < Methadone::BaseIntegrationTest
+      def test_truth
+        stdout,stderr,results = run_app("myapp","--help")
+        assert_banner(stdout, "myapp", takes_options: true, takes_arguments: false)
+        assert_option(stdout,"-h", "--help")
+        assert_option(stdout,"--version")
+        assert_oneline_summary(stdout)
+      end
+    end
+
 
 Basically, this sets you up with all the boilerplate that you *should* be using to write a command-line app.  Specifically, you get:
 
 * Gemified project (based on <tt>bundle gem</tt>)
 * An executable using Methadone::Main to outline your new app
 * <tt>Test::Unit</tt> test task set up and an empty unit test.
-* Aruba/Cucumber set up with a basic feature that exercise your executable
+* <tt>Test::Unit</tt> integration tests with some of methadone's assertions to let you drive your CLI's development
 * The outline of a README
 * An optional license included
 
 == DSL for your <tt>bin</tt> file
 
-A canonical <tt>OptionParser</tt> driven app has a few problems with it structurally that Methadone can solve:
+A canonical <tt>OptionParser</tt>-driven app has a few problems with it structurally that Methadone can solve:
 
 * Backwards organization - main logic is at the bottom of the file, not the top
 * Verbose to use +opts.on+ just to set a value in a +Hash+
@@ -117,7 +163,7 @@ This isn't a replacement for Open3 or ChildProcess, but a way to easily "do the
 
 == Zero-Config Logging
 
-Chances are, your code is littered with <tt>STDERR.puts</tt> on a good day, and nothing on a bad day.  You probably also have a bunch of debug <tt>puts</tt> calls that you have commented out.  Logging is extremely helpful in understand how your app is behaving (or how it behaved in the past).  Logging can be a pain to set up, and can also make it hard to give the user at the command-prompt a good experience.
+Chances are, your code is littered with <tt>STDERR.puts</tt> on a good day, and nothing on a bad day.  You probably also have a bunch of debug <tt>puts</tt> calls that you have commented out.  Logging is extremely helpful in understanding how your app is behaving (or how it behaved in the past).  Logging can be a pain to set up, and can also make it hard to give the user at the command-prompt a good experience.
 
 Methadone::CLILogger is designed to handle this.  It's a proper subclass of Ruby's built-in <tt>Logger</tt> with a few enhancements:
 
@@ -129,32 +175,14 @@ Methadone::CLILogger is designed to handle this.  It's a proper subclass of Ruby
 
 See {CLILogger's rdoc}[http://davetron5000.github.com/methadone/rdoc/classes/Methadone/CLILogger.html] and then {CLILogging's}[http://davetron5000.github.com/methadone/rdoc/classes/Methadone/CLILogging.html] for more.
 
-
 Currently, there are classes that assist in directing output logger-style to the right place; basically ensuring that errors go to +STDERR+ and everything else goes to +STDOUT+.  All of this is, of course, configurable
 
-== Cucumber Steps
-
-Methadone uses aruba[http://www.github.com/cucumber/aruba] for BDD-style testing with cucumber. This library has some awesome steps, and Methadone provides additional, more opinionated, steps.  
-
-=== Example
-
-Here's an example from methadone's own tests:
-
-    Scenario: Help is properly documented
-      When I get help for "methadone"
-      Then the exit status should be 0
-      And the following options should be documented:
-        |--force|
-      And the banner should be present
-      And the banner should include the version
-      And the banner should document that this app takes options
-      And the banner should document that this app's arguments are:
-        |app_name|which is required|
-        |dir_name|which is optional|
+== Integration Tests
 
-See Methadone::Cucumber or its {rdoc}[http://davetron5000.github.com/methadone/rdoc/classes/Methadone/Cucumber.html] for a list of all the steps provided.
+Methadone provides some basic features for executing your CLI and asserting things about it.  Methadone::Test::IntegrationTestAssertions documents these.
 
 == Contributing
 
 * Feel free to file an issue, even if you don't have time to submit a patch
 * Please try to include a test for any patch you submit.  If you don't include a test, I'll have to write one, and it'll take longer to get your code in.
+* This is not intended to support “command-suite” style CLIs.  See {GLI}[http://naildrivin5.com/gli] if that's what you want.

data/Rakefile

@@ -2,19 +2,37 @@ require 'sdoc'
 require 'bundler'
 require 'rake/clean'
 require 'rake/testtask'
-require 'cucumber'
-require 'cucumber/rake/task'
 
 include Rake::DSL
 
 Bundler::GemHelper.install_tasks
 
-desc 'run tests'
+desc 'run unit tests'
 Rake::TestTask.new do |t|
   t.libs << "lib"
-  t.libs << "test"
-  t.ruby_opts << "-rrubygems"
-  t.test_files = FileList['test/test_*.rb'] + FileList['test/execution_strategy/test_*.rb']
+  t.libs << "test/unit"
+  test_file = ENV["TEST"]
+  ENV.delete("TEST")
+  t.test_files = if test_file
+                   [test_file]
+                 else
+                   FileList['test/unit/test_*.rb'] +
+                     FileList['test/unit/execution_strategy/test_*.rb'] +
+                     FileList['test/unit/test/test_*.rb']
+                 end
+end
+
+desc 'run integration tests'
+Rake::TestTask.new("test:integration") do |t|
+  t.libs << "lib"
+  t.libs << "test/integration"
+  test_file = ENV["TEST"]
+  ENV.delete("TEST")
+  t.test_files = if test_file
+                   [test_file]
+                 else
+                   FileList['test/integration/test_*.rb']
+                 end
 end
 
 desc 'build rdoc'
@@ -70,29 +88,7 @@ task :hack_css do
     end
   end
 end
-if RUBY_PLATFORM == 'java'
-task :features do
-  puts "Aruba doesn't work on JRuby; cannot run features"
-end
-task 'features:wip' => :features
-else
-CUKE_RESULTS = 'results.html'
-CLEAN << CUKE_RESULTS
-Cucumber::Rake::Task.new(:features) do |t|
-  tag_opts = ' --tags ~@pending'
-  tag_opts = " --tags #{ENV['TAGS']}" if ENV['TAGS']
-  t.cucumber_opts = "features --format html -o #{CUKE_RESULTS} --format pretty -x -s#{tag_opts}"
-  t.fork = false
-end
-
-Cucumber::Rake::Task.new('features:wip') do |t|
-  tag_opts = ' --tags ~@pending'
-  tag_opts = ' --tags @wip'
-  t.cucumber_opts = "features --format html -o #{CUKE_RESULTS} --format pretty -x -s#{tag_opts}"
-  t.fork = false
-end
-end
 
 CLEAN << "coverage"
 CLOBBER << FileList['**/*.rbc']
-task :default => [:test, :features]
+task :default => [:test, "test:integration"]

data/bin/methadone

@@ -28,6 +28,9 @@ main do |app_name|
       file =~ /\.rb$/ && file !~ /version.rb$/
     }.first
   end
+  rm_rf "#{gemname}/spec"   # Don't want the default RSpec droppings
+  rm_rf "#{gemname}/.rspec"
+
   require_file = gemname if require_file.nil?
   require_file.gsub!(/^.*lib\//,'')
 
@@ -37,7 +40,7 @@ main do |app_name|
 
   rspec = options[:rspec]
 
-  ["Rakefile", ".gitignore", "features/support/env.rb"].each do |file|
+  ["Rakefile", ".gitignore", ].each do |file|
     copy_file file, :binding => binding
   end
 
@@ -46,7 +49,8 @@ main do |app_name|
     copy_file "spec/something_spec.rb", :from => :rspec, :binding => binding
   else
     template_dirs_in(:test_unit).each  { |dir| mkdir_p dir }
-    copy_file "test/tc_something.rb", :from => :test_unit, :binding => binding
+    copy_file "test/unit/test_something.rb", :from => :test_unit, :binding => binding
+    copy_file "test/integration/test_cli.rb", :from => :test_unit, :binding => binding
   end
 
 
@@ -71,18 +75,21 @@ main do |app_name|
   else
     gemspec_content.gsub!(/(^\s*#{gem_variable}\.name\s*=\s*.*)/,"\\1\n#{"  #{gem_variable}.license".ljust(20)} = #{license.to_s.inspect.upcase}")
   end
+  # RubyGems won't deal with a gemspec in this state and so Bundler won't even
+  # work at all.  This is not helpful, so replace the magic keys its looking for
+  # with something else
+  gemspec_content.gsub!(/TODO/,"to-do")
+  gemspec_content.gsub!(/FIXME/,"fix me")
+  gemspec_content.gsub!(/^.*\.homepage.*$/,"")
   File.open(gemspec,'w') {|f| f.write gemspec_content }
 
 
   copy_file "README.rdoc", :binding => binding if using_readme
 
-  copy_file "features/executable.feature", :as => "#{gemname}.feature", :binding => binding
-  copy_file "features/step_definitions/executable_steps.rb", :as => "#{gemname}_steps.rb"
   copy_file "bin/executable", :as => gemname, :executable => true, :binding => binding
 
   add_to_file gemspec, [
     "  #{gem_variable}.add_development_dependency('rdoc')",
-    "  #{gem_variable}.add_development_dependency('aruba')",
     "  #{gem_variable}.add_dependency('methadone', '~> #{Methadone::VERSION}')",
   ], :before => /^end\s*$/
   ruby_major,ruby_minor,ruby_patch = RUBY_VERSION.split(/\./).map(&:to_i)
@@ -98,6 +105,7 @@ main do |app_name|
     "  #{gem_variable}.add_development_dependency('rspec', '~> 3')",
     ], :before => /^end\s*$/
   end
+  FileUtils.rm_f "README.md", verbose: true
 
   sh! %q(git add --all .)
 end

data/lib/methadone.rb

@@ -12,4 +12,4 @@ require 'methadone/execution_strategy/open_4'
 require 'methadone/execution_strategy/rbx_open_4'
 require 'methadone/execution_strategy/jvm'
 require 'methadone/sh'
-# Note: DO NOT require cli.rb OR cucumber.rb here
+# Note: DO NOT require cli.rb, cucumber.rb, or anything in test/ here

data/lib/methadone/cli_logger.rb

@@ -100,7 +100,6 @@ module Methadone
 
     def level=(level)
       super(level)
-      current_error_level = @stderr_logger.level
       if (level > DEFAULT_ERROR_LEVEL) && @split_logs
         @stderr_logger.level = level
       end

data/lib/methadone/cli_logging.rb

@@ -48,7 +48,7 @@ module Methadone
     def change_logger(new_logger)
       raise ArgumentError,"Logger may not be nil" if new_logger.nil?
       @@logger = new_logger
-      @@logger.level = @log_level if @log_level
+      @@logger.level = @log_level if defined?(@log_level) && @log_level
     end
 
     alias logger= change_logger

data/lib/methadone/cucumber.rb

@@ -1,4 +1,8 @@
 module Methadone
+  #
+  # **NOTE!** Cucumber is not recommened or supported by methadone, as Aruba has diverged too much. This
+  # file is left here to allow you to update methadone but still use Cucumber & Aruba on older versions.
+  #
   # By <tt>require</tt>'ing <tt>methadone/cucumber</tt> in your Cucumber setup (e.g. in <tt>env.rb</tt>), you
   # gain access to the steps defined in this file.  They provide you with the following:
   #

data/lib/methadone/main.rb

@@ -325,6 +325,8 @@ module Methadone
     end
 
     def add_defaults_to_docs
+      @env_var = nil unless defined? @env_var
+      @rc_file = nil unless defined? @rc_file
       if @env_var && @rc_file
         opts.separator ''
         opts.separator 'Default values can be placed in:'
@@ -351,7 +353,7 @@ module Methadone
     end
 
     def set_defaults_from_rc_file
-      if @rc_file && File.exists?(@rc_file)
+      if @rc_file && File.exist?(@rc_file)
         File.open(@rc_file) do |file|
           parsed = begin
                      YAML::load(file)
@@ -392,6 +394,7 @@ module Methadone
 
     # Handle calling main and trapping any exceptions thrown
     def call_main
+      @leak_exceptions = nil unless defined? @leak_exceptions
       @main_block.call(*ARGV)
     rescue Methadone::Error => ex
       raise ex if ENV['DEBUG']

data/lib/methadone/test/base_integration_test.rb

@@ -0,0 +1,29 @@
+require "test/unit"
+require "fileutils"
+require "pathname"
+require "tmpdir"
+require "open3"
+
+require_relative "integration_test_assertions"
+
+# Clean test should be setting this
+$FOR_TESTING_ONLY_SKIP_STDERR = false
+
+class Methadone::BaseIntegrationTest < Test::Unit::TestCase
+  include FileUtils
+  include Methadone::IntegrationTestAssertions
+
+  # Run your app, capturing stdout, stderr, and process status.
+  # app_name:: Your bin name, without `bin/`
+  # args:: CLI args as a string
+  # allow_failure:: if true, this will return even if the app invocation fails.  If false (the default), blows up if things go
+  # wrong.
+  def run_app(app_name, args, allow_failure: false)
+    command = "bin/#{app_name} #{args}"
+    stdout,stderr,results = Open3.capture3(command)
+    if @allow_failure && !results.success?
+      raise "'#{command}' failed!: #{results.inspect}\n\nSTDOUT {\n#{stdout}\n} STDERR {\n#{stderr}\n} END"
+    end
+    [stdout,stderr,results]
+  end
+end

data/lib/methadone/test/integration_test_assertions.rb

@@ -0,0 +1,63 @@
+module Methadone::IntegrationTestAssertions
+  # Assert that a file's contents contains one or more regexps
+  #
+  # filename:: The file whose contents to check
+  # contains:: either a regexp or array of regexpts that the file's contents must match
+  def assert_file(filename, contains:)
+    contents = File.read(filename)
+    Array(contains).each do |regexp|
+      assert_match(regexp,contents,"Expected #{filename} to contain #{regexp}")
+    end
+  end
+
+  # Assert that the stdout contains an appropriate banner for your app
+  #
+  # stdout:: The standard out, presumably of running `«your-app» --help`
+  # bin_name:: The binary name of your app 
+  # takes_options:: set this to true if your app should take options
+  # takes_arguments:: set this to a hash of the arguments your app should take, with the key being the arg name and the value
+  # being either `:required` or `:optional`
+  def assert_banner(stdout, bin_name, takes_options: , takes_arguments: {})
+    if takes_options
+      assert_match(/Options/, stdout)
+      if takes_arguments == false || takes_arguments.empty?
+        assert_match(/Usage: #{Regexp.escape(bin_name)}.*\[options\]\s*$/,stdout)
+      else
+        expected_args = takes_arguments.map { |arg, required|
+          if required == :required
+            arg.to_s
+          else
+            "[#{arg}]"
+          end
+        }.join(" ")
+
+        assert_match(/Usage: #{Regexp.escape(bin_name)}.*\[options\]\s*#{Regexp.escape(expected_args)}$/,stdout)
+      end
+    else
+      assert_match(/Usage: #{Regexp.escape(bin_name)}\s*$/,stdout)
+    end
+  end
+
+  # Assert that your app takes the given option(s)
+  #
+  # stdout:: The standard out, presumably of running `«your-app» --help`
+  # options:: options your app should take.  Put the literal value in here e.g. `--foo` or `--[no-]bar`.  The array form is to
+  # allow you to assert long and short options for readable tests:
+  #
+  #     assert_option(stdout, "--version")
+  #     assert_option(stdout, "-h", "--help")
+  def assert_option(stdout, *options)
+    options.each do |option|
+      assert_match(/#{Regexp.escape(option)}/,stdout)
+    end
+  end
+
+  # Assert that your app has a one-line summary
+  # stdout:: The standard out, presumably of running `«your-app» --help`
+  def assert_oneline_summary(stdout)
+    output = stdout.split(/\n/)
+    assert output.size >= 3, "Expected 3 or more lines:\n#{stdout}"
+    assert_match(/^\s*$/,output[1],"Should be a blank line after the banner")
+    assert_match(/^\w+\s+\w+/,output[2],"Should be at least two words describing your app")
+  end
+end