DEV Community: Rémi Mercier

RSpec fundamentals: setup, naming and basic structure

Rémi Mercier — Tue, 09 Mar 2021 00:00:00 +0000

When you start programming, it’s not easy to know what to test, how to test, and why should you test? You’ve probably heard that TDD (as in Test Driven Development) is THE best practice. But at first, it’s hard to know what your code should do before you’re writing it.

Testing requires practice to reveal its potential.

When I started programming, I’d copy other people’s tests because, well, I had to test, right? But after a while, my tests would uncover edge cases, potential bugs I’d overlooked.

So, I feel a series of short know-hows, know-whats and, know-whys, could be of some use to newcomers; brief essays explaining one aspect of testing with RSpec.

If this sounds fun to you, let’s start with the basics.

What is RSpec?

First, let’s begin with the obvious question: what is RSpec?

RSpec is a testing framework built in Ruby to test Ruby code. It focuses on testing the behavior of your program: what am I feeding my code? What do I expect to come out?

It’s one of several testing frameworks available out there. You might also know Minitest.

Adding RSpec to your application

The RSpec team maintains a gem, making it easy to use the framework in Rails applications.

First, add RSpec to your Gemfile.

  # Gemfile

  gem "rspec-rails", group: [:development, :test]

Install the gem.

  bundle install

Scaffold RSpec’s configuration and switch your application’s testing framework to RSpec.

  rails generate rspec:install

Now, run your migrations and prepare your test database.

  rails db:migrate && rails db:test:prepare

There! Now, you can run your tests by typing rspec spec in your shell. spec is the folder where you’ll create your test files.

Naming your RSpec files

RSpec naming convention is straightforward:

users_controller.rb is tested by users_controller_spec.rb
user.rb is tested by user_spec.rb
user_notification_job.rb is tested by user_notification_job_spec.rb

Architecturing your spec folder

To make sure RSpec and Rails work smoothly together, mimick the structure of your app folder.

  my_app_directory
  |
  |- app
  | |
  | |- models
  | |
  | |- user.rb
  |
  |- spec
     |
     |- models
        |
        |- user_spec.rb

app/models/user.rb is tested by spec/models/user_spec.rb
app/serializers/admin/book_serializer.rb is tested by spec/serializers/admin/book_serializer_spec.rb
and so on.

There’s only one catch:

app/controllers/users_controller.rb is tested by spec/requests/users_controller.rb. The RSpec team discourages you to use spec/controllers. Why? Because testing requests allows you to test the behaviour of your controller’s actions through the stack (routing, request, response, etc…) versus testing the controller in isolation ¹.

So for testing controllers, your folder’s structure is:

  my_app_directory
  |
  |- app
  | |
  | |- controllers
  | |
  | |- users_controller.rb
  |
  |- spec
     |
     |- controllers ❌
     |
     |- requests
        |
        |- users_controller_spec.rb

The structure of your RSpec files

Let’s say we want to test our User model. Our file’s structure would look like this:

  # spec/models/user_spec.rb

  require 'rails_helper'

  RSpec.describe User do
    # test stuff
  end

There! Your setup is done.

But now, I’d like us to dig into each element so we get a better understanding of what’s going on.

require 'rails_helper' loads the configuration for RSpec. rails_helper.rb is located at the root of the spec folder. RSpec is configured out of the box so no need to worry about it.
RSpec is the core module for all RSpec code. It encapsulates and loads a lot of things on instantiation: configuration, expectations, examples, etc. You can check out the code here.
.describe is a class method defined on the RSpec module. It groups your tests around a common abstraction: a class, a request, etc. In the example above, our abstraction is the User model.

The code below is from the RSpec repository.

  def self.expose_example_group_alias(name)
    return if example_group_aliases.include?(name)

    example_group_aliases << name

    (class << RSpec; self; end). __send__ (:define_method, name) do |*args, &example_group_block|
      group = RSpec::Core::ExampleGroup. __send__ (name, *args, &example_group_block)
      RSpec.world.record(group)
      group
    end

    expose_example_group_alias_globally(name) if exposed_globally?
  end

It’s a bit hard to read because of the metaprogramming bits, but the main idea is that it defines the .describe instance method in the RSpec::Core::ExampleGroup class with the abstraction you’re testing (User) and the tests you wrote as arguments.

User is the class you’re testing. It’s passed as an argument to the .describe method.
do ... end is the block where you’re writing your tests. These will be passed as a second argument to the .describe method (see &example_group_block above).

I hope these explanations will give you a better understanding of how RSpec works. Next time, we’ll write our first tests.

Noticed something? Ping me on Twitter or create an issue on GitHub.

Cheers,

Rémi

Thanks @Benoit for pointing that out! ↩

How to wrap your head around a new codebase

Rémi Mercier — Sat, 13 Jun 2020 18:10:06 +0000

For the last eighteen months, I’ve spent my time trying to understand bits of code I’d never seen before. Eighteen months later, I still don’t know every corner of this reasonably sized codebase (~300_000 lines of code). But what I do know is how to get familiar with new parts of it.

So today, I’ll try and give you some tips about an understated skill: how to wrap your head around a new (part of the) codebase.

What you probably shouldn’t do

Don’t. Be. Stubborn.

That part, I’ve struggled with a lot. Stubbornness impeded the order of magnitude of my output for months.

I would try to understand the code alone and knock my head on my keyboard for hours on end. Man, my ego REALLY got into the way of my learning curve.

I had that same bad habit when learning Ruby. I would get to the point of self-loathing before asking teachers for help.

When I finally got to teach Ruby to new developers, I saw this was a common mistake. So, ask for help early, ask for help fast.

Once I identified that habit and worked on improving it, both my learning curve and my output skyrocketed.

Some things you could do

The end goal for you is to get how things work, faster and more comprehensively, so you can work on improving the codebase.

What you can do on our own

