Record scenarios for Ruby projects

Add   gem 'appmap' to your Gemfile just as you would any other dependency.

gem 'appmap'

If you want to segregate installation to development or test environment use:

group :development, :test do
  gem 'appmap'
end

Then run bundle install.

Configure appmap.yml

Create a file called appmap.yml in the root directory of your project.

When you run your program, the appmap gem will read configuration settings from this file. A sample configuration file for a typical Rails project is provided below.

Customize the sample by providing an application name:

name: 
packages:
- path: app/controllers
- path: app/models

Code that doesn’t match a path entry in appmap.yml is not recorded. It’s basically a way to tell AppLand which code is “your code” vs “other / library code.” For more information and to see advanced configurations of appmap.yml check out the README.

Organizational Scoping

An organization in AppLand is a place where you and your team can access a shared group of applications. To create a new organization or view your organization memberships, check out the Organizations section of your account settings.

To upload data to an application that is owned by an organization you belong to, include the organization name in the name parameter (name: my-org/my-app).

By omitting the organization name, data will be uploaded to your own personal account.

If you're looking for the name of an existing application, visit the home page for a list of applications that you have access to.

Add Railtie dependency

If you are using Ruby on Rails, you'll have to require the railtie AFTER Rails is loaded.

config/application.rb is a standard place to add the dependency, but should go wherever railties are being loaded, such as environment specific config files or initializers.

require 'rails/all'
require 'appmap/railtie'

require 'active_record/railtie'
require 'action_controller/railtie'
require 'action_mailer/railtie'
require 'sprockets/railtie'
require 'appmap/railtie'

See the README for more information.

AppLand leverages existing test cases as a source of data, recording code and data flow in real-time. We support the following testing frameworks:

• RSpec
• Minitest
• Cucumber

Include the appropriate AppMap dependency for the testing framework used by your project. Follow the links above for more information on how to integrate each dependency.

If your testing framework isn't included here, let us know by joining the discussion on Discord.

Run tests with the environment variable APPMAP=true

$ APPMAP=true bundle exec rake

Each test will output a data file into the directory tmp/appmap/[framework]. For an RSpec example:

$ find tmp/appmap/rspec
my_app_behaves_as_expected.appmap.json

That's all! You've successfully recorded AppMaps from your test suite.