Forem: Bohdan Pohorilets

[EN] Rails 7 application inside Docker on macOS - part one

Bohdan Pohorilets — Wed, 19 Jan 2022 00:00:00 +0000

Sometimes we want to play with the new version of Ruby/Rails, but in order to do so we need to install dependencies which quite often is not so seamless. So let’s take a look how to use Docker and shell commands in order to quickly start new project with any combination of Ruby/Rails version and keep the macOS itself clean as a baby’s bottom.

TL;DR - Gist

Process step-by-step

The overall process is quite straightforward and consists of seven dependent steps

Create a folder for a project on local drive
Create Gemfile with ruby/rails version within this folder
Create configuration for Docker within this folder
Build a Docker image
Install rails non the new container
Create new rails project from Docker image with files stored on the local drive
Start the server

Now let’s take a look at each step in detail:

Step #1 - Create a folder for a project on local drive

export DOCKER_RAILS_VERSION="7.0.1"
export DOCKER_RUBY_VERSION="3.1.0"
mkdir app
cd app

the folder will be named /app and all new files will be added inside

Step #2 - Create `Gemfile` with ruby/rails version within this folder

echo "ruby '$DOCKER_RUBY_VERSION'
source 'https://rubygems.org'
gem 'rails', '$DOCKER_RAILS_VERSION'" > Gemfile

this step is done only for the convenience - we will use bundler later to install correct version of the rails gem

Step #3 - Create configuration for Docker

First we create folder where configuration files will live

mkdir .devcontainer
cd .devcontainer

next we add Dockerfile that will be used later by Docker Compose to build our image

echo "FROM ruby:$DOCKER_RUBY_VERSION-slim
RUN apt-get update \
 && apt-get install -y make gcc git sqlite3 libsqlite3-dev \
 && rm -rf /var/lib/apt/lists/*" > Dockerfile

we add gcc, git, sqlite3, libsqlite3-dev packages in order to be able to compile gems later

I’m using slim version of the ruby image from Docker, you can read more about the difference between images in Alpine, Slim, Stretch, Buster, Jessie, Bullseye — What are the Differences in Docker Images? by Julie Perilla Garcia

Now let’s take a closer look at different pieces of docker-compose.yml

echo "version: '3.8'
...

this is the Compose file format version, you can find more information about this file and available versions at Docker Docs

...
services:
  web:
...

this is the beginning of our service, it will be named web

...
    build:
      context: .
      dockerfile: Dockerfile
...

this section will tell the Docker Compose to use the Dockerfile withinapp/.devcontainer/ to build an image

...
    volumes:
      - "$(pwd)/..":/web:cached
    working_dir: /web
...

we will mount parent directory app/ to the image as /web and set it as a default directory for work, :cached part is added to improve the performance of bind-mounted directories on macOS

...
    command: sleep infinity
...

this will keep the container running indefinitely

...
    environment:
      - BUNDLE_PATH=vendor/bundle
...

this is done in order to keep installed gems within the/app/vendor/bundle folder and not install them every time we start the container

...
    ports:
      - '3000:3000'" > docker-compose.yml

here we expose port from container 3000 to macOS

Step 4 - Build a Docker image

docker-compose up -d --build

this command will build an image and start the container, -d is for detached mode, --build to build image before starting container

Step 5 - Install rails in the new container

docker-compose exec web bundle

web is the name of the service where bundle command will be executed, by default it will be run in the web/ folder inside container, that is app/ folder on the macOS drive, where we createdGemfile at Step 2

Step 6 - Create new rails project

docker-compose exec web bundle exec rails new . -f

this will create new rails application inside app/ folder and overwrite existing Gemfile

Step 7 - Start the server

docker-compose exec web bundle exec rails s -b 0.0.0.0

you have to start the server at 0.0.0.0 in addition to the port exposing to make things work

Now if you navigate to http://localhost:3000you should see the default rails page

Extra

image: ruby-$DOCKER_RUBY_VERSION-rails-$DOCKER_RAILS_VERSION

this will add a tag to container with information on ruby/rails vrsion

Don’t forget to stop the container with docker-compose down

If Gemfile does not exist in the web/ folder:

stop all containers
delete any built images
restart Docker
start from the Step 1

.ltag__tag__id__31 .follow-action-button{ background-color: #73c7e6 !important; color: #134871 !important; border-color: #73c7e6 !important; }

#docker Follow

Stories about Docker as a technology (containers, CLI, Engine) or company (Docker Hub, Docker Swarm).

[EN] To mock, or not to mock, that is the question

Bohdan Pohorilets — Sun, 01 Dec 2019 00:00:00 +0000

Time: 5-10 min
Level: Beginner/Intermediate

The following checklist is aimed to help you protect yourself from improper usage of mocks and stubs.You may find yourself willing to add/remove items from the list – that is totally OK, just make sure that you stickto your final version.

Mocking has been a controversial practice from the very moment I’ve heard about it for the first time, however mostpeople agree that mocking is a tool and as any other tool it can’t be good or bad, rather it’s developers obligationto pick the right tool for the job and make most of the features it provides.

You’re doing it wrong if:

Mocking things you don’t own – External Service, IO, System, etc.
- if appropriate, add an Adapter as a wrapper around a thing and mock it instead
Mocking thing under test
- you may want to introduce and mock collaborator instead
Mocking trivial things
- you may use an actual thing instead of a mock
Mocking when you should be stubbing
- test for observable behavior instead of methods being called, methods are only an implementation detail
Mocking only a part of a collaborator’s interface
- mock it entirely or do not mock at all
Mocking at wrong level/layer
- for unit tests – mock your nearest neighbor
- for regression safety – mock dependency at the lowest possible level

If you have not violated any of the upper items, and your tests still are brittle or make you cry at night – that may be an indication of a bad design. If that’s the case – it doesn’t matter either you mock or not because the problem exists between the chair and computer.

References

[UA] Предметно-орієнтована архітектура Rails

Bohdan Pohorilets — Wed, 31 Oct 2018 00:00:00 +0000

Дана стаття описує структуру проекту написаного на Rails і в нійвикористані ідеї з вищезазначених статтей. Окрім того приклад містить всобі можливість досить просто використовувати автоматичні додатки дляперевірки якості коду. Головними вимогами до проекту є:

Розділення перегляду (репрезентації) та бізнес-логіки (вашого домену)
Розділення залежностей (gems) і як результат - можливістьвиконувати юніт тести в ізольованому середовищі
Рішення повинно бути простим і зрозумілим (Rails чудовий фреймворкі ми не збираємось з ним боротись)

TLDR - Github repo та commit з усіма змінамизастосованими до нового проекту на Rails

Розділення перегляду та бізнес-логіки

Першим кроком є чітке розділення перегляду та бізнес-логіки в структуріпроекту (та в вашій голові). Для досягнення даного результату мистворимо нову папку representations/ і перемістимо в неї все що нампотрібно для того щоб показати суб’єкти домену. В прикладі ними є:

representations/
- assets/
- controllers/
- decorators/
- public/
- views/
- vendor/
- routes.rb

Я надаю перевагу використанню декораторів замість helper тому тут немає папки helpers/.

Далі нам потрібно побудувати структуру тек для суб’єктів та логіки домену

жодне з цих двох понять не повинно бути присутнім в частині проекту,що відповідає за представлення. Отож давайте створимо нову теку domain/і перемістимов неї моделі та налаштування для бази даних:
- domain/
- contexts/
- database.yml

Назва contexts/ тут є посиланням на шаблон Bounded Context в теоріїПредметно-орієнтованого програмування. Ви можете назвати їх по-іншому і мати будь-яку структурутек всередині.

Тепер нам потрібно налаштувати Rails для роботи з новою структурою тек. Дані налаштуваннязнаходяться всередині файлу config/application.rb і використовують API Rails::Application

 # config/application.rb

 28 paths['app/assets'] = 'representations/assets'
 29 paths['app/views'] = 'representations/views'
 30 paths['config/routes.rb'] = 'representations/routes.rb'
 31 paths['config/database'] = 'domain/database.yml'
 32 paths['public'] = 'representations/public'
 33 paths['public/javascripts'] = 'representations/public/javascripts'
 34 paths['public/stylesheets'] = 'representations/public/stylesheets'
 35 paths['vendor'] = 'representations/vendor'
 36 paths['vendor/assets'] = 'representations/vendor/assets'
 37 # impacts where Rails will look for an ApplicationController and ApplicationRecord
 38 paths['app/controllers'] = 'representations/controllers'
 39 paths['app/models'] = 'domain/contexts'
 40
 41 %W[
 42 #{ File.expand_path( '../representations/concerns', __dir__ ) }
 43 #{ File.expand_path( '../representations/controllers', __dir__ ) }
 44 #{ File.expand_path( '../domain/concerns', __dir__ ) }
 45 #{ File.expand_path( '../domain/contexts', __dir__ ) }
 46 ].each do |path|
 47 config.autoload_paths << path
 48 config.eager_load_paths << path
 49 end

Після цієї зміни Rails буде працювати з новою структурою тек так, ніби оригінальна ніколи не змінювалась -autoloading, eager loading, asset compilation - всі ці процеси будуть повністю функціональні.

На мою особисту думку представлення ApplicationController та ApplicationRecord як Concernпокращує гнучкість коду, тому в даному прикладі вони є Concerns і є додатковий файл config/initializers/draper.rbдля того щоб ‘Draper’ зміг з ними працювати

 # config/initializers/draper.rb

 3 DraperBaseController = Class.new( ActionController::Base )
 4 DraperBaseController.include( ApplicationController )
 5
 6 Draper.configure do |config|
 7 config.default_controller = DraperBaseController
 8 end

Розділення середовищ та побудова незалежних тестів

Раніше ми розділили представлення і предметну область, тепер окремі тести длякожної частини будуть великим плюсом для проекту. Правильного написані тести будутьшвидші, ізольовані та незалежні. Спершу підготуємо середовище для них:

Створимо окремі Gemfile та Gemfile.lock для представлення та предметної області
Налаштовуємо головний Gemfile так щоб він використовував нові специфічні для кожноїобласті Gemfile
Налаштуємо незалежні тестові середовища для представлення та предметної області

Додавання додаткових Gemfile не є чимось складним - ми просто створюємо нові файли і переміщуємов них залежності (gem) з головного.

Налаштувати головний Gemfile для роботи з розподіленими залежностями є також доволі простим - bundlerвже має метод для завантаження додаткових файлів, якщо виникнуть проблеми при завантаженні розподіленихзалежностей ви побачите ті самі помилки що і при завантаженні звичайного Gemfile

 # Gemfile

 54 %w[representations/Gemfile domain/Gemfile].each do |custom_gemfile|
 55 eval_gemfile custom_gemfile
 56 end

Налаштування незалежних тестових середовищ є найскладнішою частиною (і найімовірніше саме тут виникнутьдодаткові проблеми при рості проекту). Перший крок - запустити команду rspec --init в теках representations/та domain/. В результаті нові таки representations/spec та domain/spec будуть додані.

spec/spec_helper.rb також буде додано автоматично, проте spec/rails_helper.rb автоматично створеноне буде і нам доведеться додати і налаштувати його вручну.

Налаштування тестового середовища предметної області

Для початку ми копіюємо файл spec/rails_helper.rb в domain/spec/rails_helper.rb і видаляємо з нього все до лініїRSpec.configure do |config|. Це робиться для того щоб не завантажувати жодних залежностей - ми їх завантажимовручну пізніше. Після цього в нас не буде можливості запустити тести, проте це лише перший крок.

Далі ми завантажуємо всі необхідні залежності:

завантажуємо active_record та rspec-rails

  # domain/spec/rails_helper.rb

  3 require 'active_record/railtie'
  4 require 'active_support'
  5 require 'rspec/rails'

завантажуємо залежності тестового середовища

  7 ENV['RAILS_ENV'] ||= 'test'
  8 require 'spec_helper'
  9 require 'database_cleaner'
 10 require 'factory_bot'
 11 require 'pry-byebug'

створюємо Application для роботи з rspec-rails (нажаль найбільшслабка частина)

 13 ContextsTestApplication = Class.new( ::Rails::Application )
 14 ::Rails.application = ContextsTestApplication.new

під’єднуємось до бази даних

 16 database_configurations = YAML.load(
 17 ERB.new(
 18 File.read( File.expand_path( '../database.yml', __dir__ ) )
 19 ).result
 20 )
 21
 22 ActiveRecord::Base.establish_connection( database_configurations['test'] )
 23

завантажуємо предметну область (спільні concerns в першу чергу оскільки немаємеханізму автозавантаження)

 24 %w[concerns contexts].each do |folder|
 25 Dir[File.expand_path( "../#{folder}/**/*.rb", __dir__ )].each { |f| require f }
 26 end

