README.md

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 db:reset Seeds the database
• 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)

Commands to run after pulling new changes

• rails db:migrate
• rails db:reset

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

Mapbox

To use the map's routing capabilities, you will need an access token for the Mapbox directions API. Place this token in an environment variable called MAPBOX_ACCESS_TOKEN

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