Welcome to the first blog post in our cycle directed to less-experienced developers. We will be diving into the world of more advanced concepts - however, each one should be easily digestible by junior+ - mid developer. It’s one of the ways we want to give back to the community.

In this blog post we will focus on solving a simple task:

Retrieve a random quote from API https://talaikis.com/api/quotes/random/ and display it in terminal (in some pretty format).

What is the catch here? We want our code to be thoroughly tested and use proper Object Oriented Programming (OOP).

Side note: the techniques shown here will be a case of overengineering, given the complexity of the task

Let’s start coding! How about starting with some simple code that will do the job well?

require 'bundler/inline' gemfile do source 'https://rubygems.org' gem 'httparty' end require 'json' server_raw_output = HTTParty . get ( 'https://talaikis.com/api/quotes/random/' ). body quote_hash = JSON . parse ( server_raw_output ) print quote_hash [ 'author' ] print ': ' puts quote_hash [ 'quote' ]

Run it:

$ ruby quotes.rb Laurence J. Peter: The best intelligence test is what we do with our leisure.

Yay! It works!

Please take a note that we’ve used inline bundler syntax - which is helpful for simple scripts.

However, this code has some problems:

it is barely testable (it would require a lot of mocking monkey-patch-style)

it isn’t very object-oriented

So, let’s start some refactoring! Let me stress again that we will be doing overengineering here.

Let’s look at our code and start by wrapping it all in a class and changing print to simply returning string (always try to separate side-effects of functions as much as you can):

require 'bundler/inline' gemfile do source 'https://rubygems.org' gem 'httparty' end require 'json' class Quote def random_quote server_raw_output = HTTParty . get ( 'https://talaikis.com/api/quotes/random/' ). body quote_hash = JSON . parse ( server_raw_output ) quote_hash [ 'author' ] + ': ' + quote_hash [ 'quote' ] + "

" end end # this is a pythonic way of only running this code # if it's executed directly and # not required from elsewhere # we do this for the sake of testing later print Quote . new . random_quote if $PROGRAM_NAME == __FILE__

(Why instance method instead of class one? You will see soon, in this state it doesn’t matter, but in the end it will make a difference).

Let’s stop here for a moment and think about the first of rules for good object-oriented design SOLID principles, i.e., Single Responsibility Principle.

Single Responsibility Principle Every module or class should have responsibility over a single part of the functionality provided by the software, and the class should entirely encapsulate that responsibility.

In other words (more practical): classes should have only one reason to change. Let’s take a look… oops! When we’re looking at our class, we see A LOT of reasons to change. Starting from switching connection protocol, through changing the parsing method to different printing style. We need to do something about it and stop violating SRP so… violently.

Great step for make it compliant with SRP is to work on untangling implicit classes connections, one by one. First of all, looking from the top, we encounter the line:

server_raw_output = HTTParty . get ( 'https://talaikis.com/api/quotes/random/' ). body

Yep, we have an implicit class usage. We will use very strict OOP here, meaning an object can use only classes explicitly provided in the constructor (usually you would also allow stdlib classes). So, let’s write the first of series of our small classes - that one will be called QuoteConnector . It will serve only as a method of requesting data from a remote server and returning a string representing its body.

# lib/quote_connector.rb require 'httparty' class QuoteConnector URL = 'https://talaikis.com/api/quotes/random/' . freeze # since this is constant, we REALLY don't want to mutate it def initialize ( adapter: HTTParty ) @adapter = adapter end def call adapter . get ( URL ). body end private attr_reader :adapter end

Let’s stop here for a second. We did something in the constructor - something that should be familiar with people who coded in Java. It’s called Dependency Injection. That way in a typical environment we will be using the HTTParty library and in our test environment, we will inject our custom, mocked class (without re-opening existing classes or injecting our mocks elsewhere). Otherwise, it’s an elementary class - this is how we roll.

Let’s look at irb usage of our class:

irb ( main ): 017 : 0 > QuoteConnector . new . call => "{ \" quote \" : \" That which is so universal as death must be a benefit. \" , \" author \" : \" Friedrich Schiller \" , \" cat \" : \" death \" }"

So, everything works as expected. Time to write some tests! I will be using Minitest - because I like it.

# test/quote_connector_test.rb require 'minitest/autorun' require_relative '../lib/quote_connector' require 'ostruct' class DummyRequest def self . get ( * ) OpenStruct . new ( body: 'test' ) end end class TestConnector < Minitest :: Test def test_call connector = QuoteConnector . new ( adapter: DummyRequest ) assert_equal 'test' , connector . call end end

We need a fake HTTParty connector to provide as a mock to our QuoteConnector class. But! We aren’t reopening the existing class, nor modifying anything in the code. That’s the beauty of DI.

Run tests:

$ ruby test /quote_connector_test.rb Run options: --seed 62844 # Running: . Finished in 0.001075s, 1860.4651 runs/s, 1860.4651 assertions/s. 1 runs, 1 assertions, 0 failures, 0 errors, 0 skips

Great! Since it’s correct, let’s plug QuoteConnector into the existing code:

require 'bundler/inline' gemfile do source 'https://rubygems.org' gem 'httparty' end require 'json' require_relative 'lib/quote_connector' class Quote def initialize ( connector: QuoteConnector ) @connector = connector end def random_quote server_raw_output = connector . new . call quote_hash = JSON . parse ( server_raw_output ) quote_hash [ 'author' ] + ': ' + quote_hash [ 'quote' ] + "

" end private attr_reader :connector end print Quote . new . random_quote if $PROGRAM_NAME == __FILE__

A little better. We need to provide QuoteConnector in the constructor to be compliant with our own rules.

Let’s look down… A-ha! We see a reference to the JSON class which isn’t specified anywhere. Time to change that! Let’s write another class - this time called QuoteParser .

