In the last decade, Plataformatec has also created and maintained a range of open source projects. In the next paragraphs, I will describe what the next steps are for the open source projects currently owned by Plataformatec.

We are very proud of the contributions we have made to open source communities throughout our history. We have built important projects in the Rails community, such as Devise, Simple Form, among others. We have also developed the Elixir programming language, which started as a Research & Development project inside Plataformatec, and today is used by companies around the world.

So what will happen with these projects from now on?

All of the projects above have one thing in common: they were created and maintained by passionate individuals who wanted to make positive contributions to their communities. Without these individuals and their efforts, these projects would not have become what they are today. Therefore, it is only fair that Plataformatec gives these individuals control of these projects moving forward.

For the Elixir programming language in particular, José Valim and the Elixir Core Team will continue developing and maintaining the programming language in the same capacity as they have been doing over the last few years, independently from Plataformatec and Nubank. We are in touch with the Elixir Core Team to transfer all assets, including the existing trademarks and the Elixir website, to their control. The remaining Elixir projects will be transferred to José Valim and his team at Dashbit.

For all other Open Source projects under the Plataformatec organization on GitHub, we will reach out to the current maintainers and take the necessary steps to transfer the ownership of all relevant assets, including names, source code, and logos of such projects.

We are thankful to these communities for all the support and feedback they’ve given us throughout the years. We are glad to have been the home to these projects and to have worked with the teams that will continue shaping these projects from now on.

The post Important information about our Elixir and Ruby Open Source projects first appeared on Plataformatec Blog.

Conforme a organização em que trabalhamos cresce, vai ficando cada vez mais difícil acompanhar tudo o que está acontecendo. Pessoas novas vão entrando na equipe, ao mesmo tempo em que a base de código cresce numa velocidade ainda maior. O conhecimento técnico e de negócios, que antes era de conhecimento de todos os desenvolvedores, começa a se concentrar nas equipes, podendo gerar uma série de problemas:

• Diminuição da qualidade dos code reviews, pois algumas equipes podem estar desfalcadas de pessoas com conhecimento técnico ou de negócios
• Diminuição no número de code reviews em projetos de pouca visiblidade
• Redução no alinhamento entre as equipes, podendo resultar em retrabalho ou até mesmo bugs
• Risco de perda de conhecimento e dificuldade na realocação dos membros das equipes, já que alguns contextos podem se tornar muito dependentes de pessoas específicas

Como reduzir esses problemas?

Nem todos os code reviews são iguais

Os code reviews são uma excelente prática para melhorar a qualidade do código e diminuir o número de erros. Mas um outro benefício, tão importante quanto estes, é o compartilhamento de conhecimento entre os desenvolvedores.

Quando eu reviso um PR (Pull Request ou Change request, dependendo da ferramenta), sinto que conhecendo o seu contexto fica mais fácil fazer uma revisão mais aprofundada e assertiva. Dúvidas do tipo:

• Essa solução realmente resolve o problema?
• Existem maneiras melhores de resolver o problema?
• Essa funcionalidade faz sentido do ponto de vista de negócios?
• É viável prosseguir com essa funcionalidade agora?

Ficam mais mais fáceis de serem enxergadas e respondidas. Mas, para ter essas respostas, ter um bom conhecimento sobre o negócio é fundamental. Por isso, as vezes acabamos revisando apenas os PRs nos quais já temos contexto, sejam eles da nossa equipe ou de partes do sistema que já conhecemos. Se pensarmos no nível organizacional, esse tipo de comportamento pode resultar nos problemas citados, muitas vezes difíceis de serem diagnosticados.

Apresentando a Pirâmide de Code Reviews

Uma prática que pode ajudar a resolver esses problemas é a Pirâmide de Code Reviews.

Essa pirâmide, inspirada na Pirâmide de Testes, nos ajuda na priorização do que devemos fazer.

Pull Requests da nossa equipe são a base da pirâmide, pois são neles onde dedicaremos mais tempo. Como já possuímos o conhecimento necessário para fazer um bom code review, é provável que essas revisões sejam feitas mais rapidamente. Dessa forma, ajudamos os outros desenvolvedores a entregar seu trabalho com mais qualidade mais rapidamente.