завантаження файлів initializer/support

 28 Dir['./spec/support/*.rb'].each { |f| require f }
 29
 30 RSpec.configure do |config|

налаштування тестового середовища для представлення

Налаштування тестового середовища для представлення є досить схожим -єдина різниця це залежності якими завантажуємо:

завантажуємо action_controller та rspec-rails

  # representations/spec/rails_helper.rb
  3 require 'action_controller/railtie'
  4 require 'active_support'
  5 require 'rspec/rails'
  6 require 'spec_helper'

створюємо Application для rspec-rails та завантажуємо routes

  8 RepresentationsTestApplication = Class.new( ::Rails::Application )
  9 ::Rails.application = RepresentationsTestApplication.new
 10 require_relative '../routes'

завантажуємо залежності

 12 require 'pry-byebug'
 13 require 'uuid'

завантажуємо код представлення (спільні concerns в першу чергу оскільки немаємеханізму автозавантаження)

 15 %w[concerns controllers decorators].each do |folder|
 16 Dir[File.expand_path( "../#{folder}/**/*.rb", __dir__ )].each { |f| require f }
 17 end

Тепер у нас є змога запускати різні тести в залежності від контексту і для кожного контексту:

тести можуть включати лише юніт-тести
ми змушені залишатися всередині контексту при написанні тесту
завантаження/перезавантаження середовища є швидким (завантаження файлів тривало 2.65 секунди коли тестизапускалося з головного проекту і лише 0.9 секунд якщо запускалась незалежно)

Оскільки файли налаштування тестового середовища знаходяться всередині тек representations/ та domain/,ці тeки не можуть бути всередині app/ - тому що Rails спробує завантажити ці файли в production.

Фінальні частини

Як я вже згадував у попередній статті, я вважаю що тести,що знаходяться в головній теці spec/, test/ не повинні бути юніт-тестамиі завжди тестувати декілька компонентів проекту. Протилежне твердження єістинним для тестів що знаходяться в теках representations/spec/ та domain/specзавжди повинні бути юніт-тестами.

Одна проблема з даним налаштуванням є те що для того щоб запускати тестивсередині ізольованого середовища ви повинні мати окремі Gemfile.lock і це можеспричинити різницю у версіях gem які використовується для тестів що запускаються візоляції і тестів що допускаються як частина глобальної тестової системи. Давайтенапишемо тест який би нам повідомляв якщо така ситуація станеться:

  # spec/sanity/gemfile_spec.rb

  5 RSpec.describe 'Gemfile' do
  6 context 'Domain Gemfile' do
  7 it 'have gems locked at the same version as a global Gemfile' do
  8 global_environment = Bundler::Dsl.evaluate( 'Gemfile', 'Gemfile.lock', {} )
  9 .resolve
 10 .to_hash
 11 local_environment = Bundler::Dsl.evaluate( 'domain/Gemfile', 'domain/Gemfile.lock', {} )
 12 .resolve
 13 .to_hash
 14
 15 diff = local_environment.reject do |gem, specifications|
 16 global_environment[gem].map( &:version ).uniq == specifications.map( &:version ).uniq
 17 end
 18
 19 expect( diff.keys ).to eq( [] )
 20 end
 21 end

Приклад проекту також включає Git hooks які будуть встановленіна ваш проект якщо ви запустите ./bin/setup і будуть автоматично виконані передта після того як ви зробити commit. pre-commit hook запускає rubocop для перевіркивсіх змін які будуть включені в commit, post-commit hook надає вам можливість запускатиrails_best_practices, reek, brakeman і mutant для вашого коду.

Підсумок

Мені дуже подобається гнучкість даної архітектури - при потребі можна заізолювати будь-якучастину коду і ставитись до неї як до незалежного unit. В той же час вона, здебільшого,використовує Rails API - тож ми не боремося з Rails, скоріше це ще один спосіб для організаціїкоду. Мені кортить випробувати дану архітектуру з більш складними та legacy проектами - їїзастосування повинно бути доволі простим в обох випадках.

Посилання:

[EN] Domain Driven Rails Architecture

Bohdan Pohorilets — Fri, 26 Oct 2018 00:00:00 +0000

The following article will describe an architecture of a Rails application that is a combination of ideas from the referenced articles as well as a few additional tools to monitor the quality of the code. Main requirements for the application are:

Separation of view(representation) and business logic(your domain)
Separation of dependencies(gems) and as a result ability to run unit tests in isolation
Solution has to be simple and straightforward (Rails is awesome and we’re not going to fight with it)

TLDR - Github repo and a commit with all thechanges applied to a fresh Rails application

Separation of representation and domain

The first thing to do is to have clear separation of representation and business logic in the folder structure (and in your head). In order to achieve this we will introduce a new folder called representations and put everything we need to represent domain entities there. In the example those were:

representations/
- assets/
- controllers/
- decorators/
- public/
- views/
- vendor/
- routes.rb

I personally prefer using decorators instead of helpers so there is nohelpers/ folder.

Next we will setup a folder structure for your domain entities and logic - none of those two should be a part of a representation layer. In order to do so let’s create a new folder domain/ and move our models and database configuration there:

domain/
- contexts/
- database.yml

The name contexts/ here is a reference to BoundedContext pattern in a DDD theory, you may name it differently and have any folder structure within it.

Now we need to make Rails aware of a change in a folder structure. Th isis done in the config/application.rb usingRails::Application

 # config/application.rb

 28 paths['app/assets'] = 'representations/assets'
 29 paths['app/views'] = 'representations/views'
 30 paths['config/routes.rb'] = 'representations/routes.rb'
 31 paths['config/database'] = 'domain/database.yml'
 32 paths['public'] = 'representations/public'
 33 paths['public/javascripts'] = 'representations/public/javascripts'
 34 paths['public/stylesheets'] = 'representations/public/stylesheets'
 35 paths['vendor'] = 'representations/vendor'
 36 paths['vendor/assets'] = 'representations/vendor/assets'
 37 # impacts where Rails will look for an ApplicationController and ApplicationRecord
 38 paths['app/controllers'] = 'representations/controllers'
 39 paths['app/models'] = 'domain/contexts'
 40
 41 %W[
 42 #{ File.expand_path( '../representations/concerns', __dir__ ) }
 43 #{ File.expand_path( '../representations/controllers', __dir__ ) }
 44 #{ File.expand_path( '../domain/concerns', __dir__ ) }
 45 #{ File.expand_path( '../domain/contexts', __dir__ ) }
 46 ].each do |path|
 47 config.autoload_paths << path
 48 config.eager_load_paths << path
 49 end

After this change Rails will work with new layout as if the original one was never changed - autoloading, eager loading, testing, asset compilation - all are fully functional.

I personally believe that having ApplicationController and ApplicationRecord as Concerns improves flexibility of the code, so in the provided example they are concerns and there is an additional config/initializers/draper.rb file to make Draper work

 # config/initializers/draper.rb

 3 DraperBaseController = Class.new( ActionController::Base )
 4 DraperBaseController.include( ApplicationController )
 5
 6 Draper.configure do |config|
 7 config.default_controller = DraperBaseController
 8 end

Separation of environments and building independent test suites

Since we’ve separated the representation and domain having separate test suite for each would be beneficial - properly implemented those suites would be faster, isolated and independent. Let’s prepare environments for themfirst:

Introduce separate Gemfile and Gemfile.lock for representations and domain
Make main Gemfile use ones we add on the previous step
Setup independent test environments for representations/ and domain/

Adding more Gemfiles is trivial - just create new file and extract dependencies from the main Gemfile.

Make main Gemfile aware of additional dependencies is quite simple too -bundler already has a method to load additional files, bundler will complain if there are any issues as if the Gemfile has never been split.

 # Gemfile

 54 %w[representations/Gemfile domain/Gemfile].each do |custom_gemfile|
 55 eval_gemfile custom_gemfile
 56 end

Setting up context specific test suites is the hardest part (and mostlikely it will introduce more issues as application grows). As a first step we run rspec --init within representations/ and domain/, as a result new representations/spec and doman/spec folders will be created.

spec/spec_helper.rb file will be added automatically too, butspec/rails_helper.rb won’t and we have to add and configure it manually.

Domain test suite configuration

To start with we will copy the spec/rails_helper.rb to thedomain/spec/rails_helper.rb and delete everything before RSpec.configure do |config|.This is done in order to not load any dependencies (we will loadeverything we need later). We won’t be able to run tests at this point, but that’s only a first step

Next we actually make sure we load only things we actually need:

load active_record and rspec-rails

  # domain/spec/rails_helper.rb

  3 require 'active_record/railtie'
  4 require 'active_support'
  5 require 'rspec/rails'

load test suite dependencies

  7 ENV['RAILS_ENV'] ||= 'test'
  8 require 'spec_helper'
  9 require 'database_cleaner'
 10 require 'factory_bot'
 11 require 'pry-byebug'

create an Application for rspec-rails to work (the most fragile piece unfortunately)

 13 ContextsTestApplication = Class.new( ::Rails::Application )
 14 ::Rails.application = ContextsTestApplication.new

connect to a database

 16 database_configurations = YAML.load(
 17 ERB.new(
 18 File.read( File.expand_path( '../database.yml', __dir__ ) )
 19 ).result
 20 )
 21
 22 ActiveRecord::Base.establish_connection( database_configurations['test'] )
 23

load domain (shared concerns first since there is no autoloadingmechanism)

 24 %w[concerns contexts].each do |folder|
 25 Dir[File.expand_path( "../#{folder}/**/*.rb", __dir__ )].each { |f| require f }
 26 end

load initializer/support files

 28 Dir['./spec/support/*.rb'].each { |f| require f }
 29
 30 RSpec.configure do |config|

Representations test suite configuration

Setting up the test suite for representations is quite similar, the only difference is things we load:

load action_controller and rspec-rails

  # representations/spec/rails_helper.rb
  3 require 'action_controller/railtie'
  4 require 'active_support'
  5 require 'rspec/rails'
  6 require 'spec_helper'

create an Application for rspec-rails and load routes

  8 RepresentationsTestApplication = Class.new( ::Rails::Application )
  9 ::Rails.application = RepresentationsTestApplication.new
 10 require_relative '../routes'

