Visualize the architecture of your Ruby app in RubyMine, in 2 / minutes
Tags: ruby, rails, webdev, productivity
Published: 2021-05-27 12:34:22

[AppMap](https://plugins.jetbrains.com/plugin/16701-appmap) is an open source RubyMine plugin which helps you improve your code by showing you how it behaves, feature by feature, as you work. It does this by automatically generating interactive maps of architecture and code behavior right in your editor.

This 2 ¹/₂ minute video shows how to install the AppMap plugin, how to configure it to map your Ruby application, and how to navigate your code using the interactive diagrams.

It uses the Rails Sample App as an example program.

Here are the step-by-step instructions that are demonstrated in the video, or you can follow the [Quickstart AppMap instructions](https://appland.com/docs/quickstart/) directly in your RubyMine IDE.

## How it works

![How AppMap works](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/01p0d6p5b4k4b1chmt9n.png)

AppMap works by recording code execution paths of your app and visualizing them in interactive diagrams directly in your code editor. A good way to create AppMaps is by recording unit, functional or integration test cases. The Rail Sample App project uses minitest tests, which will be a source of AppMaps in this demo.

## Install the AppMap plugin

`00:03` Installing AppMap from the JetBrains Marketplace takes only a moment: 

- Open the RubyMine preferences
- Select Plugins, click on the Marketplace tab and search for `AppMap`
- Click on the `Install` button, then click on `Restart IDE`.

![AppMap in Marketplace](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1yl6rkjdut9gvvix0pfc.png)

When the IDE restarts, the AppMap plugin is installed and ready for viewing AppMaps.

## Configure AppMap for the Rails Sample App recording

### 1. Add appmap gem, appmap railtie and appmap for minitest

`00:10` In the first step, instrument the application for AppMap recording. Add the appmap gem to the Gemfile and run `bundle` to install.

```ruby
group :development, :test do
  gem 'appmap'
```

`00:18` Next, add the appmap railtie. The railtie will only be activated if the appmap gem is in the bundle.

```ruby
require 'appmap/railtie' if %w[test development].member?(Rails.env)
```

`00:27` The Rails Sample App uses minitest. To `test_helper.rb`, add

```ruby
require 'appmap/minitest'
```

This should be placed before any of the application code is loaded.



### 2. Configure appmap.yml

The AppMap framework uses a file called `appmap.yml` to determine which code to map. 

`00:42` Create a new file `appmap.yml` in the root folder of your project. You should add all the source folders and gems of your project that you want to capture. Here is an example for the Rails Sample App that is used in this demo:

```yaml
name: sample_app_6th_ed
packages:
- path: app/controllers
- path: app/helpers
- path: app/jobs
- path: app/mailers
- path: app/models
- gem: image_processing
- gem: mini_magick
- gem: active_storage_validations
- gem: bcrypt
- gem: will_paginate
```

## Record AppMaps from tests

`00:58` Now you are ready to record an appmap.  To get a recording, run a test with the environment variable `APPMAP=true`

It is easy to modify the test Run configuration to include the APPMAP variable in RubyMine.

![Test run configuration](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8fyzblj14fei55jgs7fn.png)

When the test is run, an AppMap will be recorded in the `tmp/appmap/minitest` folder.

![Run test in RubyMine](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4ct0aiymyucsjz2nj30r.png)

Note: you can run the tests and record AppMaps directly from the command line:

```shell
$ APPMAP=true bundle exec rake test
```

## Open a generated AppMap in RubyMine

`01:17` Open the AppMaps view - click on the `AppMaps` tab in the UI. Or, press `CTRL or COMMAND + SHIFT + A`, then type "AppMaps" in the search box and pick the `AppMaps View" from the list.

Select an AppMap from the list of all AppMaps found in the project folders, or search for an AppMap with a specific phrase in its name.

Double click on an AppMap in the list, an interactive diagram viewer opens.

![Dependency Map](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yg810oay44z58x21v5io.png)

## Interact with the AppMap diagram

`01:20` Discover how the Rails Sample Application works in the AppMap diagrams. 

- Start with the big picture of your software design and view all code components in the Dependency Map - Web Service endpoints, Java packages/classes/functions and SQL commands and their inter-dependencies
- Navigate to sources of classes and functions directly from the diagrams so you don't have to look for them manually
- Drill down the execution details of code and SQL in the execution Trace.

![Execution Trace](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/699dc2hx58tkglvxv54u.png)

Or, you can use a bottom-up approach. Let's say you want to know what code modifies data in the database. 

- Start with a SQL command of interest - like an UPDATE
- View how it's connected to other calls in the Trace, then backtrack to its calling component and open its source file 
- See how it is connected to other code and Web Service endpoints.

![Trace with source code](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/u7seitl8ikhf67nunidk.png)

## Learn more about AppMap

This is only a small demonstration of the AppMap capabilities. For more information, step-by-step instructions and practical how-tos, check out the [AppMap documentation](https://appland.com/docs).

**Acknowledgements**

Thanks to [Petr](https://dev.to/ptrdvrk) and Dan for all their hard work on this video!