No segundo nível da pirâmide temos dois grupos de PRs: aqueles em que já possuímos contexto e os chamados “PRs críticos”.

Os PRs que já possuímos contexto são mais óbvios: eles envolvem uma parte do código ou do negócio já conhecida pelo desenvolvedor, fazendo com que ele(a) se sinta confortável na revisão. Eles não diferem muito dos Pull Requests do próprio squad, porém como são externos, consideramos que haverão outras pessoas da squad envolvida ajudando na revisão. Por isso gastamos menos tempo neles.

Já os chamados “Pull Requests Críticos” são um pouco diferentes. Esses PRs podem implementar diferentes tipos de funcionalidades, desde resolver um erro crítico até mudanças na arquitetura, e é essencial que os desenvolvedores estejam alinhados com suas alterações. Esse tipo de Pull Request geralmente requer uma atenção imediata dos desenvolvedores, por isso é importante separar um tempo para revisá-los.

O que a pirâmide traz de diferente é tornar explícito que devemos inserir no nosso processo de trabalho as revisões exploratórias. Ou seja, não precisamos mais nos sentir restritos a(s) parte(s) do sistema onde trabalhamos. Pelo contrário, tendo a pirâmide em mente, nos sentimos incentivados a revisar outras partes do código e expandir nosso conhecimento do negócio.

Mas como começar por esse caminho? Será que meus code-reviews serão bem aceitos?

Começando os code reviews exploratórios

Ao revisar uma parte do código ou do negócio que não estamos familizados é natural nos sentir desconfortáveis ou inseguros. Podemos nos sentir desestimulados a discutir, com medo de fazer perguntas “estúpidas” ou redundantes. E se não conhecermos muito bem os desenvolvedores envolvidos no PR isso fica ainda pior. Resumindo: saímos da nossa zona de conforto.

Já apresentamos os benefícios dos code reviews exploratórios, porém como devemos proceder na hora de revisar código desconhecido, onde supostamente nossa efetividade vai ser menor? E como devemos reagir quando uma pessoa de fora revisa o código e começa a fazer perguntas ou questionamentos?

Como o próprio nome já diz, estamos explorando uma parte desconhecida do projeto, por isso ter uma atitude curiosa é essencial. Fazer perguntas, dar dicas e sugestões e compartilhar experiências são ótimos pontos para se ter em mente nessas revisões. Ter bom senso também é importante aqui, pois não precisamos entender todo o contexto de negócio logo de cara na primeira revisão. Identificar o contexto mínimo que precisamos para fazer a revisão é vital para não onerarmos demais o nosso tempo nem o dos demais participantes.

E quando recebermos esse tipo de revisão é importante ter uma atitude respeitosa e didática nos comentários. Perguntas devem ser respondidas sempre educadamente e com um nível suficiente de detalhes(o bom senso vale aqui também). Respostas atravessadas ou incompletas podem prejudicar as revisões e desestimular os revisores a continuarem com essa prática. Lembre-se: ninguém é dono do código, o código que você está fazendo agora será usado por outros desenvolvedores no futuro. E vice-versa. Um ambiente amigável durante as revisões vai tornar essa prática muito mais proveitosa para todas as partes envolvidas.

E quais critérios devemos usar para escolher aonde vamos explorar? Bem, a decisão final fica por sua escolha. Mas se você souber de alguma parte do projeto que carece de revisões, pode ser uma boa idéia dar uma explorada por lá.

Quanto tempo devo me dedicar aos code reviews exploratórios? Isso varia de cada contexto. Se você tem bastante tempo livre para explorar outras partes do código, faça isso! Já se você não tiver tanto tempo assim, tente dedicar pelo menos algumas horas por semana para explorar. Um bom começo seria fazer pelo menos uma revisão exploratória por semana.

E você, como organiza seu tempo para revisar PRs? Você se sentiria confortável em adotar essa prática onde você trabalha? Deixe seu comentário logo abaixo.