load dependencies

 12 require 'pry-byebug'
 13 require 'uuid'

load representation code (shared concerns first since there is no autoloading mechanism)

 15 %w[concerns controllers decorators].each do |folder|
 16 Dir[File.expand_path( "../#{folder}/**/*.rb", __dir__ )].each { |f| require f }
 17 end

Now we have two independent test suites that:

may include only unit tests
force you to stay within your context
load/reload environment fast (files took 2.65 seconds to load if run from main app and only 0.96642 seconds to load if run independently)

Since test suite files are within representations/ and domain/ folders they can’t be within the app/ folder - Rails will try to eager load all files in those folders in production

Final parts

As I’ve mentioned in my previous post, I believe that tests within top level spec/ and test/ folders should not be unit tests and always test multiple components of the application. Opposite applies to tests within repreentations/spec and domain/spec - those always should be unit tests.

One issue with this setup is that in order to be able to execute tests within context-specific environment you have to have separate Gemfile.lock files, which may result in different gem versions used when you run tests in isolation and as a whole suite. Let’s introduce a test to make sure we get a notification if such situation happens.

  # spec/sanity/gemfile_spec.rb

  5 RSpec.describe 'Gemfile' do
  6 context 'Domain Gemfile' do
  7 it 'have gems locked at the same version as a global Gemfile' do
  8 global_environment = Bundler::Dsl.evaluate( 'Gemfile', 'Gemfile.lock', {} )
  9 .resolve
 10 .to_hash
 11 local_environment = Bundler::Dsl.evaluate( 'domain/Gemfile', 'domain/Gemfile.lock', {} )
 12 .resolve
 13 .to_hash
 14
 15 diff = local_environment.reject do |gem, specifications|
 16 global_environment[gem].map( &:version ).uniq == specifications.map( &:version ).uniq
 17 end
 18
 19 expect( diff.keys ).to eq( [] )
 20 end
 21 end

The example application also includes Git hooks that will be installed into your application if you run ./bin/setup and will be automatically executed before and after you commit.

Before hook runs Rubocop against changes staged for commit, after hook allows you to run rails_best_practices, reek, brakeman and mutant against your code

Summary

I like a lot the flexibility that this architecture provides - if needed you can isolate any part of your code and threat it as a standalone unit. At the same time it uses Rails API, so it’s not against it -rather it’s a yet another way to organize your code.I’m eager to try it with more complex and legacy applications -introducing new architecture is quite simple in both cases.

Links:

[UA] Приклад архітектури Модульний Моноліт в Ruby on Rails

Bohdan Pohorilets — Sun, 15 Jul 2018 00:00:00 +0000

Time: 20-30 min
Level: Intermediate/Advanced
Code: GitHub
Reference: The Modular Monolith: Rails Architecture – DanManges

Вищезгадана стаття є однією з найкращих, яку я прочитав у минулому році. Я не погоджуюсь з усіма правилами поданими в ній, проте описані ідеїє надзвичайно цікавими (саме після прочитання її я дізнався, що є обмеження на кількість оплесків, які ви можете дати). Я спробував застосувати їх у моєму проекті що був збудований за класичною архітектурою Rails - перебудувати проект було нелегко, протерезультат був безумовно того вартий. Нижче я опишу важливі частини створення локальних gem та engineв проекті, але для TLDR читачів ось єGithub Repo, в файлі seed.rb знаходяться логін і пароль.

Огляд Gem

Локальний gem дозволяє отримати дані про події з Google Calendar

розділення залежностей

Код в локальному gem має внутрішні залежності, проте повністю незалежнийвід проекту в якому використовується. Раніше всі залежності знаходилисьв Gemfile батьківського проекту проте були переміщені в файл *.gemspecвсередині gem.

 # gems/google_calendar/google_calendar.gemspec

 32 spec.add_dependency 'activemodel'
 33 spec.add_dependency 'google-api-client', '~> 0.11'
 34 spec.add_dependency 'ice_cube'
 35 # Development
 36 spec.add_development_dependency 'pry-byebug'
 37 spec.add_development_dependency 'simplecov'
 38 spec.add_development_dependency 'rake'
 39 spec.add_development_dependency 'rspec'
 40 spec.add_development_dependency 'factory_bot'

і завантажуються в initializer

  # gems/google_calendar/lib/google_calendar.rb
  1 require 'google/apis/calendar_v3'
  2 require 'google/api_client/client_secrets'
  3
  4 require 'google_calendar/version'
  5 require 'google_calendar/connection'
  6 require 'google_calendar/event'

розділення тестів

Всі залежні юніт тести були переміщені з батьківського проекту в папку з локальним gem, їх можна запускати незалежно та ізольовано відбатьківського проекту - перейдіть до папки з gem та запустіть bundle exec rspec spec/. Необхідні налаштування показано нижче:

  # gems/google_calendar/spec/spec_helper.rb
  1 require 'simplecov'
  2 SimpleCov.start
  3
  4 require 'google_calendar'
  5 require 'factory_bot'
  6 require 'factories/event_factories'

Огляд Engine

Engine надає можливість аутентифікації за допомогою authlogic

розділення залежностей

Процес такий же як і для gems, всі залежності перенесено в файл *.gemspec

 # domains/customers/customers.gemspec
 19 s.add_dependency 'authlogic'
 20 s.add_dependency 'best_in_place', '~> 3.0.1'
 21 s.add_dependency 'draper'
 22 s.add_dependency 'google_calendar'
 23 s.add_dependency 'haml'
 24 s.add_dependency 'rails'
 25
 26 s.add_development_dependency 'rspec-rails'
 27 s.add_development_dependency 'factory_bot'
 28 s.add_development_dependency 'shoulda-matchers'
 29 s.add_development_dependency 'pry-byebug'
 30 s.add_development_dependency 'sqlite3'

їх завантаження відбувається в initializer

  # domains/customers/lib/customers.rb
  1 require 'active_model/railtie'
  2 require 'active_record/railtie'
  3 require 'customers/engine'
  4 require 'haml'
  5 require 'best_in_place'
  6 require 'authlogic'

engine використовує локальний gem google_calendar, його потрібно завантажити в Gemfile

  # domains/customers/Gemfile
  1 source 'https://rubygems.org'
  2
  3 gem 'google_calendar', path: '../../gems/google_calendar'

розділення тестів

Всі юніт тести для engine було переміщено в папку з engine, їх можна запустити незалежно від основного проекту - перейдіть в папку з тестамидля engine domains/customers/spec/dummy/ і запустіть bundle exec rspec spec/Налаштування test sute знаходяться в rails_helper.rb

  # domains/customers/spec/dummy/spec/rails_helper.rb
  1 # Configure Rails Environment
  2 ENV['RAILS_ENV'] = 'test'
  3 require File.expand_path("../../config/environment.rb", __FILE__ )
  4 # TOFIX ActiveRecord::Migrator.migrations_paths = [File.expand_path("../../test/dummy/db/migrate", __FILE__ )]
  5 ActiveRecord::Migrator.migrations_paths << File.expand_path('../../db/migrate', __FILE__ )
  6
  7 require 'rspec/rails'
  8 # Add additional requires below this line. Rails is not loaded until this point!
  9 require 'spec_helper'
 10 require 'authlogic'
 11 require 'authlogic/test_case'
 12 require 'factory_bot'
 13 require 'shoulda-matchers'
 14 require 'pry'
 15
 16 FactoryBot.factories.clear
 17 FactoryBot.definition_file_paths = %W(spec/factories)
 18 FactoryBot.reload
 19 Dir[Rails.root.join('spec/support/**/*.rb')].each { |f| require f }
 20
 21 RSpec.configure do |config|
 22 config.include Authlogic::TestCase
 23 config.include FactoryBot::Syntax::Methods
 24 config.include Shoulda::Matchers::ActiveModel, type: :model
 25 config.include Shoulda::Matchers::ActiveRecord, type: :model
 26
 27 config.filter_rails_from_backtrace!
 28 end

розділення migrations

Я вважаю міграції не повинні копіюватись до батьківського проекту, необхідні налаштування знаходяться в initializer

  # domains/customers/lib/customers/engine.rb
  1 module Customers
  2 class Engine < ::Rails::Engine
  3 isolate_namespace Customers
  4
  5 initializer :append_migrations do |app|
  6 # Migrations
  7 config.paths['db/migrate'].expanded.each do |expanded_path|
  8 app.config.paths['db/migrate'] << expanded_path
  9 end
          ...
 12 end
 13 end
 14 end

розділення локалізацій

Файли з локалізацією можна помістити в папку з engine, налаштуванн язнаходяться в файлі initializer

  1 module Customers
  2 class Engine < ::Rails::Engine
  3 isolate_namespace Customers
  4
  5 initializer :append_migrations do |app|
          ...
 10 # Translations
 11 config.i18n.load_path += Dir["#{config.root}/config/locales/**/*.yml"]
 12 end
 13 end
 14 end

Використання аутентифікації в батьківському проекті

Аутентифікація була винесена в concern отож потрібно використати цей concern у controller

  # app/controllers/application_controller.rb
  1 class ApplicationController < ActionController::Base
  2 include Customers::Authorization
  3 end

Тестування Engine/Gem в батьківському проекті

Я вважаю, що тести, розташовані в engine/gem, повинні бути юніт тестами - вониповинні швидко запускатись і використовувати stub замість будь-яких зовнішніх залежностей.Коли потрібно протестувати інтеграцію з іншими engine/gem - використати системні тести.Приклад:

# test/system/login_test.rb
  1 require 'application_system_test_case'
  2 require File.join(Rails.root.to_s, 'test', 'support', 'pages', 'accounts', 'login')
  3
  4 class UsersTest < ApplicationSystemTestCase
  5
  6 def test_login_is_functional
  7 load "#{Rails.root}/db/seeds.rb"
  8 ::Pages::Accounts::Login.new(test: self, url: customers.login_url ).instance_eval do
  9 visit
 10 # Validate content
 11 password_present?
 12 login_present?
 13 submit_present?
 14 # Log in
 15 login.set( Customers::Account.first.email )
 16 password.set( 'Test1234' )
 17 submit.click
 18 assert_text( 'Accounts' )
 19 end
 20 ensure
 21 Customers::Account.all.map(&:destroy!)
 22 end
 23 end

Висновки

Винести gem було досить легко, винести engine було трохи складніше. Переваги модульного моноліту над класичним:

Розділення коду - значно вдосконалений дизайн
Розділення залежностей
Розділення тестів - кожен engine/gem має власні тести, які швидко працюють і можуть запускатись незалежно

Код:

Подумати:

Чи можна використовувати shared layouts?
Що робити коли потрібно мати доступ до однієї таблиці з різних engine?
Чи потрібно Gemfile.lock з engines/gems додавати в Git?

Modular Monolith Example

Bohdan Pohorilets — Sat, 23 Jun 2018 00:00:00 +0000

Time: 20-30 min
Level: Intermediate/Advanced
Code: GitHub
Reference: The Modular Monolith: Rails Architecture – DanManges

Referenced article is among the best I’ve read in the past year. While Idon’t agree with everything stated there, the ideas described aresuper awesome (this is when I found out there is a limit on a number ofclaps you can give in medium). I’ve tried to apply them in my pet projectthat is built with classic Rails structre - while extraction wasn’t easythe result was definitely worth it. Here I’ve extracted a gem and an enginefrom the project into a brand new Rails application and it was painless,moreover this extraction improved the design of the engine. I will coverimportant pieces of the setup below, but for TLDR people here is aGithub Repo, check the seed.rb file for creadentials to use.

