Introducing Cukes

.travis.yml

@@ -1,9 +1,4 @@
-before_install:
-  - git submodule update --init --recursive
-language: python
-python:
-  - 2.7
-install:
-  - pip install -r tester/requirements.txt
-script:
-  - cd tester && ./travis.sh
+language: ruby
+rvm:
+  - 2.0.0
+script: bin/rake cruise

Gemfile

@@ -0,0 +1,8 @@
+source "https://rubygems.org"
+
+gem "cucumber"
+gem "httparty"
+gem "json-schema"
+gem "uri_template"
+gem "rake"
+gem 'debugger'

Gemfile.lock

@@ -0,0 +1,41 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    builder (3.2.2)
+    columnize (0.3.6)
+    cucumber (1.3.10)
+      builder (>= 2.1.2)
+      diff-lcs (>= 1.1.3)
+      gherkin (~> 2.12)
+      multi_json (>= 1.7.5, < 2.0)
+      multi_test (>= 0.0.2)
+    debugger (1.6.5)
+      columnize (>= 0.3.1)
+      debugger-linecache (~> 1.2.0)
+      debugger-ruby_core_source (~> 1.3.1)
+    debugger-linecache (1.2.0)
+    debugger-ruby_core_source (1.3.1)
+    diff-lcs (1.2.5)
+    gherkin (2.12.2)
+      multi_json (~> 1.3)
+    httparty (0.12.0)
+      json (~> 1.8)
+      multi_xml (>= 0.5.2)
+    json (1.8.1)
+    json-schema (2.1.3)
+    multi_json (1.8.2)
+    multi_test (0.0.2)
+    multi_xml (0.5.5)
+    rake (10.1.0)
+    uri_template (0.6.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  cucumber
+  debugger
+  httparty
+  json-schema
+  rake
+  uri_template

README.md

@@ -1,49 +1,53 @@
+## Balanced API Specification
+
 [![Build Status](https://travis-ci.org/balanced/balanced-api.png?branch=revision1)](https://travis-ci.org/balanced/balanced-api)
 
-Balanced API Spec
-=================
-
-Online marketplaces enable a new form of commerce at a scale that has never
-existed before. The success of online marketplaces has the potential to
-materially effect the global economy by creating new jobs and economic activity
-that previously did not exist. Airbnb, Kickstarter, Etsy, and other
-marketplaces have created new forms of income for businesses and individuals.
-That's what gets the [Balanced](https://www.balancedpayments.com/) team excited
-and what the [Balanced API](https://www.balancedpayments.com/docs/integration)
-hopes to support.
-
-Payments for marketplaces is unfortunately painful because of unique
-requirements including paying sellers, payments aggregation policies, tax
-ramifications, and fraud. Balanced lets you charge cards, escrow funds, and pay
-sellers the next business day without the pain of building a payments system.
-
-The primary goal of this repo is to create more openness behind the decisions
-driving the designs and functionality of the Balanced API. We reached out to
-existing and potential customers when designing the API, but that was a limited
-set of people we already knew. We've received tremendous growth in the last few
-months, and our new customers have great feedback or at least want to
-understand the reasoning behind the original decisions.
-
-We're going to automate validation of our API code against the specifications
-in the repo. Any changes to the API can't be deployed unless they've been
-merged into master first. Any merge to master will happen concurrently with
-deploys of the API and the [docs](https://www.balancedpayments.com/docs). That
-means the specs need to be auto generated (except for comments) instead of
-handwritten to make sure the code and specs can never go out of sync.
-
-We'll do our best to have even internal discussions online. All changes (even
-by the Balanced team) to the specs must be submitted via pull request and can
-only be merged in by @matin after giving the community a chance to comment on
-the changes.
-
-
-Running Tests
-=============
-
-Create a new python2 virtual environment.
-```
-  $ cd tester
-  $ pip install -r requirements.txt
-  $ python fixture_data.py > fixtures.json
-  $ python runner.py ../scenarios/[scenario name]
+This repository contains an executable specification of the Balanced API. The
+goal of this repository is two-fold. First, to ensure that the API is working
+according to the spec. Second, to provide a place to have discussions around
+the API as a product.
+
+### An Executable Specification
+
+Specifications don't matter if they're not followed. Therefore, this
+specification is executable, so we can ensure conformance to the spec. There are
+more details in the README file inside the `features` directory, but to run these
+tests yourself, simply:
+
+```bash
+$ git clone https://github.com/balanced/balanced-api.git
+$ cd balanced-api
+$ bundle
+$ bin/rake cucumber
 ```
+
+This requires Ruby. We run the changes with Ruby 2.0, but other versions will
+probably work as well. [Let us
+know](https://github.com/balanced/balanced-api/issues/new) if you have any
+problems running these specs, and we'd be happy to help.
+
+If you're working on a new scenario, the 'focus' task is useful. Tag a scenario
+with `@focus`, and then run `bin/rake focus`. It will only run that single scenario.
+
+### Discussions around changes
+
+Speaking of issues, that's the second purpose of this repository. If you would
+like to see a new feature implemented in the Balanced API, please [open an
+issue](https://github.com/balanced/balanced-api/issues/new) and we'll discuss
+it.
+
+For example, one of our biggest requests is to support non-USD currencies.
+[Here](https://github.com/balanced/balanced-api/issues/23) is the issue with
+the discussion, and when we support this feature, we close the issue via a pull
+request that implements the specification, and then everyone on the issue gets
+notified.
+
+Sometimes, Issues are great for collecting feedback, as well. For example,
+[all implementation of the current framework was done via
+PR](https://github.com/balanced/balanced-api/pull/431), and some issues need
+more explanation around use cases by those who want the feature, like [Bitcoin
+support](https://github.com/balanced/balanced-api/issues/204).
+
+We try to do as much 'internal' discussion in these issues as well, it's not
+just for public feedback. If you want to know what we're thinking, just search
+for a relevant issue!

Rakefile

@@ -0,0 +1,52 @@
+require 'cucumber/rake/task'
+
+class BuildFailure < Exception;
+  def initialize(message = nil)
+    message ||= "Build failed"
+    super(message)
+  end
+end;
+
+Cucumber::Rake::Task.new do |t|
+  t.cucumber_opts = "--format progress --tags ~@failing"
+end
+
+Cucumber::Rake::Task.new(:focus) do |t|
+  t.cucumber_opts = "--format progress --tags @focus"
+end
+
+namespace :features do
+  desc "Run all features"
+  Cucumber::Rake::Task.new(:all) do |t|
+    t.cucumber_opts = "--format progress"
+  end
+
+  desc "Run in-progress features"
+  Cucumber::Rake::Task.new(:in_progress) do |t|
+    t.cucumber_opts = "--require formatters/ --format Cucumber::Formatter::InProgress --tags @failing"
+  end
+end
+
+desc "Run complete feature build"
+task :cruise do
+  finished_successful = run_and_check_for_exception("cucumber")
+  in_progress_successful = run_and_check_for_exception("features:in_progress")
+
+  unless finished_successful && in_progress_successful
+    puts
+    puts("Finished features had failing steps") unless finished_successful
+    puts("In-progress Scenario/s passed when they should fail or be pending") unless in_progress_successful
+    puts
+    raise BuildFailure
+  end
+end
+
+def run_and_check_for_exception(task_name)
+  puts "*** Running #{task_name} features ***"
+  begin
+    Rake::Task["#{task_name}"].invoke
+  rescue Exception => e
+    return false
+  end
+  true
+end

bin/cucumber

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'cucumber' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('cucumber', 'cucumber')

bin/rake

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rake', 'rake')

features/README.md

@@ -0,0 +1,81 @@
+## Balanced API Spec: Technical details
+
+Here's where the rubber hits the road.
+
+### Background
+
+We use [Cucumber](http://cukes.info/) for features. What that means is that the
+descriptions are in psuedo-English, which then gets mapped to code.
+
+You can check out the specifications by looking at any of the files that end
+with `.feature` in this directory. They look like this:
+
+```
+Feature: API Keys
+  API Keys are what customers use to authenticate against the Balanced API.
+  Generally speaking, this will be the first step that is needed to be taken by
+  the customer to get started with the API.
+
+  Scenario: List all API keys
+    Customers can make as many keys as they'd like. Being able to see all of
+    them is a good thing.
+
+    Given I have created more than one API keys
+    When I GET to /api_keys
+    Then I should get a 200 OK status code
+```
+
+As you can see by the indentation, each file describes a 'feature.' There's
+then some descriptive text about what that feature is and why it's important.
+Features are a collection of 'scenarios,' which describe different things the
+API can do. These scenarios also have some descriptive text as well. Scenarios
+are made up of 'steps,' which start with "Given," "When," "Then," "And," and a
+few others. These steps are actually executed by Cucumber: they run actual code.
+
+That code is determined by the `step\_definitions` files, which are in that
+directory. They map these feature lines to actual Ruby code. For example,
+
+```
+When I GET to /api_keys
+```
+
+is mapped to
+
+```
+When(/^I (\w+) to (\/\S*?)$/) do |verb, url|
+  options = {
+    headers: {
+      "Accept" => "application/vnd.api+json;revision=1.1",
+    },
+    basic_auth: {
+        username: $api_secret,
+        password: "",
+    }
+  }
+  response = HTTParty.send(verb.downcase, "https://api.balancedpayments.com#{url}", options)
+  @response_code = response.code
+  @response_body = JSON.parse(response.body)
+end
+```
+
+This is illustrative of why we're using Cucumber; if you're not a Rubyist, you
+can probably follow the second bit, but it's full of details you just don't
+care about. You care that you're making a GET to a certain URL, the rest of the stuff
+is just noise.
+
+There is also a `support` directory with some background code that's used to
+set things up. You probably don't care about it.
+
+### Running the tests
+
+The tests are run via `rake`. Simply go to the root level of the repository, and run
+
+```
+$ bin/rake cucumber
+```
+
+to run the specs that are currently passing. To see all the tasks, 
+
+```
+$ bin/rake -T
+```