The post Como evitar silos de conhecimento na sua codebase e levar seus code reviews para o próximo nível first appeared on Plataformatec Blog.

To illustrate this problem, consider a simple application of storing and listing contacts. You have an actor user that can sign up, sign in, then can CRUD their contacts with first name, last name and phone number. We are in a context of multiple developers working together, programming and delivering features every day. For the examples below I’ll use Ruby, RSpec, Capybara and Ruby on Rails.

Suppose we have a UI testing using RSpec features test like this:

#spec/features/contacts_spec.rb
feature 'User can create new contact' do
  scenario 'when user provides valid contact information' do
    login_with email: 'default@mail.com', password: 'default'

    click_link 'Contacts'

    expect(page).to have_content('Listing Contacts')
    expect(page).to have_content("There're no contacts.")

    click_link 'New Contact'

    fill_in 'First name', with: 'Jon'
    fill_in 'Last name', with: 'Doe'
    fill_in 'Phone number', with: '1199999999'

    click_on 'Create Contact'

    expect(page).to have_content('Listing Contacts')
    expect(page).to have_content('Jon Doe - (11) 9999-9999')
  end
end

Simple and straight forward. The good part of this test is it checks the entire application stack: authentication, rendering, storing stuff on the database and the logic of creating contacts. Some developer may be confident with this test and start to question: Should I add more unit tests? For phone number formatting? For displaying complete names? For user authentication? For contact validation and creation? If one of these features fail, this feature test will fail too. Why should I care to add more tests? Isn’t it redundancy? Waste of time? The short answer is you should add more unit and integration tests because of feedback. Now, let’s expand the topic.

Speed matters

We know the UI test brings confidence since it tests the entire stack of your application. But overusing this type of tests will severely impact your test suite speed.

In our contacts creation test example, we have some edge cases that were not covered. What happens if we use a different size of numbers in the telephone number field? How will it be displayed? We can add a new UI test to cover this case, but a unit test suits better and faster. If the number formatting is a view helper we can check it with a helper test, for example:

describe '#format_phone_number' do
  it 'formats cell phones numbers of 10 digits in "(XX) XXXXX-XXXX" format' do
    formatted_number = helper.format_phone_number('11999998888')
    expect(formatted_number).to eq '(11) 99999-8888'
  end

  it 'does not format others digits different of 10' do
    formatted_number = helper.format_phone_number('11888')
    expect(formatted_number).to eq '11888'
  end
end

This test is way easier to write, read, cheaper and faster than adding a new UI to test this specific case. Keeping this practice, you will have fewer UI tests and more integration and unit tests. Such distribution of the different kind of tests resembles the format of a pyramid:

Few UI tests on top and a solid base of unit tests. If you want more information about the test pyramid, I recommend you the following links:

• The Forgotten Layer of the Test Automation Pyramid by Mike Cohn
• The Test Pyramid by Kenneth Truyers
• TestPyramid by Martin Fowler
• We have a talk and a video explaining the test pyramid in portuguese.

Helpful messages

In the daily routine of a development team, the code is constantly evolving. The test server is running and warning when the test suite is passing or broken. A passing test suite is a requirement to deploy a new change in production in most of the clients that we have been working on. Then when the test suite fails, it is important for developers to act and fix the broken tests fast. Without helpful messages, it is critically hard.

Let’s use again our contacts UI test, let’s use a scenario where we just have that test. The application has received new changes and the test server warns the team that we have an error, and the output is:

  1) User can create new contact when user provides valid contact information
     Failure/Error: expect(page).to have_content("Jon Doe - (11) 9999-9999")
       expected to find text "Jon Doe - (11) 9999-9999" in "default@mail.com Log out Contacts Contact was successfully created. Contact was successfully created. Listing Contacts Jon Doe - 1199999

We know the test failed in the last step, the step of checking the recent contact content in the listing page. In this sample application, we have a small text to search what’s going on. In a real world application, this content can be a lot bigger and unproductive to read. From here the developer has a lot of possibilities to search what the root cause of the problem. For example:

• Is it in the creation?
• Is it in the contacts listing?
• Is it in the telephone format method?
• Is it in the test?
• Had been changes to asynchronous request and expectation didn’t have time to assert the new content?

The list can go on depending on your creativity. Now let’s build a scenario where we also have the format_phone_number helper unit test. The tests are failing, but now have this output:

1) User can create new contact when user provides valid contact information
     Failure/Error: expect(page).to have_content("Jon Doe - (11) 9999-9999")
       expected to find text "Jon Doe - (11) 9999-9999" in "default@mail.com Log out Contacts Contact was successfully created. Contact was successfully created. Listing Contacts Jon Doe - 1199999999 Show Edit Destroy New Contact"

2) ContactsHelper#format_phone_number formats cell phones numbers of 10 digits in "(XX) XXXXX-XXXX" format
   Failure/Error: expect(helper.format_phone_number('11999998888')).to eq '(11) 99999-8888'

     expected: "(11) 99999-8888"
          got: "11999998888"

     (compared using ==)

Now we have two failing tests. The second error message is way easier to guess why it is broken. Some change on the format_phone_number helper has broken the cell phone formatting. Knowing it, looking again at the first error message you may connect the dots and find out the errors are connected.

If two tests are failing for the same reason, this is not the same thing of worthless redundancy. Focused behavior tests bring you a lot more information for debugging, helping you solve problems fast. This is another benefit of the test pyramid.

Conclusion

Some people tend to be relaxed about worry too much about creating focused tests. I think the main reason is they are very used to code base context. If something fails they can navigate, debug and figure out fast what happened. But unfortunately, it not always true for everyone, specially for the newcomers.

Another problem is when the team becomes careless about covering exceptional cases with unit and integrations tests. The test suite is always green but problems are increasing in production. Your test suites become less reliable and leaving the entire team insecure about deploying new changes.

To keep your test suite fast and worthy of trust I recommend you use the test pyramid technique. In Rails applications will be something like:

• Fewer UI tests with Capybara. Use them to test the user main journey and some exceptional cases.
• Test beyond the expected behavior. Exercise the exceptional behaviors with integration and unit tests. Write more models, controllers, requests, views, helpers, or mailers tests.
• Consider adding JavaScript unit tests in your test suite.

These practices help us a lot to maintain a healthy code base and allow us to adapt and be more agile to change. What do you think of this practices? Which techniques and practices are you doing to keep your test suite fast and with helpful messages? Let me know with a comment below.

The post Using the test pyramid to have better feedback from your test suite first appeared on Plataformatec Blog.

The first highlight comes from the night before the event. We went to a bar with some conference speakers. It was really fun to chat with everyone there. Besides, Serdar Doğruyol, who talked about the Crystal framework called Kemal, brought us a box of Turkish Delights. And when I say “delights”, I mean it :yum:.

During the event, I made new friends and met old ones. I had great conversations about hiring, team building, technologies and mainly Ruby and Elixir. It is very clear that the community is more mature than ever.

Talking about Elixir, this year there were a high number of languages being talked about. As I could list, I’ve seen talks about Clojure, Crystal, JavaScript, Go, Ruby and Elixir.

Another thing that caught my attention was the large number of people trying Elixir in Brazil. I was even more surprised to know that a lot of them already have production-running apps. Here are some interesting talks about Elixir:

• 10 things I’ve learned in my first Phoenix + Elixir Project (a Rubyist point of View), by Fabiano Beselga
• Building a Twitter clone with Phoenix and Vue.js, by Philip Sampaio
• Measuring your Elixir application, by Renan Ranelli (Milhouse)
• How Elixir helped us scale our video user profile service for the Olympics, by Emerson Macedo
• Phoenix for Rubyists, by Mike North
• Elixir dev to prod: challenges encountered, by Guilherme Nogueira

In addition, eight coworkers from Plataformatec spoke at the event. Some about Ruby, some about Elixir and some about development process and culture. I’d like to greet them and also list their talks:

