siringa 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZGIxNzZkYjA3ZmM5MmU2MTM1OTVmOTNmM2NiNDhmNmI2M2UxMzgzMw==
+  data.tar.gz: !binary |-
+    NWZiYWE3MTIzMjI1NTE0YzJjZjhiYzJmNGRiMzlhYjQyOTA4MGZjMw==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    YjM1NDczYWU5N2JjMjA1YTY0MTIwMjQzZjljMjZlNzBkMDQ3NjYxZDYwOGQw
+    ZTBlZTc2ZDRiMjhkNTI1N2QwNmY2YWYwNzQ4NzVlYTliMmQxNmJjNThmNjI2
+    YmM1MGRlMjQ0MWEyMTIzN2E2OTBjYWIwNDU1YTU3MTViOWRkZmM=
+  data.tar.gz: !binary |-
+    NDdmYzI2ZmRjOGQ2MWRiMDE0NDc2MGZiYTA5MTEyNWIxNGIxMzc1MTgwZjg0
+    NmEyMzNhNzgyMmE3ZjcyZmJmOWIzNWYwYTE0Y2JmZTUyYTRmNWRlNTcyOTJk
+    MmVhYmU3YjA1MmYwNDNhYzdjOTMxMTcwMTk2NzM0ZGNmNmY0MDQ=

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 Enrico Stano
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,169 @@
+# Siringa :syringe:
+This gem was born working on pure client acceptance testing in [Teambox](http://www.teambox.com).
+## The problem
+
+You have a Rails based API and you need to write some acceptance tests using your Javascript/iOS/Android/whatever client.
+
+Probably you'll have three basic needs:
+
+1. Pre-populate the DB with some (maybe massive) data (a.k.a. seed data)
+2. Your seed data files have to be easily maintainable, you don't want to touch them too much when a model change and so on
+3. Populate your DB while executing some specific acceptance test and then clean up the DB restoring the initial situation
+
+## The solution
+
+1. Write your seed data and use Siringa's rake recipes to pre-populate the DB just after you deploy your API
+2. I suggest to use factories to create your seed data in order to take advantage of factories maybe you've already written for unit tests. But you could use whatever other way to keep your seed data maintainable and you still could use Siringa
+3. Use Siringa's extra API endpoints in order to dump your inital DB situation, load some factories and then restore the initial status when you're done
+
+**Why you don't just use your app's API to do the same thing, maybe storing JSON/XML objects in some fixture?**
+
+Well, because mantaining those huge JSON/XML fixture files will be a nightmare.
+
+## Install Siringa
+
+Add the following to your `Gemfile`:
+```ruby
+group :test do
+  gem 'siringa'
+end
+```
+For security reasons, I suggest to add it under the `test` group. In that way you'll have Siringa available only running the app in `test` environment.
+
+Run the bundle command to install it.
+
+Run the generator:
+```console
+rails generate siringa:install
+```
+This will add the Siringa initializer in `config/initializers/siringa.rb` and create an empty directory in `tmp/dumps`.
+
+Add the following to your `config/routes.rb`:
+```ruby
+mount Siringa::Engine, :at => '/siringa'
+```
+Make sure that you add it in the correct environment. For instance if you want it available only in `test` environment put it inside a condition statement like `if Rails.env.test? .. end`.
+## Create definitions
+
+In order to create a new Siringa definition just create a new file in the `test/siringa` directory like the following:
+
+```ruby
+# test/siringa/definitions.rb
+require 'siringa'
+require File.expand_path('../../factories', __FILE__)
+
+Siringa.add_definition :initial do
+  FactoryGirl.create :user,
+    name: 'Jesse Pinkman'
+end
+
+Siringa.add_definition :specific do
+  FactoryGirl.create :user,
+    name: 'Hank Schrader'
+  FactoryGirl.create :project,
+    name: 'Pollos Hermanos'
+end
+```
+
+I'm using [FactoryGirl](https://github.com/thoughtbot/factory_girl) gem here but in a definition you could write whatever kind of Ruby code and Siringa will execute it when you call the definition.
+
+## Load definitions
+Now that we've created our definitions we could use them in our two cases:
+### As seed data
+You could just load the `initial` definition running the following rake recipe after your deploy:
+```console
+rake siringa:load
+```
+`initial` is the default definition this Rake task recipe will try to load, if you want to load another definition instead you could pass its name as argument:
+```console
+rake 'siringa:load[another_definition]'
+```
+This will load a definition named `:another_definition`. Please note that if you use Zsh shell you'll need to use quotes, more info [here](http://robots.thoughtbot.com/post/18129303042/how-to-use-arguments-in-a-rake-task).
+
+If you want to force a Rails environment you could just run the Sriringa recipe specifing the `RAILS_ENV` environmental variable:
+```console
+RAILS_ENV=development rake siringa:load
+```
+
+### During an acceptance test
+As you can see running `rake routes`, Siringa added 3 new routes to your API:
+```console
+Routes for Siringa::Engine:
+        POST /load/:definition(.:format) siringa/siringa#load
+   dump POST /dump(.:format)             siringa/siringa#dump
+restore POST /restore(.:format)          siringa/siringa#restore
+```
+
+The workflow I propose here is:
+
+1. Create a dump of your DB performing a `POST` request to `YOURHOST/siringa/dump`
+
+   This will create a `.dump` file in the `tmp/dumps` directory created during the install process. You could create as many dump files as you want but Siringa will keep only the latest 5 dumps created.
+
+2. Load a Siringa definition performing a `POST` request to `YOURHOST/siringa/load/specific`
+
+   This will run the code defined in a definition named `specific` on the server.
+
+3. Go ahead with your acceptance test
+
+4. Restore the DB status performing a `POST` request to `YOURHOST/siringa/restore`
+
+   This will bring back your DB at the initial status using the dump file you created in step 1.
+
+   Please note that the `Siringa::restore` method only use the latest dump file created, older dump files in the `tmp/dumps` folder will be ignored.
+
+## Customize Siringa
+You could customize Siringa changing the configuration stored in the initializer:
+```ruby
+# config/initializers/siringa.rb
+Siringa.configure do |config|
+  # customize the path where the definitions are stored
+  config.definitions_path = 'test/siringa'
+  # customize the path where the DB dumps are stored
+  config.dumps_path = 'tmp/dumps'
+end
+
+Siringa.load_definitions
+```
+## Acceptance test example
+Just to get the idea, the following script will show you how to use Siringa in a acceptance test using Selenium, [rest-client](https://github.com/rest-client/rest-client) and RSpec:
+```ruby
+require 'selenium-webdriver'dd
+require 'rspec'
+require 'rest_client'
+
+describe "Acceptance test using Siringa" do
+  before(:all) do
+    # Dump your DB
+    RestClient.post 'YOURHOST/siringa/dump'
+  end
+
+  before(:each) do
+    @driver = Selenium::WebDriver.for :firefox
+  end
+
+  after(:each) do
+    @driver.quit
+  end
+
+  it "Load a definition and test something" do
+    # Load a definition named 'specific'
+    RestClient.post 'YOURHOST/siringa/load', { :definition => :specific }
+
+    # Here goes your test
+
+    # Restore your DB
+    RestClient.post 'YOURHOST/siringa/restore'
+  end
+end
+```
+## To Do
+* Write more tests
+* Add Postgres adaptor compatibility for dumps and restores
+* Add more customizations
+
+## How to collaborate
+* Fork the repo and send a pull request, thanks!
+
+# Licence
+MIT-LICENSE 2013 Enrico Stano

data/Rakefile

@@ -0,0 +1,39 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Siringa'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/app/controllers/siringa/application_controller.rb

@@ -0,0 +1,4 @@
+module Siringa
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/siringa/siringa_controller.rb

@@ -0,0 +1,49 @@
+module Siringa
+  class SiringaController < ApplicationController
+
+    def load
+      Siringa.load_definition(params['definition'].to_sym)
+      resp = { :text => "Definition #{params['definition']} loaded.", :status => :created }
+    rescue ArgumentError => exception
+      resp = { :text => exception.to_s, :status => :method_not_allowed }
+    rescue => exception
+      resp = { :text => exception.to_s, :status => :internal_server_error }
+    ensure
+      render resp
+    end
+
+    def dump
+      result = Siringa.dump_to(Siringa.dump_file_name)
+      if result[:success]
+        Siringa.keep_five_dumps(Siringa.ordered_dumps)
+        resp = { :text => "DB dumped at #{result[:file_name]}",
+                 :status => :created }
+      else
+        resp = { :text => "DB dump FAILED!\nError:\n#{result[:output]}",
+                 :status => :internal_server_error }
+      end
+
+      render resp
+    end
+
+    def restore
+      last_dump = Siringa.ordered_dumps.last
+      if last_dump
+        result = Siringa.restore_from(last_dump)
+        if result[:success]
+          resp = { :text => "DB restored from #{result[:file_name]}",
+                   :status => :accepted }
+        else
+          resp = { :text => "DB restore FAILED!\nError:\n#{result[:output]}",
+                   :status => :internal_server_error }
+        end
+      else
+        resp = { :text => "DB restore FAILED!\nThere is no dump to restore from.",
+                 :status => :method_not_allowed }
+      end
+
+      render resp
+    end
+
+  end
+end

data/app/helpers/siringa/application_helper.rb

@@ -0,0 +1,4 @@
+module Siringa
+  module ApplicationHelper
+  end
+end

data/config/routes.rb

@@ -0,0 +1,5 @@
+Siringa::Engine.routes.draw do
+  post "load/:definition", :to => "siringa#load"
+  post "dump", :to => "siringa#dump"
+  post "restore", :to => "siringa#restore"
+end

data/lib/generators/siringa/install_generator.rb

@@ -0,0 +1,18 @@
+module Siringa
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../templates", __FILE__)
+      desc "Creates Siringa initializer for your application"
+
+      def copy_initializer
+        template "siringa_initializer.rb", "config/initializers/siringa.rb"
+
+        puts "Install complete!"
+      end
+
+      def create_dumps_folder
+        empty_directory "tmp/dumps"
+      end
+    end
+  end
+end

data/lib/generators/templates/siringa_initializer.rb

@@ -0,0 +1,9 @@
+# config/initializers/siringa.rb
+Siringa.configure do |config|
+  # customize the path where the definitions are stored
+  # config.definitions_path = 'test/siringa'
+  # customize the path where the dumps are stored
+  # config.dumps_path = 'tmp/dumps'
+end
+
+Siringa.load_definitions

data/lib/siringa.rb

@@ -0,0 +1,4 @@
+require "siringa/engine"
+require "siringa/configuration"
+require "siringa/definitions"
+require "siringa/dumps"

data/lib/siringa/configuration.rb

@@ -0,0 +1,26 @@
+module Siringa
+
+  @definitions = {}
+
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  class Configuration
+    attr_accessor :definitions_path, :dumps_path
+
+    def initialize
+      @definitions_path = "spec/siringa"
+      @dumps_path = 'tmp/dumps'
+    end
+  end
+
+end

data/lib/siringa/definitions.rb

@@ -0,0 +1,38 @@
+module Siringa
+
+  # Load definitions from files
+  def self.load_definitions
+    Dir[Rails.root.join("#{self.configuration.definitions_path}/**/*.rb")].each { |f| require f }
+  end
+
+  # Load a definition and run its code
+  #
+  # @param [Symbol] name of the definition
+  def self.load_definition(name)
+    if exists_definition?(name)
+      @definitions[name].call
+    else
+      raise ArgumentError, "Definition #{name.to_s} does not exist.", caller
+    end
+  end
+
+  # Add a definition
+  #
+  # @param [Symbol] name of the definition
+  # @param [Proc] code to run
+  def self.add_definition(name, &block)
+    if !exists_definition?(name)
+      @definitions[name] = Proc.new(&block)
+    else
+      raise ArgumentError, "Definition #{name.to_s} already exists."
+    end
+  end
+
+  # Check if a definition already exists
+  #
+  # @param  [Symbol] name of the definition
+  # @return [Boolean]
+  def self.exists_definition?(name)
+    !@definitions[name].nil?
+  end
+end

data/lib/siringa/dumps.rb

@@ -0,0 +1,66 @@
+module Siringa
+
+  # Generate dump file name
+  #
+  # @return [String]
+  def self.dump_file_name
+    "#{Siringa.configuration.dumps_path}/db_#{Time.now.strftime('%Y%m%d%H%M%S')}.dump"
+  end
+
+  # Create a DB dump
+  #
+  # @param [String] dump path
+  # @return [Object]
+  def self.dump_to(dump_path)
+    adapter_config = ActiveRecord::Base.connection.instance_values["config"]
+    case adapter_config[:adapter]
+    when "mysql", "mysql2"
+      output = %x(/usr/bin/env mysqldump -uroot #{adapter_config[:database]} > #{dump_path})
+    when "sqlite3"
+      output = %x(/usr/bin/env sqlite3 #{adapter_config[:database]} '.backup #{dump_path}')
+    else
+      raise NotImplementedError, "Unknown adapter type '#{adapter_config[:adapter]}'"
+    end
+
+    { :success => $?.success?, :output => output, :dump_path => dump_path }
+  end
+
+  # Restore from a DB dump
+  #
+  # @param [String] dump path
+  # @return [Object]
+  def self.restore_from(dump_path)
+    adapter_config = ActiveRecord::Base.connection.instance_values["config"]
+    case adapter_config[:adapter]
+    when "mysql", "mysql2"
+      output = %x(/usr/bin/env mysql -uroot #{adapter_config[:database]} < #{dump_path})
+    when "sqlite3"
+      output = %x(/usr/bin/env sqlite3 #{adapter_config[:database]} '.restore #{dump_path}')
+    else
+      raise NotImplementedError, "Unknown adapter type '#{adapter_config[:adapter]}'"
+    end
+
+    { :success => $?.success?, :output => output, :dump_path => dump_path }
+  end
+
+  # Delete oldest dump files, keep 5 dump files
+  #
+  # @param [Array] file names
+  # @return [Boolean]
+  def self.keep_five_dumps(dump_files)
+    if dump_files.length > 5
+      dump_files.first(dump_files.length - 5).each { |f| File.delete(f) }
+      return true
+    else
+      return false
+    end
+  end
+
+  # Retrieve a collection of dump files sorted by creation date
+  #
+  # @return [Array]
+  def self.ordered_dumps
+    Dir.glob("#{Siringa.configuration.dumps_path}/db_*.dump").sort_by { |f| File.mtime(f) }
+  end
+
+end