Read the code you need to work with.
If some things aren’t clear, take notes. Things you don’t understand can be very different: Is a whole class unclear? Is it just the syntax? Did a senior developer get overboard with their abstractions?
Try and break down what’s happening: isolate each logical part, how do they interact with each other, and get a sense of the flow.
If you’ve identified some gems or patterns: go and read the relevant documentation.
Of course, you won’t approach a whole new codebase the same way you approach a specific part of it. The granularity of what you want to do changes whether you’re starting a new job or tackling a feature.

If after these steps you still feel unsure about where you should start, take a break. This is the tipping point where you’ll fall into stubborn-mode.

Do you feel you’ve started to pull on a thread but still can’t quite wrap your head around it - “I’m almost there.”? Take a break. This is a tipping point too.

Move on to the next stage.

What you can’t do on your own

Note that depending on your situation, some of these tips cannot be copied and pasted. You’ll sometimes need to adapt.

Go and ask the person responsible for the code. With them, go through the following:
- Explain your research, what you understood, and what’s still unclear.
- Ask for a walkthrough: what’s the main goal underlying that part of the codebase, what are the interactions, why did they code things that way, etc.
- Get a proper set up: do you need to create test accounts with 3rd-party software? Are there any credentials you’ll need to do your work? Should you run any tasks?
- As your understanding grows, dig deeper for edge cases. Don’t shy away from tough questions. Your work is to improve the codebase, not stroke your colleagues’ ego.
- If the person responsible for the code is not here, go to the person who has the highest seniority-mentorship ability ratio. If that one is not available, go to the next person with the second highest ratio.

Some additional steps

Draw things of paper: database interaction, data flow, user flow, etc…
Check the data stored in the database: databases aren’t as clean as they ought to be, so check the kind of values you have there. Look out for nil values in email columns, that kind of thing.

That’s it!

What's your favourite tips for getting familiar with a new codebase?

Rémi

This post was originally published on remimercier.com.

Don't sell yourself short

Rémi Mercier — Thu, 05 Mar 2020 09:09:56 +0000

Imagine yourself back to the interview table. You've just graduated from university. Or you've just done a coding bootcamp. Maybe you're in your first two years as a developer.

You are, what the market calls, a junior developer.

Now, you know there's this strong belief that junior developers are a burden to their employer. It's on everyone's lips. It's on the recruiter's who's sitting in front of you. It's on your lips too.

Nobody knows why. But everybody's droning on about it.

Well, this is bullshit. And you're in for a raw deal.

"The market is tough right now" and other fallacies

When I started looking for my first gig, many developers told me it'd be difficult.

The market is tough right now.

Companies don't hire junior developers like they used to.

Teams want fake juniors: technically skilled, battle-tested, unwilling to properly negotiate their comp package.

At first, I didn't pay attention to these. But after a few weeks of meeting people, I started to have second thoughts. After all:

I'd never had a job title remotely related to coding.
I was super picky about the team I'd joined.
I have polarizing opinions (albeit diplomatically expressed) and, I say "fuck" a lot.

The more interviews I did, the more I felt like a burden to everyone:

We'd be investing a lot of money hiring a junior developer. We wouldn't expect any return on that investment for the next 3 years.

(Note how they just - unsuccessfully - tried to talk me into not asking a raise for the next three freaking years?)

Then, out of all these sentences, one struck me as my escape route:

Since you're a junior developer and have limited skills, we'd give you $some_amount per annum.

This is was my 'aha' moment! 💡

What changed? I realized that companies were only assessing my value out of my technical skills. Employers were overlooking my previous 15-ish years in the workforce and perceived me as a complete tenderfoot - something I couldn't accept.

I decided to push back, own my story, bring attention to my full skill set, and move from the cost centers ("We'd be investing a lot of money hiring a junior developer.") to the profit centers ("Sure, come on work with us and take our money. Please?").

I believe that creating value is much (much) more than increasing revenues or cutting costs. But most companies don't share that point of view.

You really want to be attached to Profit Centers because it will bring you higher wages, more respect, and greater opportunities for everything of value to you. @patio11

Show it or it doesn't exist

Here's a list of my non-tech skills and how they affect my technical work daily.

Writing: I love writing. I love when words chime and rhythm, and take me someplace else. So I try and write code that's expressive, articulated and easy to understand.
Museology: After working in museums for years, I'm officially a nerd when it comes to taxonomy. This has proved handy when searching for the appropriate level of abstraction in code.
Design: Studying and designing stuff throughout my life has been one of my greatest joy. It's taught me how to listen to problems, deconstruct them to first principles, and to find creative yet down-to-earth solutions. I also learned to be less domain-dependent and find inspiration everywhere. ¹
Craftmanship: I worked for four years as a stained-glass master. During that time, I restored stained-glass from the 15th to the 20th century. There I nourished my love of building things, of honing the know-how, of patience and minutiae.
Entrepreneurship: Running a business for years has proved useful when dealing with employers. I can put myself into their shoes and avoid a paradox Calvin (as in Calvin and Hobbes) pointed out:

Even though we're both talking English, we're not speaking the same language.

15-ish career: Finally, working for 15 years has taught me a lot about working with people. And this proves an invaluable asset every day. Try and put a bunch of ego-loaded developers and business developers in the same room for 2 hours and see what happens.

Each of these skills, I talked about during interviews. I defended them and showed what they would bring to the table.

Find your skills

I can already hear you say:

But Remi, I don't have any skills.

Well, let me prove you wrong, friend.

Make time in your schedule (a couple of hours at least). Grab some pen and paper. You're ready?

Now, I want you to list every fucking job you've ever done in your lifetime. Next to each entry, list every task you've done and what you learned from it.

Worked in a pizza parlor? You've probably learned a lot about diplomacy, toxic managers, and being client-facing. So write it.

Got the garbage out for years at your parents' house? This is dedication. Write about it.

Worked on a piece of software instead of getting a CS degree? You value real-world experience over grades. Write about it.

Write everything. First, this will give you a master list of your skills that you can return to. Secondly, when someone tells you you know nothing, it'll remind you that they're wrong (if only Jon Snow had made such a list).

Mine is four pages long, and I add stuff on it once a year. It's always a treat to go back to it. So go and do yours now.

How do you feel about it? Lemme me know on Twitter. Noticed something? Create an issue on GitHub.