• From ASP.NET to Rails: the best parts, by Philippe Hardardt
• How does Rails Work?, by Flavia Fortes
• How to fix projects, by Wesley Zapellini
• Rails 5 and its new features by examples, by Yoshio Teruia
• Debugging Techniques in Elixir, by Erich Kist (this talk was presented in English in last ElixirConf)
• You’re not alone, go to production with Elixir, by Igor Florian
• Ruby on Rails Security: common faults and some not so obvious, by Diego Viera
• The Zen and Art of Refactoring, by Lucas Mazza

Also, I am very excited to say that Ebert, the first Plataformatec product, went public during the event. I am very happy we made it. It’s a tool we’ve been using internally and for our clients, which now is available for everyone.

Ebert has helped our team by doing continuous static analysis on GitHub repositories and delivering it straight to Pull Request. By automating some checks, it allowed us to focus on important issues. If you haven’t checked it yet, give it a try.

The last highlight is that Fabio Akita will not be part of the conference organization anymore. That said, Locaweb already twitted that the event will continue next year.

Well, that’s all for now. I hope you’ve enjoyed the event as much as we did. Tell us your thoughts on the comments below!

The post Highlights of RubyConf Brazil 2016 first appeared on Plataformatec Blog.

You can try the new Rails version using the published guides and report any problem you may find on Rails issue tracker.

Why update?

I think it is an important question you may need to answer to your team members. My favorite reasons are: security, bug fixes, and features.

Rails has supported versions to receive security fix releases. If you are in a version not supported, you may be vulnerable. You should read the security policies and check if your app is using the supported versions.

The framework also has maintenance policies that you should be aware of. Performance improvements and bug fixes you may miss if your app is too old. You need to code by yourself and do workarounds to have the same benefits, a code that would be more reliable being inside the framework.

We usually hear developers complaining about applications that use old versions of the framework. The reason is new versions of the tool usually bring improvements to make the developer’s life easier. In the developer’s perspective, it’s demotivating knowing there’s a robust, elegant and productive way to do things and they are not able to use it.

Keeping your Rails up to date will help your code base health and also can be a factor of motivation for your team.

What I should do?

We have been maintaining and evolving several old Rails apps in different contexts for years, and we have seen some practices that make it easier to keep your app updated:

• strict use of gems
• avoid monkey patches
• keep a good test coverage

Gems

Adding new dependencies using RubyGems and bundler is awesome, but overusing gems can not only slow your app down but slow you with the amount of work you need to update your Rails version. Some gems are coupled to the framework when you update it. These gems may break. When they break, you need to update them together.

I recommend you considering these points before putting a new gem in your Gemfile:

• Is this gem adding great value to your project? Some gems increase your app security, solve complex problems and reduce a lot of worktimes. Other gems add less value and can easily be replaced with your own implementation. Sometimes, it’s worth doing your own implementation than depending on a third­party code.

• Is this gem well maintained? It’s good checking if the commits are recent, the project is well documented, the changelog contains helpful messages between releases, the maintainers often close issues and answer them respectfully. These are good signs that the gem you are adding won’t give you trouble in the future.

Adding a gem to your project is adding a coupling. Software coupling has its downsides, for example, the ripple effect of changes. The downside of more work to update your dependencies will be worth it if you accurately added them. If you want to learn more about downsides of dependencies, you can read this blog post about Ruby dependencies and this one about Node.

Avoid monkey patches

Monkey patches are often used to change the behavior of the code you don’t own. For example, rewriting or adding Ruby standard library classes or methods to fit your application needs. Careless monkey patches can bring you serious problems while updating Rails.

Adding code that changes the behavior of gem classes can result in hidden bugs and turn any upgrade into a painful experience. It’s often uncertain how many objects are depending on your change and predicting all the effects of the monkey patched method. For example, in a new version of the gem, your monkey patch can change a method that was updated or doesn’t even exist anymore.

We have seen some monkey patches that are a gem fix or enhancement. These changes may benefit others users of the gem and were hidden in application code. You may get in touch with gem maintainers and propose your changes. If your contribution is accepted, your fix will have a solid and proper place to be.

