kinetic_cafe_error¶ ↑

code

github.com/KineticCafe/kinetic_cafe_error/

bugs

github.com/KineticCafe/kinetic_cafe_error/issues

continuous integration

<img src=“https://travis-ci.org/KineticCafe/kinetic_cafe_error.png” />

Description¶ ↑

kinetic_cafe_error provides an API-smart error base class and a DSL for defining errors. Under Rails, it also provides a controller concern (KineticCafe::ErrorHandler) that has a useful implementation of rescue_from to handle KineticCafe::Error types.

Exceptions in a hierarchy can be handled in a uniform manner, including getting an I18n translation message with parameters, standard status values, and meaningful JSON representations that can be used to establish a standard error representations across both clients and servers.

Synopsis¶ ↑

Define a hierarchy with KineticCafe::Error.hierarchy.

KineticCafe::Error.hierarchy class: :MyBaseError do
  not_found class: :user # => MyBaseError::UserNotFound
  unauthorized class: :user # => MyBaseError::UserUnauthorized
  forbidden class: :user # => MyBaseError::UserForbidden
  conflict class: :user# => MyBaseError::UserConflict
end

There are a few documented ways to define hierarchies. Examples for handling exceptions can be found in the provided Minitest assertions module and the RSpec matchers.

Using with Rails¶ ↑

When using KineticCafe::Error with Rails, KineticCafe::ErrorEngine is automatically injected, which enables the following functionality:

• Two rake tasks:

  • rake kcerror:defined[params], showing the errors defined in the known hierarchy. If params is ‘yes’, the expected parameters will be shown.

  • rake kcerror:translations[output], creating a template translation file for all defined errors.

• An error view, kinetic_cafe_error/page, in ERB, HAML, and Slim formats. This also has a partial, kinetic_cafe_error/_table. This allows KineticCafe::Error classes to be used in HTML contexts as well as JSON contexts.

• Access to the kinetic_cafe_error translation files for English and French, used in logging and in the error view.

• A controller concern, KineticCafe::ErrorHandler, that defines a rescue_from handler for descendants of the KineticCafe::Error class, and a error handler generator, #kinetic_cafe_error_handler_for, that sets a rescue_from handler for a KineticCafe::Error hierarchy that does not descend from KineticCafe::Error itself.

  #kinetic_cafe_error_handler distinguishes between HTML and JSON contexts.

  The error will be logged in a single language, with a configuration option that can be provided with the kinetic_cafe_error_handler_log_locale helper method.

  The error can be then captured for processing by providing the kinetic_cafe_error_handle_post_error method.

  Example for capturing KineticCafe::Errors with raven-ruby for Sentry:

  ExampleController < ActionController
    include KineticCafe::ErrorHandler
  
    def kinetic_cafe_error_handle_post_error(error)
      Raven.capture_exception(error)
    end
  end

Using with Minitest¶ ↑

KineticCafe::Error provides a number of assertions that can help testing that your code returns KineticCafe::Error hierarchies.

• #assert_kc_error when used with the return value of assert_raises, verifies that the captured exception is the expected exception, including parameters. Also available as #must_be_kc_error.

• assert_kc_error_json when used with a response body, verifies that the response is the same as would be generated with the requested error class. Also available as #must_be_kc_error_json.

• assert_response_kc_error_html works with ActiveSupport::Test; it asserts that the kinetic_cafe_error/page template has been rendered and that the expected class I18n key is part of the response body. Depends on @response.body being part of the available test environment.

• assert_response_kc_Error works with ActiveSupport::Test and checks @request.format to determine whether to forward to #assert_response_kc_error_html or #assert_kc_error_json.

Get access to these with:

require 'kinetic_cafe/error/minitest'

In your test setup code.

Using with RSpec (Experimental)¶ ↑

KineticCafe::Error provides four experimental matchers:

• be_json_for verifies that the JSON in the actual string or body match the expected data structure.

• be_kc_error verifies that the error is the expected class and renders properly with the same parameters.

• be_kc_error_json verifies that the JSON provided that the JSON output of the expected is generates the same JSON.

• be_kc_error_html verifies that the response renders the kinetic_cafe_error/page template.

Install¶ ↑

Add kinetic_cafe_error to your Gemfile:

gem 'kinetic_cafe_error', '~> 1.8'

If not using Rails, install with RubyGems:

gem install kinetic_cafe_error

And require where needed in your application:

require 'kinetic_cafe_error'

Community and Contributing¶ ↑

kinetic_cafe_error welcomes your contributions as described in Contributing.md. This project, like all Kinetic Cafe open source projects, is under the Kinetic Cafe Open Source Code of Conduct.