katapult 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c0c8a60d4ea75bbc8ab64191575c2a672d80daf6
-  data.tar.gz: 8e3b106a9465545b5bccef527bf11358aa0ecd37
+  metadata.gz: 83b5fc8065a8a49c75139d70ffd14b8bd9f46153
+  data.tar.gz: da1546065c4be23023e74749f5ab80ce217f4a58
 SHA512:
-  metadata.gz: e0fa254887044ccb0d59a3d7921e8a6122797f1950a2ed4cd55ccfb5da9e25e5c62ab1fe496cdc7b6dbf5675ab7410ae005e888ac69e9e95667d3ca5c146ed8d
-  data.tar.gz: 5367cb38a7cd8945ad1c6bb912b0004b17051cbac11a38172c8ea0c1435369e12dbc36f2a3a86a582c6a1ace860515da88572e23a1bd535e0cc3c87657b4d723
+  metadata.gz: ce71cf5e9ddd843be50e677070b5591a3f6dc48e2bff36eebc7f86651cbc2a8610f950476c9c47a407431550611202cfe65fd2a20318870f57e6745db9c6ed6a
+  data.tar.gz: 2285ddc6da1550f9cbf75165b49d2e6f65ba1894b97286d9b1e1b0f2efa61456e0534c37890b9758f5a37cebb40c02d2968933a8e58e26ade886fd9a0f1b9ed5

data/README.md

@@ -3,9 +3,10 @@
 <img src="katapult.png" width="200px" align="right" />
 
 