If your behavior is specific for your app, you should consider extending the gem and applying your wanted behavior using the conventional OO practices. For example, you can create an adapter class, subclass or composition. You may also take a look at Ruby Refinements. Using this structure, you can create scoped changes that must be used explicitly. Explicit code reduces costs to maintain the app and the effort of updating to a new Rails version.

After checking all previous solutions and you still think that a monkey patch better suits your needs, you should know there are organized ways of adding them. Regardless of coding, I recommend you to add a great documentation to keep it sane for your teammates and your future self. In this documentation, you should describe why it is necessary, when it can be removed and how it can be removed. It will help a better understanding of the app and provide useful information while updating your Rails app.

Keep a good test coverage

We all need to pay special attention to the tests. Some changes while updating Rails will be required and having a trustful test suite will help you discover problems before deploying your app to your end users.

Having 100% of test coverage is no guarantee of testing the correct behavior. I would say the team should have a test coverage that they feel confident about.

Some symptoms that your application doesn’t have good coverage is when recurrent errors are found while the application is running and all your automated tests are passing. You may use a tool like simplecov to check your coverage rate, having a very low coverage is a bad sign.

Adding proper tests is the only solution for low test coverage. If you are in this situation, you should start adding tests focused on the most used and important features. Having a good test coverage is essential to evolve because its main purpose is providing fast feedback that previously working features are still working.

Conclusion

Keeping the application’s Rails version updated is a responsibility that should not be ignored since it brings improvements for your team and security for your users.

I hope these tips help you keep your code easy to update.

Do you have more tips? Please leave comments below and tell us about your experience to keep your application up to date.

The post Keeping your Ruby on Rails app easy to update first appeared on Plataformatec Blog.

A Tale of Two Adapters

Back in November, I worked on integrating a payment gateway from scratch into one of our client projects, through a gem that abstracts the HTTP interface of this external service. On this payment flow we had to first authorize the payment data with the gateway, which would return the transaction data for us to capture the payment in the background and go on with the business logic that depended on a successful payment flow.

If you ever worked on something similar, you probably remember a few rough edges that we need to deal in cases like this: how to test the integration with the right credit card numbers for each possible outcome? Do we have a sandbox available for development and test environments? How can we control the performance and stability costs that this external dependency might bring to our application, and the coupling between the code that supports this core feature and this gem?

Our attempt to handle the coupling and maintenance cost of this dependency was to push all the integration code behind an abstraction layer responsible for dealing with this payment flow logic under a Payments namespace.

require 'gateway-xyz-gem'

module Payments
  class GatewayXYZ
    def authorize(order, credit_card)
      # Uses the `Order` details and the user `CreditCard` data to authorize
      # a new transaction on the XYZ Payment Gateway through the
      # `gateway-xyz-gem` classes.
    end

    def capture(payment_id)
      # Capture the payment information for a transaction that was previously
      # authorized.
    end
  end
end

Somewhere down our orders#create action (but not directly in the controller method itself) we call GatewayXYZ#authorize with the order record and a credit_card value object and our integration with the external service is done.

We might have a nice set of well-defined methods on the GatewayXYZ class but our job on these abstractions is far from done. We might unit test it with something like WebMock or VCR to handle the external service dependency, but every other piece of our system that interacts with this abstraction will also depend on the external API to work properly – the OrdersController, the background job that captures the payment and the Order model itself that might trigger the initial authorize call. Should we just sprinkle the existing stubs all over our test suite and call it a day?

We added a gateway implementation that mimics the expected behavior of the GatewayXYZ (with the same method signatures as the real gateway) and doesn’t depend on external resources. It also has a predefined behavior for specific inputs so we can test different code paths of their collaborators based on the test input.

module Payments
  class Memory
    def authorize(order, credit_card)
      if BAD_CREDIT_CARD_NUMBERS.include?(credit_card.number)
        bad_response
      else
        ok_response
      end
    end
  end
end

Dealing with environment specific setups

Now we need to make our Payments::Memory the go-to implementation for our test cases that depend on our payment abstractions. There are a few different ways we can do this on a Rails app.

Rails.application.config

We can expose a configuration setting in app that says which implementation it should use, similar to how Action Mailer picks the delivery method for your emails or how Active Job might have different queue adapters for your background jobs.

