Compass Portal — 🟦 Edition

dev branch:

main branch: , live app: Heroku

A web application for finding your way, written in Ruby on Rails. Created in the Scalable Software Engineering course at the HPI in Potsdam.

Development Setup

Ensure you have access to a Unix-like environment through:

• Your local Linux / MacOS installation
• Using the Windows Subsystem for Linux (WSL)
• Using a VM, e.g. Virtualbox and Vagrant
• Using a docker container

Application Setup

• ruby --version Ensure Ruby v2.7.4 using rbenv or RVM
• sqlite3 --version Ensure SQLite3 database installation
• node --version; yarn --version Ensure Node.js and Yarn installation
• bundle --version Ensure Bundler installation (gem install bundler)
• bundle config set without 'production' && bundle install Install gem dependencies from Gemfile
• yarn install Install JS dependencies from package.json
• rails db:migrate Setup the database, run migrations
• rails s Start dev server (default port 3000 required for local HPI OpenID Connect)
• bundle exec rspec --format documentation Run the tests (using RSpec framework)

Developer Guide

Employed Frameworks

• Fontawesome icons
• Bootstrap for layout and styling
• Devise library for authentication
• OmniAuth & OmniAuth OpenID Connect for HPI OpenID
• FactoryBot to generate test data
• Capybara for feature testing
• shoulda for additional RSpec matchers

Cheat Sheets

• FactoryBot
• Testing using Capybara

Setup

• bundle exec rails db:migrate RAILS_ENV=development && bundle exec rails db:migrate RAILS_ENV=test Migrate both test and development databases
• rails assets:clobber && rails webpacker:compile Redo asset compilation

Testing

• bundle exec rspec Run the full test suite
  • --format doc More detailed test output
  • -e 'search keyword in test name' Specify what tests to run dynamically
  • --exclude-pattern "spec/features/**/*.rb" Exclude feature tests (which are typically fairly slow)
• bundle exec rspec spec/<rest_of_file_path>.rb Specify a folder or test file to run
• bundle exec rspec --profile Examine run time of tests
• Code coverage reports are written to coverage/index.html after test runs (by simplecov)

Linting

• rake factory_bot:lint Create each factory and catch any exceptions raised during the creation process (defined in lib/tasks/factory_bot.rake)
• bundle exec rubocop Use the static code analyzer RuboCop to find possible issues (based on the community Ruby style guide).
  • --auto-correct to fix what can be fixed automatically.
  • RuboCop's behavior can be controlled using .rubocop.yml

Debugging

• console anywhere in the code to access an interactive console
• save_and_open_page within a feature test to inspect the state of a webpage in a browser
• rails c --sandbox Test out some code in the Rails console without changing any data
• rails dbconsole Starts the CLI of the database you're using
• bundle exec rails routes Show all the routes (and their names) of the application
• bundle exec rails about Show stats on current Rails installation, including version numbers

Generating

• rails g migration DoSomething Create migration _db/migrate/*DoSomething.rb
• rails generate takes a --pretend / -p option that shows what will be generated without changing anything

HPI OpenID Connect Configuration

• config/initializers/devise.rb contains the OmniAuth OpenID Connect config for the HPI OIDC service
• An OpenID Connect client for localhost:3000 is set up for local development. Additional clients registrable at oidc.hpi.de
• For deployment OPENID_CONNECT_CLIENT_ID, OPENID_CONNECT_CLIENT_SECRET & OPENID_CONNECT_REDIRECT_URI need to be provided
• app/controllers/users/omniauth_callbacks_controller.rb handles data returned by the OIDC service

Branch Name Conventions

• Branch names have the following structure: <type>/<team>_<issue-number>_<issue-name>
• <type> gets replaced with feature or fix, depending on the type of changes introduced by the branch
• <team> gets replaced with the abbreviation of the team that mostly develops on the branch
• <issue-number> gets replaced with the number of the issue the branch aims to close
• <issue-name> gets replaced with the name of the issue the branch aims to close, or a shortened form of it
• Experimental branches may use the structure experimental/<anything>