Gem Overview

The gem allowes you to fetch event data from a Google Calendar

separation of dependencies

Code in the local gem has it’s own dependencies but does not rely on a main app, these dependencies were moved from the parent app’s Gemfile into a gem’s *.gemspec

 # gems/google_calendar/google_calendar.gemspec

 32 spec.add_dependency 'activemodel'
 33 spec.add_dependency 'google-api-client', '~> 0.11'
 34 spec.add_dependency 'ice_cube'
 35 # Development
 36 spec.add_development_dependency 'pry-byebug'
 37 spec.add_development_dependency 'simplecov'
 38 spec.add_development_dependency 'rake'
 39 spec.add_development_dependency 'rspec'
 40 spec.add_development_dependency 'factory_bot'

and are loaded in initializer

  # gems/google_calendar/lib/google_calendar.rb
  1 require 'google/apis/calendar_v3'
  2 require 'google/api_client/client_secrets'
  3
  4 require 'google_calendar/version'
  5 require 'google_calendar/connection'
  6 require 'google_calendar/event'

separation of tests

All Unit tests for the gem were moved to a gem’s folder, they can be executed independently and in isolation - navigate to a gems folder and run bundle exec rspec spec/. In order to make tests run you will need to do a manual setup in helper file

  # gems/google_calendar/spec/spec_helper.rb
  1 require 'simplecov'
  2 SimpleCov.start
  3
  4 require 'google_calendar'
  5 require 'factory_bot'
  6 require 'factories/event_factories'

Engine Overview

Engine provides authentication using authlogic gem

separation of dependencies

Same pattern as in gems, all dependencies live in engines *.gemspec anddo not pollute parent app’s Gemfile.

 # domains/customers/customers.gemspec
 19 s.add_dependency 'authlogic'
 20 s.add_dependency 'best_in_place', '~> 3.0.1'
 21 s.add_dependency 'draper'
 22 s.add_dependency 'google_calendar'
 23 s.add_dependency 'haml'
 24 s.add_dependency 'rails'
 25
 26 s.add_development_dependency 'rspec-rails'
 27 s.add_development_dependency 'factory_bot'
 28 s.add_development_dependency 'shoulda-matchers'
 29 s.add_development_dependency 'pry-byebug'
 30 s.add_development_dependency 'sqlite3'

and are loaded in the initializer

  # domains/customers/lib/customers.rb
  1 require 'active_model/railtie'
  2 require 'active_record/railtie'
  3 require 'customers/engine'
  4 require 'haml'
  5 require 'best_in_place'
  6 require 'authlogic'

engine also depends on a local google_calendar gem, it is loaded directly in the Gemfile

  # domains/customers/Gemfile
  1 source 'https://rubygems.org'
  2
  3 gem 'google_calendar', path: '../../gems/google_calendar'

separation of tests

All Unit tests for the engine were moved to a engine’s folder, they can be executed independently and in isolation - navigate to a engine’s dummy application folder domains/customers/spec/dummy/ and run bundle exec rspec spec/In order to make tests run you will need to do manual setup of the environment in the helper file

  # domains/customers/spec/dummy/spec/rails_helper.rb
  1 # Configure Rails Environment
  2 ENV['RAILS_ENV'] = 'test'
  3 require File.expand_path("../../config/environment.rb", __FILE__ )
  4 # TOFIX ActiveRecord::Migrator.migrations_paths = [File.expand_path("../../test/dummy/db/migrate", __FILE__ )]
  5 ActiveRecord::Migrator.migrations_paths << File.expand_path('../../db/migrate', __FILE__ )
  6
  7 require 'rspec/rails'
  8 # Add additional requires below this line. Rails is not loaded until this point!
  9 require 'spec_helper'
 10 require 'authlogic'
 11 require 'authlogic/test_case'
 12 require 'factory_bot'
 13 require 'shoulda-matchers'
 14 require 'pry'
 15
 16 FactoryBot.factories.clear
 17 FactoryBot.definition_file_paths = %W(spec/factories)
 18 FactoryBot.reload
 19 Dir[Rails.root.join('spec/support/**/*.rb')].each { |f| require f }
 20
 21 RSpec.configure do |config|
 22 config.include Authlogic::TestCase
 23 config.include FactoryBot::Syntax::Methods
 24 config.include Shoulda::Matchers::ActiveModel, type: :model
 25 config.include Shoulda::Matchers::ActiveRecord, type: :model
 26
 27 config.filter_rails_from_backtrace!
 28 end

separation of migrations

I believe migration files should not be copied to a parent application, required configuration is specified in engines initializer

  # domains/customers/lib/customers/engine.rb
  1 module Customers
  2 class Engine < ::Rails::Engine
  3 isolate_namespace Customers
  4
  5 initializer :append_migrations do |app|
  6 # Migrations
  7 config.paths['db/migrate'].expanded.each do |expanded_path|
  8 app.config.paths['db/migrate'] << expanded_path
  9 end
          ...
 12 end
 13 end
 14 end

separation of translations

Translations for views from an engine also live in an engine, configuration is specified in engines initializer

  1 module Customers
  2 class Engine < ::Rails::Engine
  3 isolate_namespace Customers
  4
  5 initializer :append_migrations do |app|
          ...
 10 # Translations
 11 config.i18n.load_path += Dir["#{config.root}/config/locales/**/*.yml"]
 12 end
 13 end
 14 end

Enabling authentication in the main application

Authentication was extracted to be a controllers concern so you need to add this concern to a controller

  # app/controllers/application_controller.rb
  1 class ApplicationController < ActionController::Base
  2 include Customers::Authorization
  3 end

Testing Engine/Gem Integration into a main application

I believe that tests located in engines/gems should be unit tests - they should run fast and stub any external dependencies. It doesn’t make sense to me to test integration outside of the main applications - System Tests are great tool to do this job. A basic example

# test/system/login_test.rb
  1 require 'application_system_test_case'
  2 require File.join(Rails.root.to_s, 'test', 'support', 'pages', 'accounts', 'login')
  3
  4 class UsersTest < ApplicationSystemTestCase
  5
  6 def test_login_is_functional
  7 load "#{Rails.root}/db/seeds.rb"
  8 ::Pages::Accounts::Login.new(test: self, url: customers.login_url ).instance_eval do
  9 visit
 10 # Validate content
 11 password_present?
 12 login_present?
 13 submit_present?
 14 # Log in
 15 login.set( Customers::Account.first.email )
 16 password.set( 'Test1234' )
 17 submit.click
 18 assert_text( 'Accounts' )
 19 end
 20 ensure
 21 Customers::Account.all.map(&:destroy!)
 22 end
 23 end

Summary

Extracting a gem was quite easy, extracting an engine was a bit of work. Advantages of the Modular Monolith over the classic app:

Separation of code - dramatically improved application design
Separation of dependencies - keeps main application cleaner
Separation of tests - each unit has it’s own suite that is fast and can be run independently

Code:

Repository

Food for thought

How to handle shared layouts?
How to handle database tables shared between engines?
Should Gemfile.lock from engines/gems exist in the Git repository?

[UA] Service Objects Глибиною В Два Рівні

Bohdan Pohorilets — Mon, 23 Apr 2018 00:00:00 +0000

Час: 20-30 min
Рівень: Beginner/Intermediate
Код: GitHub

Перед тим як почати писати дану статтю я спробував знайти інших людейякі намагались розглянути код в даному ракурсі - знайшов наступний пост How deep is your code?

Мені потрібен був приклад складного Service Object ія знайшов його в репозиторії Discourse файл. Я в жодному разіне критикую даний код, більше того в тому ж самому репозиторії я знайшов чудовий прикладтого що я намагаюсь описати файл

Особисто я надаю перевагу маленьким класам, коротким, single purpose методам,а не одному великому шматку коду. Проте мушу визнати що даний підхідмає значний недолік - досить часто методи короткі лише тому що вони викликають інші методи, які викликають інші методи,які викликають інші методи… Отож, перш ніж я зможу побачити що насправді відбувається,мені доводиться переглядати купу методів і досить часто я вже не пам’ятаю з чого починав, колинарешті знайду те що шукав.

Я не хочу цим займатись, я не хочу переглядати 5-10 приватних методів щобмати уявлення якими будуть наслідки виклику одного публічного методу.я хочу щоб метод одразу, з першого погляду давав зрозуміти що саме відбувається,можливо є спосіб цього досягнути?

Одного разу я бачив метод оцінки складності коду, який описала Sandi Metz в своєму виступі All the Little Things - the Squint Test.Не зважаючи на те, що даний метод був застосований для оцінки вкладених conditionals, миможемо розглянути виклик методів у схожому контексті. Якщо метод викликає інший методдавайте ми зробимо відступ зліва, так ніби ми маємо вкладений if:

def parent
  child_level_two
  # some code
end

def child_level_two
  # some code
  child_level_three
end

def child_level_three
  # some code
  child_level_four
  # some code
end

тепер давайте запишемо всі задіяні методи і зробимо відступи для кожного вкладеного виклику

def parent
  child_level_two
    child_level_three
  child_level_two
    child_level_three
    child_level_three
  child_level_two
  child_level_two
    child_level_three
    child_level_three
      child_level_four
  child_level_two
  child_level_two
    child_level_three
      child_level_four
      child_level_four
end

ми отримали схожу фігуру, що більші нерівною є права її частина - тобільше вкладених викликів ми маємо.

КРОК #1

Зміни в коді можна подивитись тут

Service Object перед refactoring, я виніс зовнішні залежності в dependencies.rb і додав placeholders для задіяних методів

# user_updater.rb
require 'active_support'
require 'active_support/core_ext/object/blank'
require 'active_support/core_ext/time/calculations'
require 'active_model'

require_relative 'dependencies'

class UserUpdater
  delegate :change_post_owner, to: :guardian

  def update(attributes = {})
    save_options = false
    saved = nil
    old_user_name = user.name.present? ? user.name : ""

    user_profile = user.user_profile
    user_profile.location = attributes.fetch(:location) { user_profile.location }
    user_profile.dismissed_banner_key = attributes[:dismissed_banner_key] if attributes[:dismissed_banner_key].present?
    user_profile.website = format_url(attributes.fetch(:website) { user_profile.website })
    user_profile.profile_background = attributes.fetch(:profile_background) { user_profile.profile_background }
    user_profile.card_background = attributes.fetch(:card_background) { user_profile.card_background }
    if SiteSetting.enable_sso && !SiteSetting.sso_overrides_bio
      user_profile.bio_raw = attributes.fetch(:bio_raw) { user_profile.bio_raw }
    end

    user.name = attributes.fetch(:name) { user.name }
    user.locale = attributes.fetch(:locale) { user.locale }
    user.date_of_birth = attributes.fetch(:date_of_birth) { user.date_of_birth }
    if can_grant_title?(user)
      user.title = attributes.fetch(:title) { user.title }
    end

    # special handling for theme_key cause we need to bump a sequence number
    if attributes.key?(:theme_key) && user.user_option.theme_key != attributes[:theme_key]
      user.user_option.theme_key_seq += 1
    end

    OPTION_ATTR.each do |attribute|
      if attributes.key?(attribute)
        save_options = true

        if [true, false].include?(user.user_option.send(attribute))
          val = attributes[attribute].to_s == 'true'
          user.user_option.send("#{attribute}=", val)
        else
          user.user_option.send("#{attribute}=", attributes[attribute])
        end
      end
    end

    # automatically disable digests when mailing_list_mode is enabled
    user.user_option.email_digests = false if user.user_option.mailing_list_mode

    fields = attributes[:custom_fields]
    if fields.present?
      user.custom_fields = user.custom_fields.merge(fields)
    end

    User.transaction do
      if user.user_option.save && user_profile.save && user.save
        StaffActionLogger.new(@actor).log_name_change(
          user.id,
          old_user_name,
          attributes.fetch(:name) { '' }
        )

        saved = true
      end
    end

    saved
  end

  private

  attr_reader :user, :guardian

  def initialize(actor, user, guardian = Guardian.new(actor))
    @user = user
    @guardian = guardian
    @actor = actor
  end

  def format_url(website)
    return nil if website.blank?
    website =~ /^http/ ? website : "http://#{website}"
  end