# config/application.rb
Rails.application.config.x.payment_gateway = Payments::GatewayXYZ

# config/environments/test.rb
Rails.application.config.x.payment_gateway = Payments::Memory

# app/models/order.rb
class Order
  def authorize(credit_card)
    gateway = build_gateway
    gateway.authorize(self, credit_card)
  end

  private

  def build_gateway
    klass = Rails.application.config.x.payment_gateway
    klass.new
  end
end

Module.mattr_accessor macro

You can set a class level macro on the classes that depend on a configurable value and change as you want in your code. This approach can be useful if you want to keep the configuration closer to the implementation that relies on it, instead of jumping between app code and configuration code if you want to debug something or be able to change it during runtime.

# app/models/order.rb
class Order
  cattr_accessor :payment_gateway do
    Payments::GatewayXYZ
  end

  def authorize(credit_card)
    gateway = payment_gateway.new
    gateway.authorize(self, credit_card)
  end
end

# test/test_helper.rb
Order.payment_gateway = Payments::Memory

Factory method

This approach is useful when you want to hide away how to create an instance of a gateway implementation, so other classes that depend on it can have a way to just ask for a gateway object without worrying on how to create it.

# app/models/payments.rb
module Payments
  matt_accessor :gateway do
    Payments::GatewayXYZ
  end

  def build_gateway
    gateway.new
  end

  module_function :build_gateway
end

# test/test_helper.rb
Payments.gateway = Payments::Memory

I don’t believe that there is a Single Way to Do It this kind of dependency injection, so you should feel free to pick a strategy that suits the interfaces you are building and the coding style of your team – I’m personally a fan of the factory method and the cattr_accessor approaches as they feel more detached from the configuration and closer to the application code, although the configuration way feels more aligned with global APIs from 3rd party gems.

Skipping Hash driven development

Our GatewayXYZ and Memory implementations have the same methods with the same arguments but there is a second piece of making a uniform API that we need to think about: what those methods should return?

Our authorize needs to return more than a truthy/falsy value, as we need to gather more information about the payment transaction on our end, like the payment_id from the transaction, or a reason of why it might have failed (was the credit card denied? There is invalid data in the request), details for logging or instrumentation, etc. And if we think about implementing this API for multiple services (let’s say we need a Payments::PayPal now, for instance), those services will return this data in different formats that we need to normalize so these differences don’t leak to the rest of the system.

One might say that a Hash with all this junk would do it, but going that path opens too many doors for inconsistency and bugs as the hash is a weak abstraction that can be mutated anywhere and won’t enforce any specific format or requirements on the return values.

For that, we can implement a Payments::Result struct/value object to represent the outcome of our authorize action, and return it from each gateway implementation in our system, enforcing the interface we want to have.

module Payments
  class Result < Struct.new(:payment_id, :errors)
    def ok?
      errors.blank?
    end

    def failed?
      !ok?
    end
  end
end

Our Result class has the minimal information that our client code needs, and each gateway is responsible for constructing a Result from its own data. The Memory gateway can do something as straightforward as this:

module Payments
  class Memory
    def authorize(order, credit_card)
      Result.new(
        payment_id: SecureRandom.hex,
        errors: SAMPLE_ERRORS[credit_card.number])
    end
  end
end

This approach is useful not just for enforcing the interface we want, but also to improve other areas of our code that could use more specific abstractions than a bare Hash instance.

Going forward with contracts and macros

This homemade approach for better contracts between our app and this external service can go a long way, but if you want, you can build strict checks on top of your APIs to ensure that your objects are collaborating as you expect. We haven’t tried yet, but the contracts gem looks very interesting if you want that kind of type constraints that are lacking on Ruby.

You can even write your own checks by wrapping methods into type checking proxies, as refile does with its Refile::BackendMacros module. When extended by a backend implementation, it provides macros to validate the input for methods like #upload(uploadable) or #delete(id), so custom implementations don’t need to worry about validating these arguments on their own.

The post Experimenting with explicit contracts with Ruby first appeared on Plataformatec Blog.