Many thanks to the people on dev.to for sharing their perspective on this topic.

Cheers,

Rémi

Some of the design-y stuff I love: medieval stained-glass, frescoes, and architecture, the Bauhaus (hand-in-hand form and function), nature (waves building up, geological folds, forests), Fra Angelico, etc... ↩

Unpopular opinion: Junior devs bring much more value to their employers than the market wants them to believe

Rémi Mercier — Tue, 04 Feb 2020 13:09:45 +0000

I'm currently in the process of writing something about how the market wants us - junior devs - to feel we're a burden to our employers, and how I realized how this is plain wrong (as in "not true", not as in "not moral").

After reviewing the work I had done during my first nine months as a developer, I realized that the value created by my work was paying my own salary by an order of magnitude. I replayed every interview I had and realized how common this fallacy is.

How do you feel about this? What is your experience with it?

Value created == growing_revenues OR cutting_costs

A beginners' introduction to Ruby classes and objects

Rémi Mercier — Mon, 18 Nov 2019 13:17:30 +0000

When you start learning Ruby, you often hear that everything is - or evaluates as - an object. And you're usually like "🤔 Come again"?

So, here's an introduction to objects and classes in Ruby for my fellow Ruby junior developers out there.

What is an object?

An object is a piece - any piece - of data (regardless of the language you're using). That's it.

Some types of data:

'Hey there' is a string.
1 is an integer.
5 is another integer.
👶 is a baby.
[] is an empty array.

Easy right?

Objects and classes 101

Now, to handle objects, Ruby creates a set of abstractions handling common behaviors for the same objects: classes.

Let's dive in:

1 and 5 are different integers, hence different objects.

But 1 and 5 are both integers, so Ruby assign them the same class - the Integer class.

The Integer class holds a specific set of methods every integer can call. Developers can then expect common patterns for different objects described by the same class.

  # For instance, the + method is defined in the Integer class.
  # It instantiates and returns a new integer summing the previous ones.
  1 + 5 # => 6

Let's call the method .class on some objects to check their Ruby class.

  'Hello there'.class      # => String
  [1, 2, 3].class          # => Array
  true.class               # => TrueClass

  # It even works with your own classes
  wood = Struct.new(:species)
  Wood.new('mapple').class # => Wood

Classes as blueprints

Classes act as blueprints: you define which data they need and what they can do with it. Then, you can create as many instances - think of instances as casts shaped from a mold - from the same blueprint.

Let's create a blueprint for babies. Here's what our Baby class needs:

Some data to begin with: a DNA hash should do the trick.
Some basics behaviours and capabilities.

class Baby
  # accessor
  attr_reader :dna, :hair_color

  # constructor
  def initialize(dna)
    @dna = dna
    @hair_color = @dna[:possible_hair_colors].sample
    @hungry = true
    @dirty = false
  end

  # behavior
  def drink_milk
    @hungry = false
  end

  def pee
    @dirty = true
  end

  def is_crying?
    @hungry || @dirty
  end
end

Here, I now have a blueprint for babies. It's pretty limited but here's what it does:

When new babies are conceived, they receive a mix of information - their DNA -, and they're both hungry and clean.
In utero, babies will sample the DNA and "pick" a hair color.
Once they're born, babies can drink milk and not be hungry for a while, or pee themselves and get dirty.
If babies get hungry or dirty, they cry to see their need met.

A baby is an "object" whose information and behaviors are specified by a class. Different babies are different "objects" but they all share the same set of basic capabilities.

Let's recap:

So far, we have objects categorized by classes and, whose common information types and behaviors are defined by methods.

Objects as Object (a.k.a, the mindfuck)

Yes, I know, it seems like I'm in for the tautology of the year. And yet, different objects can have common behaviors too!

Let's take an example with the method inspect which returns a human-readable representation of the object. We'll make a new baby ¹ and print her information in my console.

  baby = Baby.new({possible_hair_colors: ['brownish', 'pale blonde', 'a pinch of redhead']})
  baby.inspect

  "#<Baby:0x00007ff2934b3150 @dirty=false, @hungry=true>"

But how can inspect returns anything at all since it's not defined in my Baby class? If it's not defined in Baby then, where is it?

To find out and pull on the thread, let's get back to our console.

  self.inspect                             # => "main"

  self.class.inspect                       # => "Object"

  Object.public_methods.include? :inspect  # => true

What have I just done? I've inspected the current context - self - in which I am when I open my console. The current context is the main object. And in Ruby, the main object is represented by the class Object. Still with me?

Forget about Ruby and web development for a second. Consider this main object as the mother of all objects. Every object is unique, yet they all share common patterns. For instance, they can be inspected, analyzed, etc. You can inspect integers, trees, strings, and babies all the same. Nothing stops you - if you're mentally and physically able - to submit any object to your scrutiny.

Well, that's the same in Ruby. Any object can be inspected. It's a common behavior shared by all objects. And this behavior is defined in the Object class with the method #inspect as you can see in the third line of the console screen above.

Object is the default root of all Ruby objects. [...] Methods on Object are available to all classes unless explicitly overridden. The Ruby doc

It allows Ruby to define methods at appropriate levels of abstraction.

You can dig deeper and check the full inheritance chain by running Object.ancestors in your console. For those who want the TL;DR, Object inherits from BasicObject and mixes in Kernel's methods (like the p method, we junior developers use everywhere to debug our code).

Let's sum everything we've seen so far:

Objects are pieces of data. Different objects can relate to the same class. Classes receive and handle data in their specific way. All classes inherit from the `Object` class and its methods.

Haven't lost you yet, have I? Good! Then, let's talk about the object that describes all classes: the class object and its Class class.

Still there? 😅

The Class class

When you think about it, classes are nothing more than objects. If 'Hello there' is a string and 1 is an integer, String is a class (i.e. a blueprint). So as an object, Ruby has given it its own class: the Class class.

Class inherits from Object but also defines some pretty common methods. Let's see:

  Class.public_methods.include? :new # => true

Every time you're calling #new on a class you want to instantiate, you're using an instance method of the Class class. Wait, what? If #new is an instance method of Class and if I can call it on my own Baby class too, it means that all classes are instances of the Class class?

That's right my friend!

As an instance method of Class, #new is accessible by all instances of Class like our Baby class.

My Baby class does not have a #new method. And yet, I can create new babies with Baby.new(dna). It's because all classes - String, Integer, Baby, etc - inherit from Class.

Let me show you how it works when you define a class in your code.

Writing :

  class Baby
    # some stuff
  end

  baby = Baby.new

is the same as:

  Baby = Class.new

  baby = Baby.new

So if Baby and Class are both classes, they're both instances of the Class class? Yep. Class.class returns Class. It's recursive.

Let's wrap up before letting you massage away that headache of yours:

Objects are pieces of data. Different objects can relate to the same class. Classes then receive and handle data in their specific way. All classes inherit from the `Object` class and its methods. Classes share common behaviors defined in the `Class` class.

I hope you enjoyed the ride as much as I did!

Keep in mind that this is only an introduction. There are many broad strokes and many (more or less voluntary) omissions on my part. If you enjoyed the topic, dig deeper and report back!

Many thanks to Nicolas and Sylvain for reading my drafts, asking a lot of questions, and making this introduction to objects and classes (much much) better.

Noticed something? Lemme know in the comments or create an issue on GitHub.

Cheers,

Rémi

A beginners' introduction to Ruby classes and objects was initially published on my blog.

My upcoming post "How to make babies in 30 seconds thanks to Ruby", soon in your RSS feed. ↩

How does Ruby method lookup work? 🤔

Rémi Mercier — Fri, 15 Nov 2019 09:44:48 +0000

Salut people!

I'm in the process of writing a beginners' introduction to Ruby classes and objects (18th Nov update: it's live!).

While talking with a friend about how classes inherit from their ancestors and the parent Class class, we realized we didn't know how exactly the method lookup works in Ruby.

My first (and wild) guess was: Ruby uses the method(:some_method).owner then check the ancestors' chain. But can't really wrap my head around this.

Anyone around here would like to have a go? 🙏

The violence within

Rémi Mercier — Sun, 13 Oct 2019 14:16:07 +0000

For the past 15 years, I've had multiple encounters with the systemic violence baked in our mainstream work culture: bullying, constant competition, harassment, mocking, productivism, racism, sexism, sticks and carrots, etc. You name it.

I've spent hours talking about these heart-breaking situations with friends, lawyers, psychologists, and work inspectors. All have been witnessing a shitstorm that is destroying people from all horizons.

All companies indulge in it: big corporations, public services, NGOs, etc. It's everywhere, even (especially!) in those over-hyped companies called startups.

Look around you for a moment. One out of three women is sexually harassed in the workplace ¹. One out of two men is bullied by a supervisor ². The person you're looking at right now is likely molested as we speak.

I don't know if you've been there (yet), but I have. And I refuse to feel guilty about it. I refuse to wear those traumas as a shame mark.

I fell prey to the lies our work culture tells us. And our work culture has seared its own culture of silence into our collective conscience. For a long time, I felt isolated. But no more.

Only sitting in a circle of women, listening to similar stories, allowed her to realize that she wasn't alone, it wasn't her fault, she could speak up. Gloria Steinem, My Life On The Road

No matter the gender you're relating to, sitting and sharing similar stories with others can be the first step to saying "No!" to this violence. This is why I want people to speak up and talk to each other. This is why I talk about it so that people will take courage from it.

Silence is playing our violent working culture's game. Silence is accepting your disappearance, literally and symbolically. Silence is dying.

Talking is bonding with others. Talking is organizing and exploring new paths. Talking is living.

You're not alone. Help and kindness are sometimes found when most needed. Find your circle, listen, and maybe, talk.

Rémi

Want to talk? My DMs are open. Noticed something? Create an issue on GitHub.

Originally published on my blog 👉 remimercier.com.

Official studies assume that most harassments are not reported for fear of retributions. For official data (in French): https://www.egalite-femmes-hommes.gouv.fr/dossiers/egalite-professionnelle/lutte-contre-le-harcelement-sexuel-au-travail/les-chiffres-cles-du-harcelement-sexuel-au-travail/ ↩
See Canada's official data: https://www150.statcan.gc.ca/n1/pub/75-006-x/2018001/article/54982-eng.htm ↩

Testing railway-oriented business transactions with Rspec

Rémi Mercier — Fri, 11 Oct 2019 12:05:19 +0000

Railway-oriented business transactions are a great way to unclutter your Rails controllers. We've already seen how to write 'em. Now let's see how we can test 'em. I'll be using dry-transaction as a business transaction DSL and RSpec for testing. I'm assuming that you already have RSpec set up for your app. If not, check Aaron Sumner's blog and his book Everyday Rails Testing With RSpec to saddle up.

Starting point: a basic transaction

Here's a basic transaction. I'll fetch some params and create a new lead. Based on the database response, I'll return either a Success or a Failure.

  # app/transactions/leads/create.rb

  class Leads::Create < BaseTransaction
    map :params
    step :create_lead

    def params(input)
      input.fetch(:params)
    end

    def create_lead(params)
      lead = Lead.create(params)

      if lead.errors.any?
        Failure(error: lead.errors.full_messages.join(' | '))
      else
        Success(lead)
      end
    end
  end

Now, I want to test it. So where do I start?

Testing transactions: the basics

First, I'll create a test file.

  touch app/transactions/leads/create_spec.rb

Then, I'll write our test bare bones.

  # app/transactions/leads/create_spec.rb

  require 'rails_helper'

  RSpec.describe Leads::Create, type: :transaction do
    subject { described_class.call(params: params) }

    let(:params) do
      {
        first_name:        'Steven',
        last_name:         'Universe',
        email:             'steven@crystalgems.com',
        opt_in_newsletter: true
      }
    end
  end

What I'm doing here:

described_class.call(params: params) is calling my transaction with the awaited input (params)
subject is a special variable that refers to my transaction being tested
let(:params) stores the hash I'm sending to my transaction

Covering positive scenarios

What should I test then? The first thing I want to test is the transaction returning a Success when called with valid params. From this starting point, I can check if the transaction does create a Lead or if this lead has the proper attributes filled in.

  require 'rails_helper'

  RSpec.describe Leads::Create, type: :transaction do
    subject { described_class.call(params: params) }

    let(:params) do
      {
        first_name:        'Steven',
        last_name:         'Universe',
        email:             'steven@crystalgems.com',
        phone_number:      '+33660606060',
        opt_in_newsletter: false
      }
    end

    context 'a new lead signed up with valid params' do
      it { is_expected.to be_success }

      it 'creates a new lead' do
        expect { subject }.to(change { Lead.count }.by(1))
      end

      it 'return a new lead' do
        expect(subject.success).to be_a(Lead)
      end

      it 'fills in the ad hoc fields' do
        expect(subject.success).to have_attributes(
          first_name:        a_string_ending_with('n'),
          last_name:         a_string_starting_with('u'),
          email:             be_truthy,
          phone_number:      be_truthy,
          opt_in_newsletter: be_falsey
        )
      end
    end
  end

Here I'm using various RSpec built-in matchers to check several things:

what's happening to my database when the transaction is called (with expect { subject }.to())
if my transaction returns a Success and the content of this Success (with subject.success)
the newly created Lead's attributes

Testing for successes and failures

Say I want to send a SMS to my new lead through an external service. Let's add a step to my transaction.

  class Leads::Create < BaseTransaction
    map :params
    step :create_lead
    step :send_welcome_sms

    def params(input)
      input.fetch(:params)
    end

    def create_lead(params)
      lead = Lead.create(params)

      if lead.errors.any?
        Failure(error: lead.errors.full_messages.join(' | '))
      else
        Success(lead)
      end
    end

    def send_welcome_sms(lead)
      MySmsProvider.welcome_sms(lead)

      Success(lead)
    rescue StandardError => exception
      Failure(error: exception)
    end
  end

Easy right? But MySmsProvider only provides production-ready credentials. So how can I test MySmsProvider's different responses? RSpec allows me to mock responses.

Let's start with mocking a positive response. Our basic assumptions shouldn't change because whatever steps we're adding to the transaction, it should always return a Success or a Failure.

  require 'rails_helper'

  RSpec.describe Leads::Create, type: :transaction do
    subject { described_class.call(params: params) }

    let(:params) do
      {
        first_name:        'Steven',
        last_name:         'Universe',
        email:             'steven@crystalgems.com',
        phone_number:      '+33660606060',
        opt_in_newsletter: false
      }
    end

    context 'a new lead signed up with valid params'
      before do
        response = {
          message_id:     01234,
          body:           'Hello Steven!',
          message_status: 'sent'
        }

        allow_any_instance_of(MySmsProvider).to receive(:deliver_now) { response }
      end

      it { is_expected.to be_success }

      it 'creates a new lead' do
        expect { subject }.to(change { Lead.count }.by(1))
      end

      it 'return a new lead' do
        expect(subject.success).to be_a(Lead)
      end

      it 'fills in the ad hoc fields' do
        expect(subject.success).to have_attributes(
          first_name:        a_string_ending_with('n'),
          last_name:         a_string_starting_with('u'),
          email:             be_truthy,
          phone_number:      be_truthy,
          opt_in_newsletter: be_falsey
        )
      end
    end
  end

But what if we want to test a negative response (i.e: Steven's phone number is invalid)?

I can either add a context block with specific params or mock a error message from MySmsProvider. I'll do the former. context behaves like a sub-folder where I can inherit my test's top-level information yet change it if need be.

  require 'rails_helper'

  RSpec.describe Leads::Create, type: :transaction do
    subject { described_class.call(params: params) }

    let(:params) do
      {
        first_name:        'Steven',
        last_name:         'Universe',
        email:             'steven@crystalgems.com',
        phone_number:      '+33660606060',
        opt_in_newsletter: false
      }
    end

    context 'a new lead signed up with valid params' do
      before do
        response = {
          message_id:     01234,
          body:           'Hello Steven!',
          message_status: 'sent'
        }

        allow_any_instance_of(MySmsProvider).to receive(:welcome_sms) { response }
      end

      it { is_expected.to be_success }

      it 'creates a new lead' do
        expect { subject }.to(change { Lead.count }.by(1))
      end

      it 'return a new lead' do
        expect(subject.success).to be_a(Lead)
      end

      it 'fills in the ad hoc fields' do
        expect(subject.success).to have_attributes(
          first_name:        a_string_ending_with('n'),
          last_name:         a_string_starting_with('u'),
          email:             be_truthy,
          phone_number:      be_truthy,
          opt_in_newsletter: be_falsey
        )
      end
    end

    context 'a new lead signed up with invalid params' do
      # I can redefine my params here to include a nil value that'll trigger an error with my SMS provider
      let(:params) do
      {
        first_name:        'Steven',
        last_name:         'Universe',
        email:             'steven@crystalgems.com',
        phone_number:      nil,
        opt_in_newsletter: false
      }
    end

      it { is_expected.to be_failure }

      it 'returns an error from MySmsProvider' do
        expect(subject.deliver_sms_now).to be_kind_of(MySmsProvider::REST::RestError)
      end
    end
  end

In the last context 'a new lead signed up with invalid params', the before do block defined in the first context does not apply (it's context-dependent). I've decided to trigger an error based on my input rather than mocking an error with allow_any_instance_of. This way, I can decide to enforce validations at the transaction level to return a Failure if some data are missing.

And voilà!

I hope this boilerplate will help you start testing your transactions. Noticed something? Lemme know in the comments or create an issue on GitHub.

Cheers,

Rémi

Testing railway-oriented business transactions with Rspec was originally published on my blog.

How to use transactions to unclutter your Rails controllers

Rémi Mercier — Fri, 13 Sep 2019 11:59:26 +0000

When your Rails app needs to handle multiple steps, your controllers' methods can become a mess.

Don't despair, though. You can delegate sequential steps to business transactions and Marie-Kondo those messy controllers. I'll show you how.

Let's keep in mind that business transactions are different from ActiveRecord transactions. Business transactions allow you to create a series of steps, each resulting in a Success or a Failure object. ActiveRecord transactions are about ensuring that several database operations work as a single unit and are all rollbacked if any error occurs.

In this tutorial, I'll use the dry-transaction gem whose documentation is neat.

From clean to messy controllers in no time

Let's start with coding a basic controller.

  class LeadsController < ApplicationController
    def new
      @lead = Lead.new
    end

    def create
      lead = Lead.create(lead_params)

      if lead.errors.any?
        lead = Lead.new(lead_params)
        render :new
      else
        redirect_to lead_path(lead)
      end
    end

    private

    def lead_params
      params.require(:lead).permit(
        :first_name, :last_name, :email
      )
    end
  end

Okay, so here's a basic LeadsController. You have two actions: new and create. As you can see, the create method is straightforward:

I create a new lead with the information filled by our lead.
I handle any errors by rendering the leads/new form prefilled with the information our current lead already gave us.
If everything goes well, I redirect our lead to her profile page (or any page of my choosing).

But what if I want to do more? Let's say I want to:

connect to a distant CRM through an API and synchronize the lead's information with my sales team
send a welcome text and an email to the lead
notify someone in my team

  class LeadsController < ApplicationController
    def new
      @lead = Lead.new
    end

    def create
      lead = Lead.create(lead_params)

      if lead.errors.any?
        lead = Lead.new(lead_params)
        render :new
      else
        # synchronize new lead to distant CRM
        MyDistantCrm.create_lead(lead)

        # send welcome sms and email to new lead
        MySmsProvider.welcome_sms(lead).deliver_now
        LeadMailer.welcome(lead).deliver_now

        # notify business developer
        BusinessDevelopperMailer.new_lead(lead).deliver_now

        # redirect new leads to their profile page
        redirect_to lead_path(lead)

      # rescue any error to avoid a 500 error
      rescue StandardError => exception
        flash[:error] = exception
      end
    end

    private

    def lead_params
      params.require(:lead).permit(
        :first_name, :last_name, :email
      )
    end
  end

As you can see, there are several new steps doing very different things. In a real-life app, we could do a lot more than that: create associations, generate SKU numbers, etc. The other thing is that all these steps are dependent on the lead being created without any errors. This puts a lot of stuff into an else branch. This is where business transactions can come in handy.

Let's see how to do it.

Transactions to the rescue

Let's set up dry-transaction and see how we can unclutter our controller.

Step 1: Install dry-transaction

Add this line to your application's Gemfile:

  gem 'dry-transaction'

Then execute:

  bundle install

Step 2: General principles

Before we dive into moving parts of our LeadsController#create into a transaction, let's look at a transaction file to see what's what.

A business transaction is a series of operations where any can fail and stop the processing.

Each step is processed one at a time and must return either a Success or a Failure object.

  class Leads::Create < BaseTransaction
    # Here, I define the operation sequence
    tee :params
    step :create_lead

    # Here, I define each operation
    def params(input)
      @params = input.fetch(:params)
    end

    def create_lead(input)
      @lead = Lead.create(@params)

      if @lead.errors.any?
        Failure(error: @lead.errors.full_messages.join(' | '))
      else
        Success(input)
      end
    end
  end

Here are a few points to keep in mind:

tee is a specific kind of step. It'll always return a Success. This is fine here because I'm simply fetching an input.
step is the basic operation. It'll have to return either a Success or a Failure object.
@params will be available to all other steps or methods of my transaction when lead will not.

Step 3: Move the controller's logic into the transaction

Now, we can move parts of our LeadsController#create into a transaction.

My app's architecture was:

  - app
    - controllers
      - application_controller.rb
      - leads_controller.rb

At the end of this tutorial, it'll be:

  - app
    - controllers
      - application_controller.rb
      - leads_controller.rb
    - transactions
      - base_transaction.rb
      - leads
        - create.rb

Let's build base_transaction.rb first.

  class BaseTransaction
    include Dry::Transaction

    def self.call(*args, &block)
      new.call(*args, &block)
    end
  end

def self.call(*args, &block) will allow us to call the transaction from our controllers with a hash of arguments.

I'll start with the transaction we started earlier and I'll move parts of our LeadsController#create into it.

  class Leads::Create < BaseTransaction
    tee :params
    step :create_lead
    step :create_distant_lead
    step :send_welcome_sms
    step :send_welcome_email
    step :notify_business_developper

    def params(input)
      @params = input.fetch(:params)
    end

    def create_lead(input)
      @lead = Lead.create(@params)

      if @lead.errors.any?
        Failure(error: @lead.errors.full_messages.join(' | '))
      else
        Success(input)
      end
    end

    def create_distant_lead(input)
      MyDistantCrm.create_lead(@lead)

      Success(input)
    rescue StandardError => exception
      Failure(error: exception)
    end

    def send_welcome_sms(input)
      MySmsProvider.welcome_sms(@lead).deliver_now

      Success(input)
    rescue StandardError => exception
      Failure(error: exception)
    end

    def send_welcome_email(input)
      LeadMailer.welcome(@lead).deliver_now

      Success(input)
    rescue StandardError => exception
      Failure(error: exception)
    end

    def notify_business_developper(input)
      BusinessDevelopperMailer.new_lead(@lead).deliver_now

      Success(input)
    rescue StandardError => exception
      Failure(error: exception)
    end
  end

All of my LeadsController#create steps are now in my transaction.

Each operation handles its own errors and return a Success or a Failure object.

For instance, if my MySmsProvider.welcome_sms(@lead).deliver_now returns an error, my transaction will not execute the next steps and will return a Failure so I know that something went wrong here.

Step 4: Call the transaction and handle its results

Now that all my steps are in my transaction, what should I do with my controller? We'll start by calling the transaction.

  class LeadsController < ApplicationController
    def new
      @lead = Lead.new
    end

    def create
      Leads::Create.call(params: lead_params)
    end

    private

    def lead_params
      params.require(:lead).permit(
        :first_name, :last_name, :email
      )
    end
  end

Neat right?

Calling a transaction will run its operations in their specified order, with the output of each operation becoming the input for the next.

As I said before, a transaction either returns a Success or a Failure object. I can handle these results in the controller.

In our original controller, I would render the new form if the lead creation failed. On the other hand, if the creation succeeded, I'd redirect my new lead to its profile. Let's do this now!

  class LeadsController < ApplicationController
    def new
      @lead = Lead.new
    end

    def create
      Leads::Create.call(lead_params) do |m|
        m.success do
          redirect_to lead_path(lead)
        end
        m.failure do |failure|
          lead = Lead.new(lead_params)
          render :new
        end
      end
    end

    private

    def lead_params
      params.require(:lead).permit(
        :first_name, :last_name, :email
      )
    end
  end

Now, my controller only handles calls to a grouped set of business operations. No more database operations mingling with sending out emails or redirection rules. There is some cohesiveness in the abstraction.

This is it!

Y'all go and checkout dry-transaction's documentation and do not hesitate to read the source code for more magic!

If you have any questions or if something is not clear enough, ping me on Twitter or create an issue on GitHub so we can make this tutorial better.

Next time, I'll show you how to test your transactions.

Cheers,

Rémi

How to use transactions to unclutter your Rails controllers was originally published on my blog.

What does PHP stand for?

Rémi Mercier — Wed, 03 Jul 2019 15:38:35 +0000

👏 People

👏 Hate

👏 PHP

This had me rolling under the table a while back. 😄

What is an API?

Rémi Mercier — Thu, 23 May 2019 13:08:17 +0000

Feeling queasy about explaining APIs to your grandma 👵 or a non-technical client 👔? Lemme help you out!

Before we start, I’d like to ask you a few questions. Do you know how:

Authentic Weather knows the weather it’ll be doing during your upcoming trip to Dunkirk?
Trainline knows if a seat is available (of that very same upcoming trip to Dunkirk)?
Airbnb puts available flats on a map (do I even need to say “of Dunkirk”)?

These past few years, APIs (also known as Application Programming Interfaces) have spread like wildfire in the startup growth game.

To quote Paul Bonaud, back-end engineer at @trainline_fr (formerly Captain-Train):

APIs, quite an interesting and vast subject, isn’t it?

Wrapping your head around APIs can be challenging for non-technical users. What’s an API? What can be shared through an API? Data? Services? How does one design an API? How do you code an API?

Because I asked myself all of these questions (and many more), I’ve decided that it was time to get a better understanding of what APIs are all about. It’s a bit scary though - especially when you come from a non-technical background - but I’m sure people will find it entertaining. I plan on writing about various topics:

what’s an API?
how does it work?
who’s using it?
etc…

But let’s start from the beginning.

What is an API?

APIs - or Application Programming Interfaces - are defined as a set of functions (a coded procedure performing a particular task) through which two software can talk to each other without any human intermediation. An API is an abstracted point of entry to a piece of software with a description of the open interface and its behavior.

Let’s break that acronym down:

Application: By application, we mean a service with which a developer wants to interact. This service can be a stream of meteorological data, an image sharing app or an open data portal.
Interface: The interface is the entry door to the service. You have to go through that door to interact with the service capabilities (e.g., filtering meteorological data for a city, publishing pictures on Instagram…)
Program: The program is a set of coded procedures written by a developer. The program is designed to interact with the application, so we don’t have to. For example, the program can submit a postal address to get coordinates (think Airbnb or Google Map).

To sum it up: APIs are programs using a specific point of entry (the interface, also call an end-point) to interact with an application (or some features within this application).

Ok, but what does an API do?

Nowadays, APIs are well covered. You’ll find lots of articles about the “Greatest XXX APIs every developer need to know.” But the very basics of APIs are not concisely explained and still elude non-technical users.

An API allows a developer to access a service. One usually says that an API exposes a service.

We’ve seen it above; the service can come in many shapes and forms: real-time data streams (e.g., Twitter), maps (OpenStreetMap), publishing a picture (Instagram).

Developers write programs that consume these APIs.

APIs can be used in various environments:

👉 In a closed environment:

to mutualize your company data across departments’ lines
to expose a database’s serialization made from multiple data sources
to test an API in a secure environment before releasing it publicly

👉 In an open environment:

expose data to the world: think open data portals
allow other companies to offer their services within your application: think Giphy integration in Slack, Zapier…

Let's try a metaphor

Metaphors can be tricky when it comes to technological matters. But the gist of APIs can easily be understood using the electricity network as a proxy.

Let’s start with an electricity supplier:

this supplier produces and distributes a service: electricity
to distribute this service, the supplier relies on infrastructure: the electric network (stations, transmission lines, utility poles, sockets)

Now, let’s take a lamp that needs to consume electricity:

for the lamp to work, it needs to be connected to the electric grid
to be connected, the lamp is sold with a plug that fits standards sockets

The socket is a standardized point of entry (an interface) through which a lamp consumes electricity. An API is a standardized point of entry (an interface) through which a program consumes an application.

APIs allow developers to delegate a service they need to consume. In the same way, the lamp’s owner delegates the electricity needed by her lamp to the electricity supplier.

Let’s dig further. APIs and electrical sockets both specify how the user can consume the service. Remember our lamp? It needs to respect some conditions for using the service:

the number and shape of the pins
voltage and frequency
type of current
etc…

APIs will do the same and specify conditions to use them:

number of API calls for a defined lap of time
what you can expect to do: read and/or write
etc…

Thanks to the standardization of sockets, you can plug several lamps in your home without thinking twice about it. What matters is that every socket is functionally similar: it brings electricity right into your home.

APIs and sockets are abstractions for the service they expose.

Wait, what? Abstractions? 🤔

They hide the nitty-gritty of the service the customer uses.

Without sockets, you’d need to twist your lamp’s wires around those sticking out of your wall. Lamps don’t give a dime about the details of the electrical grid. They work whether the electricity comes from solar panels or wind turbines; whether the cables within the wall are black, red or pink; whether other lamps are plugged into the network or not. As long as the electricity supplier provides the lamp with its functional needs (AC and 110 volts if you live in the US), the supplier can modify its network at will. Without this abstraction, you’d need to wrap your lamp’s wires around the wires in the wall.

The abstraction works the other way round. The electric grid doesn’t care about the design of your lamp. Whether your lamp is designed by Ikea or Wilhelm Wagenfeld, the grid only cares about the plug fitting the socket. Electricity flows from the station to your socket even if no lamps are plugged in it.

APIs work the same way.

Without APIs, Authentic Weather would need to weather.com’s data on a regular basis (or any other meteorological data provider). Thanks to APIs, Authentic Weather doesn’t care about the nitty-gritty of the meteorological data it receives every second. As long as the data stream (accessible through the API) is functionally stable, Authentic Weather is happy (and its users are happy).

The abstraction works the other way round. weather.com’s API doesn’t care about your app’s color scheme. As long as your app consumes the API within the pre-defined conditions, it’s 👌.

Was this helpful? Lemme know in the comments or on Twitter!

Meet your new friend: self

Rémi Mercier — Wed, 20 Mar 2019 20:19:58 +0000

When coding, it's not always easy to know what's what. Why can't I call that method on this array? When in a method, what am I working with exactly? In these cases, self can prove a super-duper friend!

Even if you're a junior developer, you've probably come across self in class methods definition.

class Hello
  def self.from_the_class
    "👋 from the class method."
  end
end

Hello.from_the_class # => "👋 from the class method."

But that usually it.

Now, self can also come in handy when your understanding of what's going on is a bit muddy. Let's code something!

Say I want to recode the .map method.

  # Native method
  p [1, 2, 3].map { |integer| integer * 2 } # => [2, 4, 6]

  # Let's write our own!
  p [1, 2, 3].my_map { |integer| integer * 2 }

First thing I'll do is to start by defining .my_map and have it output something nice.

  def my_map
    "Hello from my_map"
  end

  p [1, 2, 3].my_map { |integer| integer * 2 }

What I expect, when running this code, is to get "Hello from my_map".

  NoMethodError: private method `.my_map` called for [1, 2, 3]:Array
  from (pry):8:in `<main>`

🤔 Duh.

What does it mean by private method? Let's output our current context (i.e. where the hell we are) with self.

  p "Where are in: #{self}"

  def my_map
    "Hello from my_map"
  end

  p [1, 2, 3].my_map { |integer| integer * 2 }

  "Where are in: main"
  NoMethodError: private method `my_map` called for [1, 2, 3]:Array
  from (pry):8:in `<main>`

main means that we currently are in the context of the Object object. Remember when you were told that all things in Ruby are objects? Well, even Object is an object.

Ruby top classes (or objects) are BasicObject > Kernel > Object.

BasicObject is the parent class of all classes in Ruby. Basic methods like ==, !, !=, equal? are defined there. Kernel is a module with basics public/private methods like puts, gets or chomp. Object inherits from BasicObject and mixes in the Kernel module for good measure. All other Ruby objects inherit from Object. This way, Ruby objects get tons of methods, the latter being defined at the appropriate level of abstraction. Some methods from Object include: to_s or nil?. Fancy right?

Ok, but what about that NoMethodError of mine?

Here's my mistake: I've forgotten to write .my_map in a class. So it's been defined in the Object object by default. And yet, I'm trying to call .my_map on an array.

In order to call .my_map on an array, I need to open and define it in the Array class.

class Array
  p "Where are in: #{self}"

  def my_map
    "Hello from my_map"
  end
end

p [1, 2, 3].my_map { |integer| integer * 2 }

  Where are in: Array
  Hello from my_map

👏 It works! Classes in Ruby can be opened and modified. Now that I've defined .my_map inside the Array class, I can call it on arrays. Easy peasy!

A side note: If you feel like it, you can modify the real .map and make it do weird things too.

Alright, now I want to pass the { |integer| integer * 2 } block to .my_map. I know I should loop through the array and yield the block at some point. But since I'm not passing the array as an argument, where am I to call .each on it?

Let's see what self has to say.

class Array
  def my_map
    # Instantiate an empty array to store results
    results = []
    # Output yield to see the current context
    "Where are in: #{self}"
  end
end

p [1, 2, 3].my_map { |integer| integer * 2 }

  "Where are in: [1, 2, 3]"

When we are in .my_map, the default value we're working with is the array .my_map was called upon. I now know I can call .each on self (i.e. [1, 2, 3]).

class Array
  def my_map
    results = []
    # Loop through the array and output yield just to see what's what
    self.each do |i|
      yield
    end
  end
end

p [1, 2, 3].my_map { |integer| integer * 2 }

  NoMethodError: undefined method `*' for nil:NilClass
  from (pry):94:in `block in <class:Array>'

First, I can read from the error message that I'm in the <class:Array>. That's good. Now, what about this NoMethodError: undefined method '*' for nil:NilClass? Well, it simply says that in the NilClass ¹, there are no methods * defined ².

It means that my block { |integer| integer * 2 } can't execute the multiplication because the integer variable inside it is nil. yield can take arguments though. So inside the loop, I'll just pass the current integer - i - to yield.

class Array
  def my_map
    results = []
    # Loop through the array and execute the block
    self.each do |i|
      # Give yield the current integer and store result in array
      results << yield(i)
    end
    # Return final array
    results
  end
end

p [1, 2, 3].my_map { |integer| integer * 2 }

  [2, 4, 6]

Which can be refactored like this:

class Array
  def my_map
    results = []
    # Loop through the array and execute the block
    each { |i| results << yield(i) } # self is implicite so I can remove it
    results
  end
end

p [1, 2, 3].my_map { |integer| integer * 2 }

🥳 Done!

self is also pretty useful to figure out the scopes of your variables. But that'll do for another article.

The key takeaway for today is: Next time you don't know where the fuck you are in your code, call self to the rescue!

Cheers,

Rémi

Yes, nil also has its own class. ↩
Yes, * is a method defined on specific objects 🤪. To check if NilClass has the * method defined, run NilClass.public_methods.include? '*' and NilClass.private_methods.include? '*' in irb. ↩