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.