end

КРОК #2

Даний крок поділено на кілька невеликих частин:

#2.1 Refactor UserUpdater#update метод (commit)
#2.2 Refactor методи що були додані в 2.1
- #2.2.1 Refactor UserUpdater#update_user_profile метод (commit)
- #2.2.2 Refactor UserUpdater#update_user метод (commit)
- #2.2.3 Refactor UserUpdater#update_user_option метод (commit)
- #2.2.4 Refactor UserUpdater#save_user_data метод (commit)

Я пропущу деталі, тому що зміни є досить прості і звичні для refactoring, вони були зроблені щоб спроститиUserUpdater#update метод, зробити його коротким і простим для розуміння.

# user_updater.rb
class UserUpdater
  delegate :change_post_owner, to: :guardian

  def update(attributes = {})
    old_user_name = user.name.present? ? user.name : ""

    update_user_profile( user.user_profile, attributes )
    update_user( user, attributes )
    update_user_option( user.user_option, attributes )
    save_user_data(user, old_user_name, attributes)
  end

  private
  # ...

Проте я вважаю, що тепер надто багато інформації прихованоЯкщо подивитись на тіло методу ми більше не бачимо що:

В методі використовується транзакція
Деякі частини змінюються лише за виконання певних умов
Ми покладаємось на константу, коли визначаємо які дані змінити
Не очевидно що ми повертаємо (і використовуємо значення) true/false в залежності від результату транзакції

In addition to hiding information, I storngly dislike how newОкрім прихованої інформації, мені надзвичайно не подобається як виглядаєUserUpdater#update_user_profile - це приватний метод, якийскладається лише викликів інших приватних методів і приховує існуючі conditionals.

# user_updater.rb
def update_user_profile( user_profile, attributes )
  update_geo_data( user_profile, attributes )
  update_web_data( user_profile, attributes )
  update_background_data( user_profile, attributes )
  update_bio_raw( user_profile, attributes )
end

Я вважаю що схожі методи лише підвищують складність кодуі не мають права існувати.

КРОК #3

Зміни в коді можна подивитись тут

На цьому кроці ми позбудемось приватних методів, що були (майже) лишеобгортками навколо інших приватних методів і трохи змінимо назви методів, що залишились,щоб краще відобразити їх мету

# user_updater.rb
class UserUpdater
  delegate :change_post_owner, to: :guardian
  delegate :log_user_name_change, to: :StaffActionLogger

  def update(attributes = {})
    old_user_name = user.name.present? ? user.name : ""
    user_profile = user.user_profile
    user_option = user.user_option

    set_user_profile_geo_data( user_profile, attributes )
    set_user_profile_web_data( user_profile, attributes )
    set_user_profile_background_data( user_profile, attributes )
    set_user_profile_bio_raw( user_profile, attributes )

    set_user_bio(user, attributes, update_title: can_grant_title?(user) )
    user.custom_fields = user.custom_fields.merge( attributes.fetch( :custom_fields, {} ) )

    set_user_option_theme_key(user_option, attributes)
    OPTION_ATTR.each { |attribute| set_user_option_single_attribute(user_option, attributes, attribute) }
    # automatically disable digests when mailing_list_mode is enabled
    user_option.email_digests = false if user_option.mailing_list_mode

    return false unless User.transaction { user.user_option.save && user.user_profile.save && user.save }
    log_user_name_change( user.id, old_user_name, attributes.fetch(:name) { '' } )

    return true
  end

UserUpdater#update метод став майже втричі більшим в порівнянні зпопередньою версією, проте тепер він значно краще розповідає свою історію.

Він не ідеальний (і ніколи таким не буде), проте ми зробимо ще один крок для його покращення і знову порівняємо з версією з Кроку #2

КРОК #4

Зміни в коді можна подивитись тут

На даному кроці ми ще трохи відшліфуємо наш код і порівняємо остаточні результати

# user_updater.rb

# Short version
class UserUpdater
  # ...
  def update(attributes = {})
    old_user_name = user.name.present? ? user.name : ""

    update_user_profile( user.user_profile, attributes )
    update_user( user, attributes )
    update_user_option( user.user_option, attributes )
    save_user_data(user, old_user_name, attributes)
  end
# Two levels deep version
class UserUpdater
  # ...
  def update(attributes = {})
    @attributes = attributes
    old_user_name = user.name.present? ? user.name : ""

    set_user_profile_geo_data
    set_user_profile_web_data
    set_user_profile_background_data
    set_user_profile_bio_raw if should_update_user_profile_bio_raw?

    set_user_bio( update_title: can_grant_title?(user) )
    user.custom_fields = user.custom_fields.merge( attributes.fetch( :custom_fields, {} ) )

    set_user_option_theme_key if should_update_user_option_theme_key?
    OPTION_ATTR.each do |attribute|
      set_user_option_single_attribute( attribute )
    end
    # automatically disable digests when mailing_list_mode is enabled
    user_option.email_digests = false if user_option.mailing_list_mode

    return false unless User.transaction { save_user_and_related_entities }
    log_user_name_change( user.id, old_user_name, attributes.fetch(:name) { '' } )

    return true
  end

Я вважаю що довша версія має наступні переваги:

Код розповідає чудову історію з великою кількістю деталей виконання
Код слідує принципу Open/Closed
Ви завжди щонайбільше за один крок від повного визначення будь-якого приватного методу

ПІДСУМОК

Для того щоб мати глибину рівну 2 код повинен задовольняти наступні критерії:

Публічні методи не можуть викликати інші публічні методи того ж класу
Приватні/Захищені методи не можуть викликати інші приватні/захищені методи

У мене є ще два не обов’ язкових правила

Уникати conditionals в приватних методах
Conditionals повинні використовувати приватні методи а не boolean expressions

Код:

ДЛЯ РОЗДУМІВ

Дані правила досить просто виконати при написанні Service Objects, тому що вони зазвичайописуюють певний процес/алгоритм - де ще можна застосувати їх?
Як щодо delegated та accessor methods, чи можна їх вважати приватними при застосуванні метрики?

Two Levels Deep Service Objects

Bohdan Pohorilets — Fri, 20 Apr 2018 00:00:00 +0000

Time: 20-30 min
Level: Beginner/Intermediate
Code: GitHub

Before I started writing this post I searched for other people looking at code code from this perspective - found one How deep is your code?

I needed an example of complicated Service Object and found it in one of the Discourse source files. I’m not criticizing this code by any mean and there is a great example of what I’m going to try to achieve in the same repository

I personally prefer small classes, short, single purpose methods over the one big piece of code. Having said that I have to admit that this approach has a significant downside - methods are short quite often because internally they call other methods, which call other methods, which call other methods… So you have to go down the rabbit hole before you figure out what method actually does, sometimes you loose the big picture in the meantime.

I don’t want to do this, I don’t want to look at 5-10 private methods to figure out what are the implications of calling a public method, I want public method to be able to tell me the story right away, the very first time I see it - maybe there is a way?

Once I saw a complexity metric described by Sandi Metz in her talk All the Little Things - the Squint Test.While this metric was used to measure the complexity of the nested conditionals, we could think about calling methods in a similar way. If a method calls other method let’s indent it as if it was a nested if:

def parent
  child_level_two
  # some code
end

def child_level_two
  # some code
  child_level_three
end

def child_level_three
  # some code
  child_level_four
  # some code
end

now let’s write down all involved methods and indent each nested call

def parent
  child_level_two
    child_level_three
  child_level_two
    child_level_three
    child_level_three
  child_level_two
  child_level_two
    child_level_three
    child_level_three
      child_level_four
  child_level_two
  child_level_two
    child_level_three
      child_level_four
      child_level_four
end

we got similar figure with changes in shape, the bigger is the shape change - the more nesting we have.

STEP #1

Code changes in this step can be found in the corresponding commit

Service object before refactoring, I’ve extracted external dependencies into dependencies.rb and added placeholders for required methods

# user_updater.rb
require 'active_support'
require 'active_support/core_ext/object/blank'
require 'active_support/core_ext/time/calculations'
require 'active_model'

require_relative 'dependencies'

class UserUpdater
  delegate :change_post_owner, to: :guardian

  def update(attributes = {})
    save_options = false
    saved = nil
    old_user_name = user.name.present? ? user.name : ""

    user_profile = user.user_profile
    user_profile.location = attributes.fetch(:location) { user_profile.location }
    user_profile.dismissed_banner_key = attributes[:dismissed_banner_key] if attributes[:dismissed_banner_key].present?
    user_profile.website = format_url(attributes.fetch(:website) { user_profile.website })
    user_profile.profile_background = attributes.fetch(:profile_background) { user_profile.profile_background }
    user_profile.card_background = attributes.fetch(:card_background) { user_profile.card_background }
    if SiteSetting.enable_sso && !SiteSetting.sso_overrides_bio
      user_profile.bio_raw = attributes.fetch(:bio_raw) { user_profile.bio_raw }
    end

    user.name = attributes.fetch(:name) { user.name }
    user.locale = attributes.fetch(:locale) { user.locale }
    user.date_of_birth = attributes.fetch(:date_of_birth) { user.date_of_birth }
    if can_grant_title?(user)
      user.title = attributes.fetch(:title) { user.title }
    end

    # special handling for theme_key cause we need to bump a sequence number
    if attributes.key?(:theme_key) && user.user_option.theme_key != attributes[:theme_key]
      user.user_option.theme_key_seq += 1
    end

    OPTION_ATTR.each do |attribute|
      if attributes.key?(attribute)
        save_options = true

        if [true, false].include?(user.user_option.send(attribute))
          val = attributes[attribute].to_s == 'true'
          user.user_option.send("#{attribute}=", val)
        else
          user.user_option.send("#{attribute}=", attributes[attribute])
        end
      end
    end

    # automatically disable digests when mailing_list_mode is enabled
    user.user_option.email_digests = false if user.user_option.mailing_list_mode

    fields = attributes[:custom_fields]
    if fields.present?
      user.custom_fields = user.custom_fields.merge(fields)
    end

    User.transaction do
      if user.user_option.save && user_profile.save && user.save
        StaffActionLogger.new(@actor).log_name_change(
          user.id,
          old_user_name,
          attributes.fetch(:name) { '' }
        )

        saved = true
      end
    end

    saved
  end

  private

  attr_reader :user, :guardian

  def initialize(actor, user, guardian = Guardian.new(actor))
    @user = user
    @guardian = guardian
    @actor = actor
  end

  def format_url(website)
    return nil if website.blank?
    website =~ /^http/ ? website : "http://#{website}"
  end
end

STEP #2

This step was divided into few smaller chunks:

#2.1 Refactor UserUpdater#update method (commit)
#2.2 Refactor methods that were extracted in 2.1
- #2.2.1 Refactor UserUpdater#update_user_profile method (commit)
- #2.2.2 Refactor UserUpdater#update_user method (commit)
- #2.2.3 Refactor UserUpdater#update_user_option method (commit)
- #2.2.4 Refactor UserUpdater#save_user_data method (commit)

I’ll skip details here because those are quite straight forward extractions, they were done to simplify UserUpdater#update method, make it small and easy to understand.

# user_updater.rb
class UserUpdater
  delegate :change_post_owner, to: :guardian

  def update(attributes = {})
    old_user_name = user.name.present? ? user.name : ""

    update_user_profile( user.user_profile, attributes )
    update_user( user, attributes )
    update_user_option( user.user_option, attributes )
    save_user_data(user, old_user_name, attributes)
  end

  private
  # ...

However I believe that too much information was hidden with this extraction. From the method definition we no longer see that:

There is a transaction
Some parts are updated only if particular conditions are met
We use constant to determine what to update
It’s not obvious that we return (and depend on the returned value somewhere) true/false depending on the result of the transaction

In addition to hiding information, I strongly dislike how new UserUpdater#update_user_profile method looks - it’s a private method that consists of only other private methods, and once again - no conditionals inside

# user_updater.rb
def update_user_profile( user_profile, attributes )
  update_geo_data( user_profile, attributes )
  update_web_data( user_profile, attributes )
  update_background_data( user_profile, attributes )
  update_bio_raw( user_profile, attributes )
end

I believe that methods like this only introduce additional level of complexity and have no right to exist

STEP #3

Code changes in this step can be found in the corresponding commit

In this step we drop private methods that were (almost) only wrappers around other private methods and change remaining method names to reflect the intention better

# user_updater.rb
class UserUpdater
  delegate :change_post_owner, to: :guardian
  delegate :log_user_name_change, to: :StaffActionLogger

  def update(attributes = {})
    old_user_name = user.name.present? ? user.name : ""
    user_profile = user.user_profile
    user_option = user.user_option

    set_user_profile_geo_data( user_profile, attributes )
    set_user_profile_web_data( user_profile, attributes )
    set_user_profile_background_data( user_profile, attributes )
    set_user_profile_bio_raw( user_profile, attributes )

    set_user_bio(user, attributes, update_title: can_grant_title?(user) )
    user.custom_fields = user.custom_fields.merge( attributes.fetch( :custom_fields, {} ) )

    set_user_option_theme_key(user_option, attributes)
    OPTION_ATTR.each { |attribute| set_user_option_single_attribute(user_option, attributes, attribute) }
    # automatically disable digests when mailing_list_mode is enabled
    user_option.email_digests = false if user_option.mailing_list_mode

    return false unless User.transaction { user.user_option.save && user.user_profile.save && user.save }
    log_user_name_change( user.id, old_user_name, attributes.fetch(:name) { '' } )

    return true
  end

the UserUpdater#update has become almost three times bigger compared to the previous version however it now also tells us a better story.

It’s not perfect (and will never be) but we will make one more step to improve it and compare with the shorter version from Step #2 afterwards.

STEP #4

Code changes in this step can be found in the corresponding commit

In this step we will do final polishing and compare results

# user_updater.rb

# Short version
class UserUpdater
  # ...
  def update(attributes = {})
    old_user_name = user.name.present? ? user.name : ""

    update_user_profile( user.user_profile, attributes )
    update_user( user, attributes )
    update_user_option( user.user_option, attributes )
    save_user_data(user, old_user_name, attributes)
  end
# Two levels deep version
class UserUpdater
  # ...
  def update(attributes = {})
    @attributes = attributes
    old_user_name = user.name.present? ? user.name : ""

    set_user_profile_geo_data
    set_user_profile_web_data
    set_user_profile_background_data
    set_user_profile_bio_raw if should_update_user_profile_bio_raw?

    set_user_bio( update_title: can_grant_title?(user) )
    user.custom_fields = user.custom_fields.merge( attributes.fetch( :custom_fields, {} ) )

    set_user_option_theme_key if should_update_user_option_theme_key?
    OPTION_ATTR.each do |attribute|
      set_user_option_single_attribute( attribute )
    end
    # automatically disable digests when mailing_list_mode is enabled
    user_option.email_digests = false if user_option.mailing_list_mode

    return false unless User.transaction { save_user_and_related_entities }
    log_user_name_change( user.id, old_user_name, attributes.fetch(:name) { '' } )

    return true
  end

I believe longer version has the following benefits:

Code tells great story with lots of implementation details
It follows Open/Closed principle
You're always at most one step away from the full private method definition

Summary

In order to be two levels deep code has to follow the following rules:

Public methods can’t call other public methods of the same class
Private/protected methods can’t call other private/protected methods

I have two more rules of thumb

Avoid conditionals in private methods
Conditionals have to reflect on private methods rather than on boolean expressions

Code:

Food for thought

These rules are quite easy to follow in Service Objects because usually they describe some process/algorithm - where else they can be applied?
How about delegated methods, can we threat them as private when measuring?
How about accessor methods, can we threat them as private when measuring?

[UA] OOP та Cистемні Тести в Rails

Bohdan Pohorilets — Tue, 26 Dec 2017 00:00:00 +0000

Час: 30-40 min
Рівень: Середній/Високий
Код: GitHub

В цій статті ми на простому прикладі розглянемо як можна покращитиRails 5.1.3 System Test використовуючи Plain Old Ruby Objects,collaborators, delegators і module.

Крок #0

Приклад до рефакторингу

# test/system/users_test.rb
require "application_system_test_case"

class UsersTest < ApplicationSystemTestCase
  test "visiting the index" do
    visit users_url

    assert_selector "h1", text: "User"
  end

  test 'creating new user' do
    visit users_url
    click_on 'New User'
    fill_in 'First name', with: 'Bill'
    fill_in 'Last name', with: 'Bird'
    click_on 'Create User'
    visit users_url
    assert_text 'Bill Bird'
  end

  test 'editing existing user' do
    User.new(first_name: 'Bill', last_name: 'Bird').save
    visit edit_user_url(User.first)
    fill_in 'First name', with: 'First'
    fill_in 'Last name', with: 'Last'
    click_on 'Update User'
    assert_text 'First Last'
  end
end

Тест перевіряє три речі:

Чи можливо відкрити сторінку зі списком користувачів і чи має вона очікувану структуру
Чи можливо додати нового користувача і чи буде новий користувач на сторінці зі списком користувачів
Чи можливо оновити інформацію про користувача і чи будуть відображені зімни на сторінці зі списком користувачів

Крок #1

В цьому кроці ми:

Створимо новий абстрактний клас який в майбутному допоможе нам описати структуру та функціонал HTML сторінок
Створимо page class для тестування сторінки з інформацією про користувача
Використаємо новий page class в тесті

Для початку ми додамо абстрактний клас, який має один метод для визначення елементів на сторінці, зміни можна переглянути у відповідному комміті

# test/support/pages/base.rb
module Pages
  class Base
    Error = Class.new(StandardError)
    attr_reader :current_session
    attr_reader :url

    def self.has_node(method_name, selector, default_selector = :css, options = {})
      case default_selector
      when :css
        define_method(method_name) do
          css_selector = @css_wrapper + ' ' + selector
          current_session.first(default_selector, css_selector.strip, options)
        end
      when :xpath
        # XPATH accessor
        define_method(method_name) do
          current_session.first(default_selector, selector, options)
        end
      else
        fail Error, "Unknown selector #{default_selector}"
      end
    end

    private

    # initialize with Capybara session
    def initialize(url:, css_wrapper: ' ', current_session: Capybara.current_session)
      @current_session = current_session
      @url = url
      @css_wrapper = css_wrapper
    end
  end
end

Давайте детальніше розглянемо метод initilaize та instance variables у ньому:

@current_session - за замовчуванням Capybara.current_session,об’єкт-collaboratior що дозволяє нам використовувати driver всередині методу has_node
@url - обов’язкова змінна, URL сторінки що тестується
@css_wrapper - за замовчуванням порожня стрічка, допоміжний параметр, використовується коли всі елементи на сторінці знаходяться всередині елементу з певним CSS класом

Тепер додамо новий клас що описує сторінку з інформацією про користувача

# test/support/pages/users/show.rb
require_relative '../base'

module Pages
  module Users
    class Show < Pages::Base
      has_node :notice, '#notice'
      has_node :edit_user_link, 'a', :css, text: 'Edit'
      has_node :back_link, '//a[text()="Back"]', :xpath
    end
  end
end

Є три способи для визначення елементу на сторінці:

За CSS id
За типом і текстом всередині елементу
За xpath

Варто запам’ятати:

has_node лише обгортка навколоCapybara::Node::Finders#first тому є різні способи отримати один і той же результат
has_node повертає такий же результат що й Capybara::Node::Finders#first, якщо елемент був знайдений то це об’єкт Capybara::Node::Element

Тепер використаємо Pages::Users::Show в тесті для UsersController#show

  test 'creating new user' do
    visit users_url
    click_on 'New User'
    fill_in 'First name', with: 'Bill'
    fill_in 'Last name', with: 'Bird'
    click_on 'Create User'

    page = ::Pages::Users::Show.new(url: user_path(User.last))
    assert page.notice.text == 'User was successfully created.'
    assert page.edit_user_link.text == 'Edit'
    assert page.back_link.text == 'Back'

    visit users_url
    assert_text 'Bill Bird'
  end

цей крок досить малий, лише для того щоб зрозуміти як використовувати page classes

Крок #2

В цьому кроці ми:

Додамо новий Pages::Base#visit метод
Додамо Rails.application.routes.url_helpers до Pages::Base для того щоб мати доступ до routes
Додамо Pages::Users::New, Pages::Users::Edit, Pages::Users::Index
Використаємо нові класи для рефакторингу

Я не додаватиму код нових класів тут, його можна знайти у відповідному комміті. Натомість давайте поглянемо на тест, що їх використовує:

# test/system/users_test.rb
require 'application_system_test_case'
require File.join(Rails.root.to_s, 'test', 'support', 'pages', 'users', 'show')
require File.join(Rails.root.to_s, 'test', 'support', 'pages', 'users', 'new')
require File.join(Rails.root.to_s, 'test', 'support', 'pages', 'users', 'index')
require File.join(Rails.root.to_s, 'test', 'support', 'pages', 'users', 'edit')

class UsersTest < ApplicationSystemTestCase
  test "visiting the index" do
    visit users_url

    assert_selector "h1", text: "User"
  end

  test 'creating new user' do
    ::Pages::Users::Index.new.instance_eval do
      visit
      new_user_link.click
    end

    ::Pages::Users::New.new.instance_eval do
      visit
      first_name.set( 'Bill' )
      last_name.set( 'Bird' )
      create_user_button.click
    end

    page = ::Pages::Users::Show.new(url: user_path(User.last))
    assert page.notice.text == 'User was successfully created.'
    assert page.edit_user_link.text == 'Edit'
    assert page.back_link.text == 'Back'

    ::Pages::Users::Index.new.visit
    assert_text 'Bill Bird'
  end

  test 'editing existing user' do
    User.new(first_name: 'Bill', last_name: 'Bird').save

    ::Pages::Users::Edit.new(url: edit_user_url(User.first)).instance_eval do
      visit
      first_name.set( 'First' )
      last_name.set( 'Last' )
      update_user_button.click
    end

    ::Pages::Users::Index.new.visit
    assert_text 'First Last'
  end
end

