jet_black 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa0fa42b8b1218e280038ce18fa583a3a8288d4cd91c5a6445c34d03b8c68c5f
-  data.tar.gz: d5c94f0eb5852106f2959dd4745f27d401f67adcc2d79247e9979dd3760a8935
+  metadata.gz: 492919b04c06523b9dca80a4d30939272ae1d435ea83c183f94cae6ab7d11501
+  data.tar.gz: c5157a559982f91bfe2560a6283b96229dade980b35fd52f9e446c4e339772e5
 SHA512:
-  metadata.gz: 5ca15f316fac15876965b704f37432ee80ceb4867c13b1a0cc0e4063f79bd50ec3b60a2a462f600afb753c08c260c665a71065ba3e35d8dd470436acb0128e83
-  data.tar.gz: c371bf859447eeac0514167f9f1869132595cf745d6086dcb1482d0feb7622c886ed3f89ffd8cd881c8f5855718be2386bb0c17bd236ad664a9594e8353dbdde
+  metadata.gz: d2e3877e059b410b276486990e042722d134abb2c9a4111183a9fcfdd3f902bcd742ff426003fb4c44966e4f0d70ba651709f3833f1cc44048fd3ccddee6e764
+  data.tar.gz: ed0f71a6940b5cde28e0c61bcdcbcd76db183a0808a0d7d97d56ba476aab4f885954ab24386f2329c167972430a04d0591105273a93ee4e63a005647ad38df17

data/.circleci/config.yml

@@ -2,7 +2,9 @@ version: 2
 jobs:
   build:
     docker:
-       - image: circleci/ruby:2.5
+      - image: circleci/ruby:2.5
+    environment:
+      ENABLE_COVERAGE: 1
 
     working_directory: ~/repo
 

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v0.3.0
+
+- Allows `stdin` data to be provided when running commands
+- Adds `create_executable` to which writes a file and adds execute permission
+
 ## v0.2.0
 
 - Adds RSpec matchers `have_stdout`, `have_stderr`, `have_no_stdout`, &

data/Gemfile.lock

@@ -1,18 +1,32 @@
 PATH
   remote: .
   specs:
-    jet_black (0.2.0)
+    jet_black (0.3.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     coderay (1.1.2)
+    coveralls (0.7.2)
+      multi_json (~> 1.3)
+      rest-client (= 1.6.7)
+      simplecov (>= 0.7)
+      term-ansicolor (= 1.2.2)
+      thor (= 0.18.1)
     diff-lcs (1.3)
+    docile (1.3.0)
+    json (2.1.0)
     method_source (0.9.0)
+    mime-types (3.1)
+      mime-types-data (~> 3.2015)
+    mime-types-data (3.2016.0521)
+    multi_json (1.13.1)
     pry (0.11.3)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
     rake (10.5.0)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
     rspec (3.7.0)
       rspec-core (~> 3.7.0)
       rspec-expectations (~> 3.7.0)
@@ -28,17 +42,28 @@ GEM
     rspec-support (3.7.1)
     rspec_junit_formatter (0.3.0)
       rspec-core (>= 2, < 4, != 2.12.0)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    term-ansicolor (1.2.2)
+      tins (~> 0.8)
+    thor (0.18.1)
+    tins (0.13.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   bundler (~> 1.16)
+  coveralls
   jet_black!
   pry
   rake (~> 10.0)
   rspec (~> 3.0)
   rspec_junit_formatter
+  simplecov
 
 BUNDLED WITH
    1.16.1

data/README.md

@@ -1,16 +1,248 @@
 # JetBlack
 
-[![CircleCI](https://circleci.com/gh/odlp/jet_black.svg?style=svg)](https://circleci.com/gh/odlp/jet_black)
-
-A black-box testing utility for command line tools, written in Ruby. Features:
-
-- Each session runs in a temporary directory
-- Captures `stdout`, `stderr` and exit status of a command
-- Keeps a history of commands executed
-- Temporarily overriding environment variables for a command
-- Copying fixture files to the temporary directory
-- Appending content to files in the temporary directory
-- Adding a path prefix to include your executable
-- Option to escape the Bundler environment (allowing `bundle exec` with
-  different Gemfiles)
-- RSpec matchers for `stdout` and `stderr`
+[![CircleCI](https://circleci.com/gh/odlp/jet_black.svg?style=svg)](https://circleci.com/gh/odlp/jet_black) [![Coverage Status](https://coveralls.io/repos/github/odlp/jet_black/badge.svg?branch=master)](https://coveralls.io/github/odlp/jet_black?branch=master)
+
+A black-box testing utility for command line tools and gems. Written in Ruby,
+with [RSpec] in mind. Features:
+
+[RSpec]: http://rspec.info/
+
+- Each session takes place within a unique temporary directory, outside the project
+- Synchronously [run commands](#running-commands) then write assertions on the:
+  - `stdout` / `stderr` content
+  - exit status of the process
+- Conveniently manipulate files in the temporary directory:
+  - [Create files](#file-manipulation)
+  - [Create executable files](#file-manipulation)
+  - [Append content to files](#file-manipulation)
+  - [Copy fixture files](#copying-fixture-files) from your project
+- Modify the environment without modifying the parent test process:
+  - [Override environment variables](#environment-variable-overrides)
+  - [Escape the current Bundler context](#clean-bundler-environment)
+  - [Adjust `$PATH`](#path-prefix) to include your executable / Subject Under Test
+- [RSpec matchers](#rspec-matchers) (optional)
+
+The temporary directory is discarded after each spec. This means you can write
+& modify files and run commands (like `git init`) without worrying about tidying
+up after or impacting your actual project.
+
+## Setup
+
+```ruby
+group :test do
+  gem "jet_black"
+end
+```
+
+### RSpec setup
+
+If you're using RSpec, you can load matchers with the following require
+(optional):
+
+```ruby
+# spec/spec_helper.rb
+
+require "jet_black/rspec"
+```
+
+Any specs you write in the `spec/black_box` folder will then have an inferred
+`:black_box` meta type, and the matchers will be available in those examples.
+
+Alternatively you can manually include the matchers:
+
+```ruby
+# spec/cli/example_spec.rb
+
+require "jet_black"
+require "jet_black/rspec/matchers"
+
+RSpec.describe "my command line tool" do
+  include JetBlack::RSpec::Matchers
+end
+```
+
+## Usage
+
+### Running commands
+
+```ruby
+require "jet_black"
+
+session = JetBlack::Session.new
+result = session.run("echo foo")
+
+result.stdout # => "foo"
+result.stderr # => ""
+result.exit_status # => 0
+```
+
+Providing `stdin` data:
+
+```ruby
+session = JetBlack::Session.new
+session.run("./hello-world", stdin: "Alice")
+```
+
+### File manipulation
+
+```ruby
+session = JetBlack::Session.new
+
+session.create_file "file.txt", <<~TXT
+  The quick brown fox
+  jumps over the lazy dog
+TXT
+
+session.create_executable "hello-world.sh", <<~SH
+  #!/bin/sh
+  echo "Hello world"
+SH
+
+session.append_to_file "file.txt", <<~TXT
+  shiny
+  new
+  lines
+TXT
+
+# Subdirectories are created for you:
+session.create_file "deeper/underground/jamiroquai.txt", <<~TXT
+  I'm going deeper underground, hey ha
+  There's too much panic in this town
+TXT
+```
+
+### Copying fixture files
+
+It's ideal to create pertinent files inline within a spec, to provide context
+for the reader, but sometimes a large or non-readable file is best copied
+across.
+
+First create a fixture directory in your project, such as
+`spec/fixtures/black_box`. Then configure the fixture path in
+`spec/support/jet_black.rb`:
+
+```ruby
+require "jet_black"
+
+JetBlack.configure do |config|
+  config.fixture_directory = File.expand_path("../fixtures/black_box", __dir__)
+end
+```
+
+Now you can copy fixtures across into a session's temporary directory:
+
+```ruby
+session = JetBlack::Session.new
+session.copy_fixture("src-config.json", "config.json")
+
+# Destination subdirectories are created for you:
+session.copy_fixture("src-config.json", "config/config.json")
+```
+
+### Environment variable overrides
+
+```ruby
+session = JetBlack::Session.new
+result = subject.run("echo $FOO", env: { FOO: "bar" })
+
+result.stdout # => "bar"
+```
+
+### Clean Bundler environment
+
+If your project's test suite is invoked with Bundler (e.g. `bundle exec rspec`)
+but you want to run commands like `bundle install` and `bundle exec` with a
+different Gemfile in a given spec, you can configure the session or individual
+commands to run with a clean Bundler environment.
+
+```ruby
+# Per command
+session = JetBlack::Session.new
+subject.run("bundle install", options: { clean_bundler_env: true })
+
+# Per session
+session = JetBlack::Session.new(options: { clean_bundler_env: true })
+subject.run("bundle install")
+subject.run("bundle exec rake")
+```
+
+### `$PATH` prefix
+
+Given the root of your project contains a `bin` directory containing
+`my_awesome_bin`.
+
+Configure the `path_prefix` to the directory containing with your executable(s):
+
+```ruby
+# spec/support/jet_black.rb
+
+require "jet_black"
+
+JetBlack.configure do |config|
+  config.path_prefix = File.expand("../../bin", __dir__)
+end
+```
+
+Then the `$PATH` of each session will include the configured directory, and your
+executable should be invokable:
+
+```ruby
+JetBlack::Session.new.run("my_awesome_bin")
+```
+
+### RSpec matchers
+
+Given the [RSpec setup](#rspec-setup) is configured, you'll have access to the
+following matchers:
+
+- `have_stdout` which accepts a string or regular expression
+- `have_stderr` which accepts a string or regular expression
+- `have_no_stdout` which asserts the `stdout` is empty
+- `have_no_stderr` which asserts the `stderr` is empty
+
+And the following predicate matchers:
+
+- `be_a_success` / `be_success` asserts the exit status was zero
+- `be_a_failure` / `be_failure` asserts the exit status was not zero
+
+#### Example assertions
+
+```ruby
+# spec/black_box/cli_spec.rb
+
+RSpec.describe "my command line tool" do
+  let(:session) { JetBlack::Session.new }
+
+  it "does the work" do
+    expect(session.run("my_tool --good")).
+      to be_a_success.and have_stdout(/It worked/)
+  end
+
+  it "explodes with incorrect arguments" do
+    expect(session.run("my_tool --bad")).
+      to be_a_failure.and have_stderr("Oh no!")
+  end
+end
+```
+
+However these assertions can be made with built-in matchers too:
+
+```ruby
+RSpec.describe "my command line tool" do
+  let(:session) { JetBlack::Session.new }
+
+  it "does the work" do
+    result = session.run("my_tool --good")
+
+    expect(result.stdout).to match(/It worked/)
+    expect(result.exit_status).to eq 0
+  end
+
+  it "explodes with incorrect arguments" do
+    result = session.run("my_tool --bad")
+
+    expect(result.stderr).to match("Oh no!")
+    expect(result.exit_status).to eq 1
+  end
+end
+```

data/jet_black.gemspec

@@ -19,8 +19,10 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "coveralls"
   spec.add_development_dependency "pry"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec_junit_formatter"
   spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "simplecov"
 end

data/lib/jet_black/file_helper.rb

@@ -0,0 +1,66 @@
+require "fileutils"
+require_relative "errors"
+
+module JetBlack
+  class FileHelper
+    def initialize(working_directory)
+      @working_directory = working_directory
+    end
+
+    def create_file(file_path, file_content)
+      resolved_file_path = resolve_working_path(file_path)
+      resolved_dir = File.dirname(resolved_file_path)
+
+      FileUtils.mkdir_p(resolved_dir)
+      File.write(resolved_file_path, file_content)
+    end
+
+    def create_executable(file_path, file_content)
+      resolved_file_path = resolve_working_path(file_path)
+
+      create_file(file_path, file_content)
+      FileUtils.chmod("+x", resolved_file_path)
+    end
+
+    def append_to_file(file_path, append_content)
+      resolved_file_path = resolve_working_path(file_path)
+
+      unless File.exist?(resolved_file_path)
+        raise JetBlack::NonExistentFileError.new(file_path, resolved_file_path)
+      end
+
+      File.open(resolved_file_path, "a") do |file|
+        file.write(append_content)
+      end
+    end
+
+    def copy_fixture(source_path, destination_path)
+      source_fixture_dir = JetBlack.configuration.fixture_directory
+      resolved_source_path = File.expand_path(source_path, source_fixture_dir)
+
+      resolved_destination_path = resolve_working_path(destination_path)
+      resolved_destination_dir = File.dirname(resolved_destination_path)
+
+      if source_fixture_dir.nil?
+        raise Error.new("Please configure the fixture_directory")
+      end
+
+      FileUtils.mkdir_p(resolved_destination_dir)
+      FileUtils.cp(resolved_source_path, resolved_destination_path)
+    end
+
+    private
+
+    attr_reader :working_directory
+
+    def resolve_working_path(file_path)
+      resolved_file_path = File.expand_path(file_path, working_directory)
+
+      unless resolved_file_path.start_with?(working_directory)
+        raise JetBlack::InvalidPathError.new(file_path, resolved_file_path)
+      end
+
+      resolved_file_path
+    end
+  end
+end

data/lib/jet_black/session.rb

@@ -1,86 +1,47 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "forwardable"
 require "open3"
 require "tmpdir"
 require_relative "environment"
 require_relative "errors"
 require_relative "executed_command"
+require_relative "file_helper"
 
 module JetBlack
   class Session
-    attr_reader :commands
+    extend Forwardable
+
+    def_delegators :file_helper, :create_file, :create_executable,
+                   :append_to_file, :copy_fixture
+
+    attr_reader :commands, :directory
 
     def initialize(options: {})
       @commands = []
       @session_options = options
+      @directory = File.realpath(Dir.mktmpdir("jet_black"))
+      @file_helper = FileHelper.new(directory)
     end
 
-    def run(command, env: {}, options: {})
+    def run(command, stdin: nil, env: {}, options: {})
       combined_options = session_options.merge(options)
-      executed_command = exec_command(command, env, combined_options)
+      executed_command = exec_command(command, stdin, env, combined_options)
       commands << executed_command
       executed_command
     end
 
-    def directory
-      @_directory ||= File.realpath(Dir.mktmpdir("jet_black"))
-    end
-
-    def create_file(file_path, file_content)
-      expanded_file_path = File.expand_path(file_path, directory)
-      expanded_dir = File.dirname(expanded_file_path)
-
-      unless expanded_file_path.start_with?(directory)
-        raise JetBlack::InvalidPathError.new(file_path, expanded_file_path)
-      end
-
-      FileUtils.mkdir_p(expanded_dir)
-      File.write(expanded_file_path, file_content)
-    end
-
-    def append_to_file(file_path, append_content)
-      expanded_file_path = File.expand_path(file_path, directory)
-
-      unless File.exist?(expanded_file_path)
-        raise JetBlack::NonExistentFileError.new(file_path, expanded_file_path)
-      end
-
-      File.open(expanded_file_path, "a") do |file|
-        file.write(append_content)
-      end
-    end
-
-    def copy_fixture(source_path, destination_path)
-      src_fixture_dir = JetBlack.configuration.fixture_directory
-      expanded_source_path = File.expand_path(source_path, src_fixture_dir)
-      expanded_destination_path = File.expand_path(destination_path, directory)
-      expanded_destination_dir = File.dirname(expanded_destination_path)
-
-      if src_fixture_dir.nil?
-        raise Error.new("Please configure the fixture_directory")
-      end
-
-      unless expanded_destination_path.start_with?(directory)
-        raise JetBlack::InvalidPathError.new(
-          destination_path, expanded_destination_path
-        )
-      end
-
-      FileUtils.mkdir_p(expanded_destination_dir)
-      FileUtils.cp(expanded_source_path, expanded_destination_path)
-    end
-
     private
 
-    attr_reader :session_options
+    attr_reader :session_options, :file_helper
 
-    def exec_command(raw_command, raw_env, options)
+    def exec_command(raw_command, stdin, raw_env, options)
       env = Environment.new(raw_env).to_h
 
       command_context(options) do
         stdout, stderr, exit_status =
-          Open3.capture3(env, raw_command, chdir: directory)
+          Open3.capture3(env, raw_command, chdir: directory, stdin_data: stdin)
 
         ExecutedCommand.new(
           raw_command: raw_command,

data/lib/jet_black/version.rb

@@ -1,3 +1,3 @@
 module JetBlack
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jet_black
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Oli Peate
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-04-27 00:00:00.000000000 Z
+date: 2018-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -80,6 +94,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email: 
 executables: []
@@ -89,7 +117,6 @@ files:
 - ".circleci/config.yml"
 - ".gitignore"
 - ".rspec"
-- ".travis.yml"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
@@ -104,6 +131,7 @@ files:
 - lib/jet_black/environment.rb
 - lib/jet_black/errors.rb
 - lib/jet_black/executed_command.rb
+- lib/jet_black/file_helper.rb
 - lib/jet_black/rspec.rb
 - lib/jet_black/rspec/matchers.rb
 - lib/jet_black/session.rb

data/.travis.yml

@@ -1,5 +0,0 @@
-sudo: false
-language: ruby
-rvm:
-  - 2.4.3
-before_install: gem install bundler -v 1.16.1