# lib/quote_parser.rb # let's take note that it's a bit of overkill # since JSON is in stdlib # but hey, we're doing EXOOP (extreme oop)! class QuoteParser def initialize ( object_to_parse :, parser_class: JSON ) @object_to_parse = object_to_parse @parser_class = parser_class end def call parser_class . parse ( object_to_parse ) end private attr_reader :object_to_parse , :parser_class end

How does it work? Let’s look into irb…

irb ( main ): 033 : 0 > QuoteParser . new ( object_to_parse: QuoteConnector . new . call ). call => { "quote" => "Beauty is only skin deep. I think what's really important is finding a balance of mind, body and spirit." , "author" => "Jennifer Lopez" , "cat" => "beauty" }

Looking good! And it seems the classes are working together, excellent.

Time to test it, similar to testing QuoteConnector :

# test/quote_parser_test.rb require 'minitest/autorun' require_relative '../lib/quote_parser' require 'ostruct' class DummyQuoteParser def self . parse ( hash_to_parse ) hash_to_parse end end class TestQuoteParser < Minitest :: Test def test_parser_call test_hash = { 'author' => 'Rainbow Dash' , 'quote' => '[So] Awesome!' } parser = QuoteParser . new ( object_to_parse: test_hash , parser_class: DummyQuoteParser ) assert_equal ( test_hash , parser . call ) end end

And, as tests are passing, time to plug it into our entry point class:

require 'bundler/inline' gemfile do source 'https://rubygems.org' gem 'httparty' end require 'json' require_relative 'lib/quote_connector' require_relative 'lib/quote_parser' class Quote def initialize ( connector: QuoteConnector , parser: QuoteParser ) @connector = connector @parser = parser end def random_quote server_raw_output = connector . new . call quote_hash = parser . new ( object_to_parse: server_raw_output ). call quote_hash [ 'author' ] + ': ' + quote_hash [ 'quote' ] + "

" end private attr_reader :connector , :parser end print Quote . new . random_quote if $PROGRAM_NAME == __FILE__

So far, so good! It seems like we’re only missing one class in the random_quote method - some presenter, that will transform our JSON data into strings ready to be displayed. Time to write it!

# lib/quote_presenter.rb class QuotePresenter def initialize ( quote_hash :) @quote_hash = quote_hash end def to_s " #{ quote_hash [ 'author' ] } : #{ quote_hash [ 'quote' ] }

" end def present # we combine two pretty useful conventions here: # classes should implement to_s method that # will return a string representation of them ✓ # presenters should implement present method # that will return their data formatted ✓ to_s end private attr_reader :quote_hash end

How does it work?

irb ( main ): 055 : 0 > QuotePresenter . new ( quote_hash: QuoteParser . new ( object_to_parse: QuoteConnector . new . call ). call ). present => "Joseph Jackson: It's all about the money.

"

Time for a little bit of test:

# test/quote_presenter_test.rb require 'minitest/autorun' require_relative '../lib/quote_presenter' require 'ostruct' class TestQuotePresenter < Minitest :: Test def setup @test_hash = { 'author' => 'Rainbow Dash' , 'quote' => '[So] Awesome!' } @output = "Rainbow Dash: [So] Awesome!

" end def test_presenter_to_s presenter = QuotePresenter . new ( quote_hash: @test_hash ) assert_equal ( @output , presenter . to_s ) end def test_presenter_present test_hash = { 'author' => 'Rainbow Dash' , 'quote' => '[So] Awesome!' } presenter = QuotePresenter . new ( quote_hash: @test_hash ) assert_equal ( @output , presenter . present ) end end

Nothing new here - only take note that we’re testing both to_s and present methods.

And let’s of course plug it back into our quote class:

require 'bundler/inline' gemfile do source 'https://rubygems.org' gem 'httparty' end require 'json' require_relative 'lib/quote_connector' require_relative 'lib/quote_parser' require_relative 'lib/quote_presenter' class Quote def initialize ( connector: QuoteConnector , parser: QuoteParser , presenter: QuotePresenter ) @connector = connector @parser = parser @presenter = presenter end def random_quote server_raw_output = connector . new . call quote_hash = parser . new ( object_to_parse: server_raw_output ). call presenter . new ( quote_hash: quote_hash ). present end private attr_reader :connector , :parser , :presenter end print Quote . new . random_quote if $PROGRAM_NAME == __FILE__

Yay! We’ve got the whole enchilada working. And for our final touch - let’s write tests for the Quote class that will check the integration of all classes along the way:

# test/quote_test.rb require 'minitest/autorun' require_relative '../quote' require 'ostruct' class DummyConnector def call { 'a' => 'b' } end end class DummyParser def initialize ( object_to_parse :) @object_to_parse = object_to_parse end def call object_to_parse end private attr_reader :object_to_parse end class DummyPresenter def initialize ( quote_hash :) @quote_hash = quote_hash end def present quote_hash end attr_reader :quote_hash end class TestQuote < Minitest :: Test def test_random_quote quote_object = Quote . new ( connector: DummyConnector , parser: DummyParser , presenter: DummyPresenter ) assert_equal ({ 'a' => 'b' }, quote_object . random_quote ) end end

We need three mocked classes to inject them into Quote , and then we’re checking if the chain of classes is returning the message as we intend it to.

In conclusion - we’ve written four small classes, each having exactly one responsibility and one reason to change. We’ve tested them extensively and tested classes that integrated them together. Pretty neat I think!

What could be changed here? For example, we could have all these classes in a single namespace, like a Quote module. Also, we could use some testing library to use verified mocks (with only real methods with correct arity, i.e., the number of arguments they take).

Whole code can be found in repository on our github including entire history of commits, showing different steps of refactoring.