У нас лишилось ще три кроки попереду проте давайте підсумуємо що ми вже отримали:

Ми використовуємо методи класу а не CSS/XPATH отож якщо структура сторінки зміниться ми повинні будемо змінити лише клас щоб виправити тести
Завдяки використанню collaborator objects код згрупований всередині блоків, його простіше зрозуміти і одразу очевидно на якій сторінці виконується кожна лінія коду

Крок #3

В цьому кроці ми:

Додамо можливість перевіряти чи присутній елемент всередині page classes
Додамо у Pages::Users::Show метод для перевірки структури сторінки

Для початку розглянемо зміни в тесті ( всі зміни у відповідному комміті)

До

  # test/system/users_test.rb
  test 'creating new user' do
    # Not important piece
    page = ::Pages::Users::Show.new(url: user_path(User.last))
    assert page.notice.text == 'User was successfully created.'
    assert page.edit_user_link.text == 'Edit'
    assert page.back_link.text == 'Back'

    ::Pages::Users::Index.new.visit
    assert_text 'Bill Bird'
  end

Після

  # test/system/users_test.rb
  test 'creating new user' do
    # Not important piece
    ::Pages::Users::Show.new(test: self, url: user_path(User.last)).instance_eval do
      check_main_elements_presence
      assert notice.text == 'User was successfully created.'
    end

    ::Pages::Users::Index.new.visit
    assert_text 'Bill Bird'
  end

Метод Pages::Users::Show#check_main_elements_presence

  # test/support/pages/users/show.rb
  def check_main_elements_presence
    notice_present?
    edit_user_link_present?
    back_link_present?
  end

Для отримання такого результату ми:

Змінили Pages::Base#initialize - тепер він очікує новий об’єкт-collaborator test:
Змінили Pages::Base#has_node - тепер він додає метод для доступу до елементу та перевірки наявності елементу на сторінці - *_present?

Крок #4

В цьому кроці ми вилучимо спільний функціонал у модуль (відповідний комміт)

Для початку порівняємо Pages::User::Edit та Pages::User::New

  # pages/user/edit.rb
  require_relative '../base'
  module Pages
    module Users
      class Edit < Pages::Base
        has_node :first_name, '#user_first_name'
        has_node :last_name, '#user_last_name'
        has_node :update_user_button, '//input[@value ="Update User"]', :xpath
      end
    end
  end

  # pages/user/new.rb
  require_relative '../base'
  module Pages
    module Users
      class New < Pages::Base
        has_node :first_name, '#user_first_name'
        has_node :last_name, '#user_last_name'
        has_node :create_user_button, '//input[@value= "Create User"]', :xpath

      private

        def http_path
          new_user_path
        end
      end
    end
  end

обидва мають однакові елементи first_name та last_name, що не дивно - ми render один і той самий partial form на обох сторінках. Окрім того ми заповнюємо цю форму коли тестуємо ці сторінки. Давайте вилучимо спільний функціонал у модуль.

`Pages::Users::Partials::UserForm` модуль

# test/support/pages/users/partials/user_form.rb
module Pages
  module Users
    module Partials
      module UserForm
        def self.included(clazz)
          clazz.has_node :first_name, '#user_first_name'
          clazz.has_node :last_name, '#user_last_name'
        end

        def fill_out_user_form(first: 'Bill', last: 'Bird')
          first_name.set(first)
          last_name.set(last)
        end
      end
    end
  end
end

Page classes після рефакторингу

  # pages/user/edit.rb
  require_relative '../base'
  module Pages
    module Users
      class Edit < Pages::Base
        include Partials::UserForm

        has_node :update_user_button, '//input[@value ="Update User"]', :xpath
      end
    end
  end

  # pages/user/new.rb
  require_relative '../base'
  module Pages
    module Users
      class New < Pages::Base
        include Partials::UserForm

        has_node :create_user_button, '//input[@value= "Create User"]', :xpath

      private

        def http_path
          new_user_path
        end
      end
    end
  end

Крок #5

В цьому кроці ми:

Додамо можливість робити скріншот до page classes
Порівняємо як виглядав тест до Крок #1 та після Крок #5

Перша частина досить проста, оскільки ми вже маємо тест як об’єкт-collaboratorу Pages::Base нам лише потрібно додати take_screenshot до списку методів які ми делегуємо,всі зміни можна переглянути у відповідному комміті

Тепер давайте порівняємо що ми мали на початку і як тест виглядає після рефакторингу

До

# test/system/users_test.rb
require "application_system_test_case"

class UsersTest < ApplicationSystemTestCase
  test "visiting the index" do
    visit users_url

    assert_selector "h1", text: "User"
  end

  test 'creating new user' do
    visit users_url
    click_on 'New User'
    fill_in 'First name', with: 'Bill'
    fill_in 'Last name', with: 'Bird'
    click_on 'Create User'
    visit users_url
    assert_text 'Bill Bird'
  end

  test 'editing existing user' do
    User.new(first_name: 'Bill', last_name: 'Bird').save
    visit edit_user_url(User.first)
    fill_in 'First name', with: 'First'
    fill_in 'Last name', with: 'Last'
    click_on 'Update User'
    assert_text 'First Last'
  end
end

Після

# test/system/users_test.rb
require 'application_system_test_case'
require File.join(Rails.root.to_s, 'test', 'support', 'pages', 'users', 'show')
require File.join(Rails.root.to_s, 'test', 'support', 'pages', 'users', 'new')
require File.join(Rails.root.to_s, 'test', 'support', 'pages', 'users', 'index')
require File.join(Rails.root.to_s, 'test', 'support', 'pages', 'users', 'edit')

class UsersTest < ApplicationSystemTestCase
  test "visiting the index" do
    visit users_url

    assert_selector "h1", text: "User"
  end

  test 'creating new user' do
    ::Pages::Users::Index.new(test: self).instance_eval do
      visit
      new_user_link.click
      take_screenshot
    end

    ::Pages::Users::New.new.instance_eval do
      visit
      fill_out_user_form
      create_user_button.click
    end

    ::Pages::Users::Show.new(test: self, url: user_path(User.last)).instance_eval do
      check_main_elements_presence
      assert notice.text == 'User was successfully created.'
    end

    ::Pages::Users::Index.new.visit
    assert_text 'Bill Bird'
  end

  test 'editing existing user' do
    User.new(first_name: 'Bill', last_name: 'Bird').save

    ::Pages::Users::Edit.new(url: edit_user_url(User.first)).instance_eval do
      visit
      fill_out_user_form(first: 'First', last: 'Last')
      update_user_button.click
    end

    ::Pages::Users::Index.new(test: self).instance_eval do
      visit
      assert_text 'First Last'
    end
  end
end

версія ‘Після’ має певні переваги, ми перерахуємо їх у підсумку

Підсумок

Переваги OO підходу:

Тести менш ‘крихкі’ - якщо структура чи логіка сторінки зміниться досить буде змінити лише page class
Тести більш зрозумілі - завдяки використанню instance_eval та блоків завжди зрозуміло на якій сторінці ви знаходитесь
Значно простіше описати структуру сторінки
Однаковий функціонал можна помістити в модуль
Інші члени команди можуть використовувати готові page classes
Pages classes є POROs, Ви можете використовувати всю красу/потужність Ruby в них

Код:

Для роздумів:

Мені не подобається що Pages::Base має include Rails.application.routes.url_helpers. Це було зроблено лише щоб показати що статичний URL може бути частиною page class, має бути кращий спосіб
has_node працює лише з одним елементом, варто додати has_nodes для колекцій
В залежності від використаного фреймворку, методи делеговані в Pages::Base відрізнятимуться, проте його можна використовувати з іншими фреймворками (RSpec, …)
Замість багатьох тестів можна мати один супер-тест, тоді не доведеться чистити базу даних, можна групувати частини тесту за роллю користувача. Додаткові дані в базі можуть допомогти знайти глюки або лише ускладнити Ваше життя =)

OOP and System Tests in Ruby on Rails

Bohdan Pohorilets — Mon, 16 Oct 2017 00:00:00 +0000

Time: 30-40 min
Level: Intermediate/Advanced
Code: GitHub

In this post we will take a look at a way to improve sample Rails 5.1.3 System Test using POROs, collaborators, delegation and modules.

STEP #0

Basic system test, before refactoring

# test/system/users_test.rb
require "application_system_test_case"

class UsersTest < ApplicationSystemTestCase
  test "visiting the index" do
    visit users_url

    assert_selector "h1", text: "User"
  end

  test 'creating new user' do
    visit users_url
    click_on 'New User'
    fill_in 'First name', with: 'Bill'
    fill_in 'Last name', with: 'Bird'
    click_on 'Create User'
    visit users_url
    assert_text 'Bill Bird'
  end

  test 'editing existing user' do
    User.new(first_name: 'Bill', last_name: 'Bird').save
    visit edit_user_url(User.first)
    fill_in 'First name', with: 'First'
    fill_in 'Last name', with: 'Last'
    click_on 'Update User'
    assert_text 'First Last'
  end
end

it verifies three things:

If we can visit the index page and if it has the structure we expect
If we can create a new user and see it on the index user page
If we can update user information and see the changes on the index user page

Step #1

In this step we’ll:

Introduce an abstract clas that will help us describe page structure and functionality
Add a page class to test show user page
Use new page class in a test

As a first step let’s introduce an abstract class with a single method that will help us specify what elements we have on the page, actions from this step can be found in the corresponding commit

# test/support/pages/base.rb
module Pages
  class Base
    Error = Class.new(StandardError)
    attr_reader :current_session
    attr_reader :url

    def self.has_node(method_name, selector, default_selector = :css, options = {})
      case default_selector
      when :css
        define_method(method_name) do
          css_selector = @css_wrapper + ' ' + selector
          current_session.first(default_selector, css_selector.strip, options)
        end
      when :xpath
        # XPATH accessor
        define_method(method_name) do
          current_session.first(default_selector, selector, options)
        end
      else
        fail Error, "Unknown selector #{default_selector}"
      end
    end

    private

    # initialize with Capybara session
    def initialize(url:, css_wrapper: ' ', current_session: Capybara.current_session)
      @current_session = current_session
      @url = url
      @css_wrapper = css_wrapper
    end
  end
end

Let’s take a closer look at initilaize method and instance variablesthere:

@current_session - defaults to Capybara.current_session,collaboratior object that allows us use driver inside has_node method
@url - requidred parameter, URL of the page under test
@css_wrapper - defaults to an empty string, helpful when all elements under test are within an element with particular CSS class

Now let’s introduse a new class that describes a show user page

# test/support/pages/users/show.rb
require_relative '../base'

module Pages
  module Users
    class Show < Pages::Base
      has_node :notice, '#notice'
      has_node :edit_user_link, 'a', :css, text: 'Edit'
      has_node :back_link, '//a[text()="Back"]', :xpath
    end
  end
end

You can see here three ways to identify an element on the page:

By CSS id
By type and text
By xpath

Things to remember:

has_node is only a wrapper aroundCapybara::Node::Finders#first so same thing may bedone in a few ways
has_node result is equal to Capybara::Node::Finders#first, if the element is found it’s result is aninstance of Capybara::Node::Element

Now let’s use Pages::Users::Show in the test for UsersController#show

  test 'creating new user' do
    visit users_url
    click_on 'New User'
    fill_in 'First name', with: 'Bill'
    fill_in 'Last name', with: 'Bird'
    click_on 'Create User'

    page = ::Pages::Users::Show.new(url: user_path(User.last))
    assert page.notice.text == 'User was successfully created.'
    assert page.edit_user_link.text == 'Edit'
    assert page.back_link.text == 'Back'

    visit users_url
    assert_text 'Bill Bird'
  end