-`Katapult` is a kickstart generator for Rails applications. It creates
-application basics and generates (makandra-flavored) code from an application
-model, significantly speeding up the initial phase of a Rails project.
+`Katapult` is a kickstart generator for Rails applications. It creates a basic
+application and generates ([makandra-flavored](https://leanpub.com/growing-rails))
+code from an application model, significantly speeding up the initial phase of a
+Rails project.
 
 `Katapult` will always support current versions of Ruby and Rails, currently
 Rails 4.2 and Ruby 2.1.
@@ -13,37 +14,78 @@ Rails 4.2 and Ruby 2.1.
 
 ## Installation
 
-As `katapult` is designed to *start* Rails applications, it works best with a
-clean new Rails app. To create one, run
+Install the `katapult` gem with
 
-    katapult target MY_APPLICATION_NAME
+    gem install katapult
 
-This will add the `katapult` gem to the Gemfile and then integrate `katapult`
-by running
 
-    rails generate katapult:install
-    rails generate katapult:basics
+## Usage
 
+`Katapult` does two separate things:
 
-It will install application basics, such as a `database.yml`, basics styles as
-well as RSpec and Cucumber and prepare `lib/katapult/application_model.rb`
-where you will draft your application.
+1. Create a new Rails application, set up with many standard gems, snippets,
+   useful configuration, databases etc.
+2. Generate code from an application model, i.e. create files for models, views,
+   controllers, routes, stylesheets
 
-### Manual installation
-You may also integrate the gem into an existing Rails application. Just add it to the Gemfile and run the generators stated above.
+You may use both or only one of them.
 
 
-## Usage
+## 1) Creating a new Rails application
+
+Run the following command:
+
+    katapult new $APPLICATION_NAME
+
+In detail, this will:
+ 
+- create a new Rails application (without turbolinks)
+- install common Gems, some of them commented out
+- add a .gitignore and a .ruby-version file
+- set up a `database.yml` file (for MySQL)
+- create basic styles
+- install some handy initializers
+- install RSpec and Cucumber to the application
+- create `lib/katapult/application_model.rb` (needed in Step 2)
+
+See `lib/generators/katapult/basics/basics_generator.rb`.
+
+### Using Katapult in existing Rails applications
+`katapult` expects a clean application (that it would usually generate itself).
+If you have an existing Rails application, you *may* use `katapult`, but be
+warned: it is not designed to respect existing files, although it will usually
+ask before overwriting files.
+
+To add `katapult` to an existing Rails application, add
+`gem 'katapult', group: :development` to the Gemfile. Then run any of the
+following generators:
+
+    rails generate katapult:basics # Prepare the app with useful defaults
+    rails generate katapult:install # Create application model file
+    rails generate katapult:transform lib/katapult/application_model.rb
+
+
+## 2) Generating code from an application model
+
+> If you only want to use the code generation feature of `katapult`, but did not
+> run `katapult new ...`, you need to add `katapult` to your Gemfile now and
+> install it with `rails generate katapult:install`. See above.
 
-After installation, you find a file `lib/katapult/application_model.rb` where
-you will define the properties of your application. Inside this file, use
-`katapult`'s simple DSL (domain specific language) to express yourself.
+After installation, you will find a file `lib/katapult/application_model.rb`
+where you will define the properties of your application.
 
+Inside this file, use `katapult`'s simple DSL (domain specific language) to
+express yourself. When you are done developing the application model, transform
+it into code with:
 
-### DSL syntax example
-The DSL consists of _elements_, e.g. Model or WUI (which stands for *Web User
-Interface*). Each `katapult` element has the same syntax, taking a name,
-options, and a block:
+    katapult fire
+
+See an overview of the DSL below. The respective sections hold examples of what
+options are available to each element.
+
+### Generic DSL syntax example
+The DSL consists of _elements_, e.g. `Model` or `WUI` (Web User Interface). Each
+`katapult` element has the same syntax, taking a name, options, and a block:
 
     element_type 'name', options: 'example' do |element|
       element.some_method
@@ -54,17 +96,29 @@ options, and a block:
 Takes a name and a block:
 
     model 'Customer' do |customer|
-      # ...
+      # customer.attr :name etc, see Attribute element
     end
 
 
 #### Attribute
 Defined on Model. Takes a name and options:
 
+    # Default type :string
+    model.attr :name
+    
+    # Inferred type :email (when attr name matches /email/)
     model.attr :email
+    
+    # Specify assignable values. Available options: allow_blank, default
     model.attr :age, type: :integer, assignable_values: 18..99, allow_blank: true
+    
+    # Will be rendered as number_field in forms, and with a € sign in show views
     model.attr :income, type: :money
+    
+    # All attribute types take an optional default
     model.attr :homepage, type: :url, default: 'http://www.makandra.de'
+    
+    # Boolean fields are modeled as flags. Default required!
     model.attr :locked, type: :flag, default: false
 
 
@@ -72,22 +126,32 @@ Defined on Model. Takes a name and options:
 Takes a name, options and a block:
 
     wui 'Customer', model: 'User' do |wui|
-      # ...
+      # wui.crud, see Action element
+    end
+
+    # Inferred model name: 'Customer'
+    wui 'Customer' do |wui|
+      # wui.crud, see Action element
     end
 
 
 #### Action
 Defined on WUI. Takes a name and options:
 
+    # Create all the standard rails actions
+    wui.crud
+
+    # Select single Rails actions
     wui.action :index
     wui.action :show
     wui.action :create # also creates :new
     wui.action :update # also creates :edit
     wui.action :destroy
-    wui.crud   # creates all the standard rails actions above
+    
+    # Add custom actions
     wui.action :custom_action, method: :post, scope: :member
     wui.action :other_action, method: :get, scope: :collection
-
+    
 
 ### Navigation
 Takes a name, will generate a navigation with links to the index pages of all
@@ -98,19 +162,46 @@ WUIs.
 
 ## Development
 
-`Katapult` caches a pristine Rails application inside its `tmp/` directory to
+### Basic information
+`Katapult` is tested with [RSpec](http://rspec.info/) and
+[Cucumber](https://cucumber.io/) + [Aruba](https://github.com/cucumber/aruba)
+([API-Doc](http://www.rubydoc.info/github/cucumber/aruba/master/)).
+
+It caches a pristine Rails application inside its `tmp/` directory to
 speed up test runs. Keep this in mind, as it may lead to caching issues when
 switching Ruby versions or installing a new version of the Rails gem.
 
 Since `katapult` has full-stack integration tests, it requires a MySQL account.
-Create a dedicated account on your MySQL server by running this command in a
-MySQL console (as-is):
+Create a dedicated account on your local MySQL server by running this command in
+a MySQL console (as-is):
 
     GRANT ALL ON *.* TO 'katapult'@'localhost' IDENTIFIED BY 'secret';
 
 The user `katapult` is hereby granted any action (SELECT, UPDATE, etc. except
 for granting privileges) on any database and table (`*.*`).
 
+### Continuing development
+When you continue development on `katapult`, remove its `tmp/` directory first.
+It contains cached data that might lead to confusion.
+
+### Debugging
+Add the `@announce-output` tag to `katapult` features in order to have any output
+logged to your terminal.
+
+To precisely debug errors occurring _inside_ the generated application, you may
+cd to `tmp/aruba/katapult_test_app`. Run the failing command manually.
+
+Note that after running a katapult feature, you need to call
+`cd ../../aruba/katapult_test_app` inside the generated app terminal. This is
+required because the `tmp/aruba` directory is being wiped before each scenario.
+
+### Typical errors
+- Timeout error because of a script waiting for user input
+- Executing (bash) commands in the test application without resetting the
+  katapult gem's Bundler settings. Wrap into `Bundler.with_clean_env { }`.
+- Spring running inside the test application encumbers parallel_tests
+- An outdated Rails application in `tmp/cached_test_app`
+
 
 ## Credits
 

data/bin/katapult

@@ -1,44 +1,82 @@
 #!/usr/bin/env ruby
 
+# This script simplifies the usage of `katapult` by grouping relevant actions
+# that the user else had to perform manually.
+# See bottom for USAGE.
+
 require_relative '../lib/katapult/util'
+require 'bundler'
+
+def pink_puts(*args)
+  message = "\n> #{ args.join ' ' }"
+  Kernel.puts "\e[35m#{ message }\e[0m" # pink
+end
 
-case (command = ARGV.shift)
-when 'target'
+# With clean Bundler env
+def run(command)
+  Bundler.with_clean_env { system command }
+end
+
+case (transform_command = ARGV.shift)
+when 'new'
+  interactive = !ARGV.delete('--non-interactive')
   app_name = ARGV.shift
+  basics_command = 'bundle exec rails generate katapult:basics'
 
-  puts 'Creating new Rails application ...'
-  system "rails new #{app_name} --skip-test-unit --skip-bundle --database mysql"
+  if interactive
+    pink_puts 'Please enter your database user: '
+    basics_command << ' --db-user ' << gets.chomp
+
+    pink_puts 'Please enter your database password: '
+    basics_command << ' --db-password ' << gets.chomp
+  end
+
+  pink_puts 'Creating new Rails application ...'
+  run "rails new #{ app_name } --skip-test-unit --skip-bundle --database mysql"
 
   Dir.chdir app_name
 
-  puts
-  puts 'Initializing git repository ...'
-  system 'git init'
-  Katapult::Util.git_commit "rails new #{app_name}"
+  pink_puts 'Initializing git repository ...'
+  run 'git init'
+  Katapult::Util.git_commit "rails new #{ app_name }"
 
-  puts
-  puts 'Installing katapult ...'
+  pink_puts 'Installing katapult ...'
   File.open('Gemfile', 'a') do |file|
-    file.puts "gem 'katapult'#{ ENV['KATAPULT_GEMFILE_OPTIONS'] }"
+    file.puts "gem 'katapult'#{ ENV['KATAPULT_GEMFILE_OPTIONS'] }, group: :development"
   end
-  system 'bundle install'
-  system 'bundle exec rails generate katapult:install'
+  run 'bundle install'
+  run 'bundle exec rails generate katapult:install'
   Katapult::Util.git_commit 'rails generate katapult:install'
 
-  puts
-  puts 'Generating katapult basics ...'
-  system 'bundle exec rails generate katapult:basics'
+  pink_puts 'Generating katapult basics ...'
+  run basics_command
   Katapult::Util.git_commit 'rails generate katapult:basics'
 
-  puts
-  puts 'Done.'
+  pink_puts <<-INSTRUCTIONS
+Application initialization done.
+
+Next step: Model your application in lib/katapult/application_model.rb and
+transform it into code by running `katapult fire`.
+  INSTRUCTIONS
 
 when 'fire'
   app_model_path = 'lib/katapult/application_model.rb'
+  transform_command = 'bin/rails generate katapult:transform ' + app_model_path
+
+  pink_puts 'Loading katapult ...'
+  run transform_command
+  Katapult::Util.git_commit transform_command
+
+  pink_puts <<-INSTRUCTIONS
+Model transformation done.
 
-  puts 'Loading katapult ...'
-  system 'bin/rails generate katapult:transform ' + app_model_path
+Now boot up your development server (e.g. with `rails server`) and try your
+kickstarted application in the browser!
+  INSTRUCTIONS
 
 else
-  puts 'Usage: katapult [target APP_NAME | fire]'
+  puts <<-USAGE
+Usage: katapult [new APP_NAME | fire]
+Hint: Suppress database credentials prompt with `--non-interactive`
+  USAGE
 end

data/features/binary.feature

@@ -1,13 +1,21 @@
 Feature: Katapult binary `katapult`
 
   Scenario: Start new Rails application
-    Given the default aruba timeout is 120 seconds
+    Given the default aruba exit timeout is 120 seconds
 
-    When I successfully run `katapult target binary_test`
+    When I run `katapult new binary_test` interactively
+      And I type "katapult"
+      And I type "secret"
     Then the output should contain "Creating new Rails application"
     And the output should contain "Installing katapult"
     And the output should contain "Generating katapult basics"
-    And the output should contain "Done."
+    And the output should contain:
+    """
+    Application initialization done.
+
+    Next step: Model your application in lib/katapult/application_model.rb and
+    transform it into code by running `katapult fire`.
+    """
 
     When I cd to "binary_test"
 
@@ -15,9 +23,14 @@ Feature: Katapult binary `katapult`
     Then the file "Gemfile" should contain "gem 'katapult'"
     And a file named "lib/katapult/application_model.rb" should exist
 
-    # test whether the application is already bundled
-    When I run `bundle check`
-    Then the output should contain "The Gemfile's dependencies are satisfied"
+    # test correct insertion of database credentials
+    And the file "config/database.yml" should contain "username: katapult"
+    And the file "config/database.yml" should contain "password: secret"
+
+#    Not working, probably because Bundler sees an empty BUNDLER_GEMFILE var
+#    # test whether the application is already bundled
+#    When I run `bundle check`
+#    Then the output should contain "The Gemfile's dependencies are satisfied"
 
     # test whether katapult made git commits
     When I run `git log`
@@ -26,21 +39,15 @@ Feature: Katapult binary `katapult`
     And the output should contain "rails generate katapult:basics"
     And the output should contain "Author: katapult <katapult@makandra.com>"
 
-    And the output should contain:
-    """
-    Next step: Model your application in lib/katapult/application_model.rb and
-    trigger the code generation by running `katapult fire`.
-    """
-
 
   Scenario: Forget to pass application name
-    When I run `katapult target # without app name`
+    When I run `katapult new --non-interactive # Without app name`
     Then the output should contain "No value provided for required arguments 'app_path'"
 
 
   Scenario: Run without arguments
     When I run `katapult # without arguments`
-    Then the output should contain "Usage: katapult [target APP_NAME | fire]"
+    Then the output should contain "Usage: katapult [new APP_NAME | fire]"
 
 
   Scenario: Transform the application model
@@ -55,6 +62,12 @@ Feature: Katapult binary `katapult`
 
     And the output should contain:
     """
-    You're done! Now boot up your development server (e.g. with `rails server`)
-    and try your kickstarted application in the browser.
+    Model transformation done.
+
+    Now boot up your development server (e.g. with `rails server`) and try your
+    kickstarted application in the browser!
     """
+
+    When I run `git log`
+    Then the output should contain "rails generate katapult:transform lib/katapult/application_model.rb"
+      And the output should contain "Author: katapult <katapult@makandra.com>"

data/features/katapult.feature

@@ -32,21 +32,35 @@ Feature: Katapult in general
 
   Scenario: Generate basic files and settings
     Given I install katapult
+
     When I generate katapult basics
     Then the file ".ruby-version" should contain "2.1.5"
-    And the file "Gemfile" should contain exactly:
+
+
+    And the file "config/cucumber.yml" should contain:
+      """
+      default: <%= std_opts %> features
+      wip: --tags @wip:3 --wip features
+      parallel: <%= std_opts %> features <%= log_failures %>
+      rerun: -r features --format pretty --strict <%= rerun_failures %> <%= log_failures %>
+      """
+
+
+      And the file ".gitignore" should contain "config/database.yml"
+      And the file "Gemfile" should contain "gem 'rails', '4.2.4'"
+      And the file "Gemfile" should contain exactly:
       """
       source 'https://rubygems.org'
 
       # from original Gemfile
-      gem 'rails', '4.2.1'
-      gem 'mysql2'
+      gem 'rails', '4.2.4'
       gem 'jquery-rails'
       gem 'jbuilder', '~> 2.0'
       gem 'katapult', path: '../../..'
 
       # engines
       gem 'haml-rails'
+      gem 'mysql2', '~> 0.3.18' # Work around require-error in Rails 4.2
 
       # internal
       gem 'exception_notification'
@@ -88,6 +102,7 @@ Feature: Katapult in general
         gem 'binding_of_caller'
         gem 'thin'
 
+        gem 'parallel_tests'
         gem 'guard-livereload', require: false
         gem 'rack-livereload'
         gem 'spring-commands-rspec'
@@ -102,15 +117,14 @@ Feature: Katapult in general
       end
 
       group :test do
-        gem 'parallel_tests'
         gem 'database_cleaner'
         gem 'timecop'
         gem 'launchy'
 
         gem 'capybara'
+        gem 'capybara-screenshot'
         gem 'cucumber-rails', require: false
         gem 'cucumber_factory'
-        gem 'cucumber_spinner'
         gem 'selenium-webdriver'
         gem 'spreewald'
 
@@ -120,7 +134,11 @@ Feature: Katapult in general
 
       """
 
-    And the file "config/database.yml" should contain exactly:
+
+
+      # Config
+      And the file "config/application.rb" should contain "config.time_zone = 'Berlin'"
+      And the file "config/database.yml" should contain exactly:
       """
       common: &common
         adapter: mysql2
@@ -135,10 +153,8 @@ Feature: Katapult in general
       test: &test
         <<: *common
         database: katapult_test_app_test<%= ENV['TEST_ENV_NUMBER'] %>
-
-      cucumber:
-        <<: *test
       """
+
     And the file "config/database.sample.yml" should contain exactly:
       """
       common: &common
@@ -151,30 +167,84 @@ Feature: Katapult in general
         <<: *common
         database: katapult_test_app_development
 
-      test: &test
+      test:
         <<: *common
         database: katapult_test_app_test<%= ENV['TEST_ENV_NUMBER'] %>
+      """
+
+    And the file "config/cucumber.yml" should contain:
+      """
+      default: <%= std_opts %> features
+      wip: --tags @wip:3 --wip features
+      parallel: <%= std_opts %> features <%= log_failures %>
+      rerun: -r features --format pretty --strict <%= rerun_failures %> <%= log_failures %>
+      """
+    And the file "config/initializers/find_by_anything.rb" should contain:
+      """
+      ActiveRecord::Base.class_eval do
 
-      cucumber:
-        <<: *test
+        def self.find_by_anything(identifier)
+      """
+    And the file "config/initializers/exception_notification.rb" should contain:
+      """
+      ExceptionNotification.configure do |config|
 
+        config.add_notifier :email, {
+          email_prefix: '[katapult_test_app] ',
+          exception_recipients: %w[fail@makandra.de],
       """
+    And the file "config/initializers/form_for_with_development_errors.rb" should contain:
+      """
+      if Rails.env == 'development'
+
+        ActionView::Helpers::FormHelper.class_eval do
+
+          def form_for_with_development_errors(*args, &block)
+      """
+
+
 
+    # Tests
     And the file "features/support/env-custom.rb" should contain:
       """
       require 'spreewald/all_steps'
       """
-    And a file named "features/support/paths.rb" should exist
-    And the file "spec/rails_helper.rb" should contain:
+    And the file "features/support/cucumber_factory.rb" should contain:
+      """
+      Cucumber::Factory.add_steps(self)
+      """
+    And the file "features/support/capybara_screenshot.rb" should contain:
+      """
+      require 'capybara-screenshot/cucumber'
+
+      # Keep up to the number of screenshots specified in the hash
+      Capybara::Screenshot.prune_strategy = { keep: 10 }
+      """
+    And the file "features/support/database_cleaner.rb" should contain:
+      """
+      DatabaseCleaner.clean_with(:deletion) # clean once, now
+      DatabaseCleaner.strategy = :transaction
+      Cucumber::Rails::Database.javascript_strategy = :deletion
+      """
+      And a file named "features/support/paths.rb" should exist
+      And a file named "features/support/selectors.rb" should exist
+      And the file "spec/rails_helper.rb" should match /^Dir.Rails.root.join.+spec.support/
+      And the file "spec/support/shoulda_matchers.rb" should contain:
       """
-      require 'rspec/rails'
       require 'shoulda/matchers'
+
+      Shoulda::Matchers.configure do |config|
+        config.integrate do |with|
+          with.test_framework :rspec
+          with.library :rails
+        end
+      end
       """
 
 
 
     # styles
-    And the file "app/assets/stylesheets/application.css.sass" should contain:
+    And the file "app/assets/stylesheets/application.sass" should contain:
       """
       @import compass
       @import bootstrap
@@ -182,7 +252,7 @@ Feature: Katapult in general
       @import application/blocks/all
 
       """
-    And the file "app/assets/stylesheets/application/blocks/_all.css.sass" should contain exactly:
+    And the file "app/assets/stylesheets/application/blocks/_all.sass" should contain exactly:
       """
       @import items
       @import layout
@@ -190,10 +260,10 @@ Feature: Katapult in general
       @import tools
 
       """
-    And a file named "app/assets/stylesheets/application/blocks/_items.css.sass" should exist
-    And a file named "app/assets/stylesheets/application/blocks/_layout.css.sass" should exist
-    And a file named "app/assets/stylesheets/application/blocks/_navigation.css.sass" should exist
-    And a file named "app/assets/stylesheets/application/blocks/_tools.css.sass" should exist
+    And a file named "app/assets/stylesheets/application/blocks/_items.sass" should exist
+    And a file named "app/assets/stylesheets/application/blocks/_layout.sass" should exist
+    And a file named "app/assets/stylesheets/application/blocks/_navigation.sass" should exist
+    And a file named "app/assets/stylesheets/application/blocks/_tools.sass" should exist
 
     # And the file "config/deploy.rb" should contain exactly:
     #   """