this is a small first step to understand better how to use page classes

Step #2

In this step we will:

Introuduce a new Pages::Base#visit method
Include Rails.application.routes.url_helpers in Pages::Base inorder to have access to the routes inside the class
Add Pages::Users::New, Pages::Users::Edit, Pages::Users::Indexclasses
Use new classes to refactor our sample test

I won’t include code for new pages here you can find it in the corresponding commit. Let’s take a look at how the test looks now instead:

# test/system/users_test.rb
require 'application_system_test_case'
require File.join(Rails.root.to_s, 'test', 'support', 'pages', 'users', 'show')
require File.join(Rails.root.to_s, 'test', 'support', 'pages', 'users', 'new')
require File.join(Rails.root.to_s, 'test', 'support', 'pages', 'users', 'index')
require File.join(Rails.root.to_s, 'test', 'support', 'pages', 'users', 'edit')

class UsersTest < ApplicationSystemTestCase
  test "visiting the index" do
    visit users_url

    assert_selector "h1", text: "User"
  end

  test 'creating new user' do
    ::Pages::Users::Index.new.instance_eval do
      visit
      new_user_link.click
    end

    ::Pages::Users::New.new.instance_eval do
      visit
      first_name.set( 'Bill' )
      last_name.set( 'Bird' )
      create_user_button.click
    end

    page = ::Pages::Users::Show.new(url: user_path(User.last))
    assert page.notice.text == 'User was successfully created.'
    assert page.edit_user_link.text == 'Edit'
    assert page.back_link.text == 'Back'

    ::Pages::Users::Index.new.visit
    assert_text 'Bill Bird'
  end

  test 'editing existing user' do
    User.new(first_name: 'Bill', last_name: 'Bird').save

    ::Pages::Users::Edit.new(url: edit_user_url(User.first)).instance_eval do
      visit
      first_name.set( 'First' )
      last_name.set( 'Last' )
      update_user_button.click
    end

    ::Pages::Users::Index.new.visit
    assert_text 'First Last'
  end
end

We have three more steps left, but let’s take a look what we’ve acheivedalready:

Now we use class methods instead of raw selectors so if page structure change we will have to change only the corresponding class
Because we use collaborator objects we have nice blocks and it’sclear on what page we are an every line

Step #3

In this step we will:

Add ability to verify if the element is present in page classes
Add a method to Pages::Users::Show to verify page structure

Let’s take a look at the changes in the test first (corresponding commit)

Before

  # test/system/users_test.rb
  test 'creating new user' do
    # Not important piece
    page = ::Pages::Users::Show.new(url: user_path(User.last))
    assert page.notice.text == 'User was successfully created.'
    assert page.edit_user_link.text == 'Edit'
    assert page.back_link.text == 'Back'

    ::Pages::Users::Index.new.visit
    assert_text 'Bill Bird'
  end

After

  # test/system/users_test.rb
  test 'creating new user' do
    # Not important piece
    ::Pages::Users::Show.new(test: self, url: user_path(User.last)).instance_eval do
      check_main_elements_presence
      assert notice.text == 'User was successfully created.'
    end

    ::Pages::Users::Index.new.visit
    assert_text 'Bill Bird'
  end

Pages::Users::Show#check_main_elements_presence definition

  # test/support/pages/users/show.rb
  def check_main_elements_presence
    notice_present?
    edit_user_link_present?
    back_link_present?
  end

In order to do this step we:

Changed the Pages::Base#initialize to accept new collaboratorobject test:
Changed the Pages::Base#has_node to define both accessor and*_present? methods

Step #4

In this step we will extract functionality into a module (corresponding_commit)

Let’s first compare Pages::User::Edit and Pages::User::New

  # pages/user/edit.rb
  require_relative '../base'
  module Pages
    module Users
      class Edit < Pages::Base
        has_node :first_name, '#user_first_name'
        has_node :last_name, '#user_last_name'
        has_node :update_user_button, '//input[@value ="Update User"]', :xpath
      end
    end
  end

  # pages/user/new.rb
  require_relative '../base'
  module Pages
    module Users
      class New < Pages::Base
        has_node :first_name, '#user_first_name'
        has_node :last_name, '#user_last_name'
        has_node :create_user_button, '//input[@value= "Create User"]', :xpath

      private

        def http_path
          new_user_path
        end
      end
    end
  end

they both have two same nodes first_name and last_name, which isn’t strange - we render same partial form on both pages. Except for that when testing these pages we fill out this form, let’s extract these two pieces to a module.

`Pages::Users::Partials::UserForm` module

# test/support/pages/users/partials/user_form.rb
module Pages
  module Users
    module Partials
      module UserForm
        def self.included(clazz)
          clazz.has_node :first_name, '#user_first_name'
          clazz.has_node :last_name, '#user_last_name'
        end

        def fill_out_user_form(first: 'Bill', last: 'Bird')
          first_name.set(first)
          last_name.set(last)
        end
      end
    end
  end
end

Pages after refactoring

  # pages/user/edit.rb
  require_relative '../base'
  module Pages
    module Users
      class Edit < Pages::Base
        include Partials::UserForm

        has_node :update_user_button, '//input[@value ="Update User"]', :xpath
      end
    end
  end

  # pages/user/new.rb
  require_relative '../base'
  module Pages
    module Users
      class New < Pages::Base
        include Partials::UserForm

        has_node :create_user_button, '//input[@value= "Create User"]', :xpath

      private

        def http_path
          new_user_path
        end
      end
    end
  end

Step #5

In This step we will:

Add ability to take screenshots to the page classes
Compare test we had before Step #1 and after Step #5

First item is quite straightforward, since we already have a test as a collaborator in Pages::Base we only need to add take_screenshot to a list of methods we delegate, you can find changes in thecorresponding commit

Now let’s compare what we had in the beginning

Before

# test/system/users_test.rb
require "application_system_test_case"

class UsersTest < ApplicationSystemTestCase
  test "visiting the index" do
    visit users_url

    assert_selector "h1", text: "User"
  end

  test 'creating new user' do
    visit users_url
    click_on 'New User'
    fill_in 'First name', with: 'Bill'
    fill_in 'Last name', with: 'Bird'
    click_on 'Create User'
    visit users_url
    assert_text 'Bill Bird'
  end

  test 'editing existing user' do
    User.new(first_name: 'Bill', last_name: 'Bird').save
    visit edit_user_url(User.first)
    fill_in 'First name', with: 'First'
    fill_in 'Last name', with: 'Last'
    click_on 'Update User'
    assert_text 'First Last'
  end
end

and how the test looks now

After

# test/system/users_test.rb
require 'application_system_test_case'
require File.join(Rails.root.to_s, 'test', 'support', 'pages', 'users', 'show')
require File.join(Rails.root.to_s, 'test', 'support', 'pages', 'users', 'new')
require File.join(Rails.root.to_s, 'test', 'support', 'pages', 'users', 'index')
require File.join(Rails.root.to_s, 'test', 'support', 'pages', 'users', 'edit')

class UsersTest < ApplicationSystemTestCase
  test "visiting the index" do
    visit users_url

    assert_selector "h1", text: "User"
  end

  test 'creating new user' do
    ::Pages::Users::Index.new(test: self).instance_eval do
      visit
      new_user_link.click
      take_screenshot
    end

    ::Pages::Users::New.new.instance_eval do
      visit
      fill_out_user_form
      create_user_button.click
    end

    ::Pages::Users::Show.new(test: self, url: user_path(User.last)).instance_eval do
      check_main_elements_presence
      assert notice.text == 'User was successfully created.'
    end

    ::Pages::Users::Index.new.visit
    assert_text 'Bill Bird'
  end

  test 'editing existing user' do
    User.new(first_name: 'Bill', last_name: 'Bird').save

    ::Pages::Users::Edit.new(url: edit_user_url(User.first)).instance_eval do
      visit
      fill_out_user_form(first: 'First', last: 'Last')
      update_user_button.click
    end

    ::Pages::Users::Index.new(test: self).instance_eval do
      visit
      assert_text 'First Last'
    end
  end
end

after version has few advantages, they will be listed in a summary section

Summary

Advantages of the OO approach:

Tests are less brittle - if page structure/logic changes you will need to change only corresponding page class
Tests are more readable - because of instance_eval blocks you always know which page are you on
It’s much easier to define elements that exist on the page
Same functionality can be extracted
Other team members may use page classes in their tests
Pages are POROs, all the beauty/power of Ruby can be used there

Code:

Food for thought

I’m not happy with the fact that Pages::Base has include Rails.application.routes.url_helpers. This is done only to show that if the page URL is static it can become a part of the page class, there should be a better way to achieve it
has_node works only for a single element, would be cool to have has_nodes for collections. Once again page classes are POROs so they may and should be changed to fit your needs
Folder with page classes may be a part of autoload paths, but noteveryone likes autoloading
Depending on a test framework delegated methods in Pages::Base will differ, but it can be used with other test frameworks (like RSpec) too
Instead of having multiple test there could be one test, you won’t truncate database, you may have tests grouped by the user that is logged in, additional data in the database may help you discover bugs or make your hate your life :)

Forem: Bohdan Pohorilets

[EN] Rails 7 application inside Docker on macOS - part one

TL;DR - Gist

Process step-by-step

Step #1 - Create a folder for a project on local drive

Step #2 - Create Gemfile with ruby/rails version within this folder

Step #3 - Create configuration for Docker

Step 4 - Build a Docker image

Step 5 - Install rails in the new container

Step 6 - Create new rails project

Step 7 - Start the server

Extra

#docker Follow

[EN] To mock, or not to mock, that is the question

References

[UA] Предметно-орієнтована архітектура Rails

Розділення перегляду та бізнес-логіки

Розділення середовищ та побудова незалежних тестів

Налаштування тестового середовища предметної області

налаштування тестового середовища для представлення

Фінальні частини

Підсумок

[EN] Domain Driven Rails Architecture

Separation of representation and domain

Separation of environments and building independent test suites

Domain test suite configuration

Representations test suite configuration

Final parts

Summary

[UA] Приклад архітектури Модульний Моноліт в Ruby on Rails

Огляд Gem

розділення залежностей

розділення тестів

Огляд Engine

розділення залежностей

розділення тестів

розділення migrations

розділення локалізацій

Використання аутентифікації в батьківському проекті

Тестування Engine/Gem в батьківському проекті

Висновки

Подумати:

Modular Monolith Example

Gem Overview

separation of dependencies

separation of tests

Engine Overview

separation of dependencies

separation of tests

separation of migrations

separation of translations

Enabling authentication in the main application

Testing Engine/Gem Integration into a main application

Summary

Food for thought

[UA] Service Objects Глибиною В Два Рівні

КРОК #1

КРОК #2

КРОК #3

КРОК #4

ПІДСУМОК

ДЛЯ РОЗДУМІВ

Two Levels Deep Service Objects

STEP #1

STEP #2

STEP #3

STEP #4

Summary

Food for thought

[UA] OOP та Cистемні Тести в Rails

Крок #0

Крок #1

Крок #2

Крок #3

До

Після

Крок #4

Pages::Users::Partials::UserForm модуль

Page classes після рефакторингу

Крок #5

Step #2 - Create `Gemfile` with ruby/rails version within this folder

`Pages::Users::Partials::UserForm` модуль

`Pages::Users::Partials::UserForm` module