appmap 0.27.0 → 0.33.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd23faab460498cfac79b397c4fc87920df8d1a984142909542f524057d1e4cb
-  data.tar.gz: a967224c65d6a479287768389feb73a378e6e1be133f1033d06be6034a43b18e
+  metadata.gz: ae23c62b9a3f01cc3b7680706746d2f51c94c3a776978a8ee2d4e0e8501fca01
+  data.tar.gz: 4aa33af19ed0c31b826f8cffa75e147e2781fe93ed39353ace29cede8a7882b9
 SHA512:
-  metadata.gz: 7822e4c821cb5e57579163fdd080bc3b74fb5ad0c8999bc6e3d29ace636301d8ed931966abfe9a59a6a59603f83af03e82130c241293ee198173ef6f6f41ebd1
-  data.tar.gz: 8ba03667929d4571e13439ab53420934e0b1c9ee4605dfd71e9a7ff82b984d34e37ca43e206cbf5dc750201df93dc8dc9babbdafbadf12a86051e52efc6ef985
+  metadata.gz: 04a3c1bee70c02c96c1b71d5153a6ed44d668d6fc69d6da77cd6201364ede609bee93604f4ace391ddb38f8259841d6b334fdbe9051f1667d41cf3383281fe58
+  data.tar.gz: c60d868b2c1fa9c1e8742856dd7f946f5bf1284cab01a4478708c1582add5ca8fd16002e150d8a2cd897819edb661a9082cb01ec3e9879686d85d49b341d4ba8

data/.gitignore

@@ -1,7 +1,6 @@
 .DS_Store
 /html/
-/.appmap/
-/.bundle/
+.bundle
 /.yardoc
 /_yardoc/
 /coverage/
@@ -16,4 +15,3 @@ appmap.json
 .vscode
 .byebug_history
 
-/test/fixtures/rspec_recorder/.bundle/

data/CHANGELOG.md

@@ -1,3 +1,40 @@
+# v0.33.0
+
+* Added command `AppMap.open` to open an AppMap in the browser.
+
+# v0.32.0
+
+* Removes un-necessary fields from `return` events.
+
+# v0.31.0
+
+* Add the ability to hook methods by default, and optionally add labels to them in the
+  classmap. Use it to hook `ActiveSupport::SecurityUtils.secure_compare`.
+  
+# v0.30.0
+
+* Add support for Minitest.
+
+# v0.29.0
+
+* Add `lib/appmap/record.rb`, which can be `require`d to record the rest of the process.
+
+# v0.28.1
+
+* Fix the `defined_class` recorded in an appmap for an instance method included in a class
+  at runtime.
+* Only include the `static` attribute on `call` events in an appmap. Determine its value
+  based on the receiver of the method call.
+
+# v0.28.0
+
+* Change behavior of **AppMap.record** to return a complete AppMap as a Hash.
+* Update README with information about recording Cucumber tests.
+* **AppMap.initialize** automatically runs when `AppMap` is required, unless disabled
+  by environment variable `APPMAP_INITIALIZE=false`.
+* **AppMap.hook** no longer takes a `configuration` argument.
+* Add **AppMap::Util.scenario_filename**.
+
 # v0.27.0
 
 * Add **AppMap.record** to programatically record and capture an AppMap of a Ruby block.

data/README.md

@@ -1,18 +1,24 @@
 - [About](#about)
-- [Testing](#testing)
 - [Installation](#installation)
 - [Configuration](#configuration)
 - [Running](#running)
   - [RSpec](#rspec)
+  - [Minitest](#minitest)
+  - [Cucumber](#cucumber)
   - [Remote recording](#remote-recording)
   - [Ruby on Rails](#ruby-on-rails)
 - [Uploading AppMaps](#uploading-appmaps)
+- [Development](#development)
+  - [Running tests](#running-tests)
+  - [Using fixture apps](#using-fixture-apps)
+    - [`test/fixtures`](#testfixtures)
+    - [`spec/fixtures`](#specfixtures)
 - [Build status](#build-status)
 
 # About
 
 `appmap-ruby` is a Ruby Gem for recording
-[AppMaps](https://github.com/applandinc/appmap) of your code. 
+[AppMaps](https://github.com/applandinc/appmap) of your code.
 "AppMap" is a data format which records code structure (modules, classes, and methods), code execution events
 (function calls and returns), and code metadata (repo name, repo URL, commit
 SHA, labels, etc). It's more granular than a performance profile, but it's less
@@ -22,26 +28,15 @@ There are several ways to record AppMaps of your Ruby program using the `appmap`
 
 * Run your RSpec tests with the environment variable `APPMAP=true`. An AppMap will be generated for each spec.
 * Run your application server with AppMap remote recording enabled, and use the AppMap.
-  browser extension to start, stop, and upload recordings. 
+  browser extension to start, stop, and upload recordings.
 * Run the command `appmap record <program>` to record the entire execution of a program.
 
 Once you have recorded some AppMaps (for example, by running RSpec tests), you use the `appland upload` command
 to upload them to the AppLand server. This command, and some others, is provided
-by the [AppLand CLI](https://github.com/applandinc/appland-cli/releases), to
+by the [AppLand CLI](https://github.com/applandinc/appland-cli/releases).
 Then, on the [AppLand website](https://app.land), you can
 visualize the design of your code and share links with collaborators.
 
-# Testing
-Before running tests, configure `local.appmap` to point to your local `appmap-ruby` directory.
-```
-$ bundle config local.appmap $(pwd)
-```
-
-Run the tests via `rake`:
-```
-$ bundle exec rake test
-```
-
 # Installation
 
 Add `gem 'appmap'` to your Gemfile just as you would any other dependency.
@@ -60,7 +55,7 @@ group :development, :test do
 end
 ```
 
-Then install with `bundle`. 
+Then install with `bundle`.
 
 # Configuration
 
@@ -90,36 +85,37 @@ Each entry in the `packages` list is a YAML object which has the following keys:
 
 ## RSpec
 
-To instrument RSpec tests, follow these additional steps:
+To record RSpec tests, follow these additional steps:
 
-1) Require `appmap/rspec` in your `spec_helper.rb`.
+1) Require `appmap/rspec` in your `spec_helper.rb` before any other classes are loaded.
 
 ```ruby
 require 'appmap/rspec'
 ```
 
-2) Add `appmap: true` to the tests you want to instrument.
+Note that `spec_helper.rb` in a Rails project typically loads the application's classes this way:
 
 ```ruby
-describe Hello, appmap: true do
-  describe 'says hello' do
-    it 'when prompted' do
-      expect(Hello.new.say_hello).to eq('Hello!')
-    end
-  end
-end
+require File.expand_path("../../config/environment", __FILE__)
 ```
 
-3) *Optional* Add `feature: '<feature name>'` and `feature_group: '<feature group name>'` annotations to your 
+and `appmap/rspec` must be required before this:
+
+```ruby
+require 'appmap/rspec'
+require File.expand_path("../../config/environment", __FILE__)
+```
+
+2) *Optional* Add `feature: '<feature name>'` and `feature_group: '<feature group name>'` annotations to your 
    examples. 
 
-4) Run the tests with the environment variable `APPMAP=true`:
+3) Run the tests with the environment variable `APPMAP=true`:
 
 ```sh-session
 $ APPMAP=true bundle exec rspec -t appmap
 ```
 
-Each RSpec test will output a data file into the directory `tmp/appmap/rspec`. For example:
+Each RSpec test will output an AppMap file into the directory `tmp/appmap/rspec`. For example:
 
 ```
 $ find tmp/appmap/rspec
@@ -143,6 +139,82 @@ If you include the `feature` and `feature_group` metadata, these attributes will
 
 If you don't explicitly declare `feature` and `feature_group`, then they will be inferred from the spec name and example descriptions.
 
+## Minitest
+
+To record Minitest tests, follow these additional steps:
+
+1) Require `appmap/minitest` in `test_helper.rb`
+
+```ruby
+require 'appmap/minitest'
+```
+
+Note that `test_helper.rb` in a Rails project typically loads the application's classes this way:
+
+```ruby
+require_relative '../config/environment'
+```
+
+and `appmap/rspec` must be required before this:
+
+```ruby
+require 'appmap/rspec'
+require_relative '../config/environment'
+```
+
+2) Run the tests with the environment variable `APPMAP=true`:
+
+```sh-session
+$ APPMAP=true bundle exec -Ilib -Itest test/*
+```
+
+Each Minitest test will output an AppMap file into the directory `tmp/appmap/minitest`. For example:
+
+```
+$ find tmp/appmap/minitest
+Hello_says_hello_when_prompted.appmap.json
+```
+
+## Cucumber
+
+To record Cucumber tests, follow these additional steps:
+
+1) Require `appmap/cucumber` in `support/env.rb`:
+
+```ruby
+require 'appmap/cucumber'
+```
+
+Be sure to require it before `config/environment` is required.
+
+2) Create an `Around` hook in `support/hooks.rb` to record the scenario:
+
+
+```ruby
+if AppMap::Cucumber.enabled?
+  Around('not @appmap-disable') do |scenario, block|
+    appmap = AppMap.record do
+      block.call
+    end
+
+    AppMap::Cucumber.write_scenario(scenario, appmap)
+  end
+end
+```
+
+3) Run the tests with the environment variable `APPMAP=true`:
+
+```sh-session
+$ APPMAP=true bundle exec cucumber
+```
+
+Each Cucumber test will output an AppMap file into the directory `tmp/appmap/cucumber`. For example:
+
+```
+$ find tmp/appmap/cucumber
+Hello_Says_hello_when_prompted.appmap.json
+```
+
 ## Remote recording
 
 To manually record ad-hoc AppMaps of your Ruby app, use AppMap remote recording.
@@ -183,5 +255,74 @@ Note that using this method is kind of a blunt instrument. Recording RSpecs and
 
 For instructions on uploading, see the documentation of the [AppLand CLI](https://github.com/applandinc/appland-cli).
 
+# Development
+
+## Running tests
+
+Before running tests, configure `local.appmap` to point to your local `appmap-ruby` directory.
+```
+$ bundle config local.appmap $(pwd)
+```
+
+Run the tests via `rake`:
+```
+$ bundle exec rake test
+```  
+
+## Using fixture apps
+
+### `test/fixtures`
+
+The fixture apps in `test/fixtures` are plain Ruby projects that exercise the basic functionality of the
+`appmap` gem. To develop in a fixture, simple enter the fixture directory and `bundle`.
+
+### `spec/fixtures`
+
+The fixture apps in `spec/fixtures` are simple Rack, Rails4, and Rails5 apps.
+You can use them to interactively develop and test the recording features of the `appmap` gem.
+These fixture apps are more sophisticated than `test/fixtures`, because they include additional 
+resources such as a PostgreSQL database.
+
+To build the fixture container images, first run:
+
+```sh-session
+$ bundle exec rake fixtures:all
+```
+
+This will build the `appmap.gem`, along with a Docker image for each fixture app.
+
+Then move to the directory of the fixture you want to use, and provision the environment.
+In this example, we use Ruby 2.6.
+
+```sh-session
+$ export RUBY_VERSION=2.6
+$ docker-compose up -d pg
+$ sleep 10s # Or some reasonable amount of time
+$ docker-compose run --rm app ./create_app
+```
+
+Now you can start a development container.
+
+```sh-session
+$ docker-compose run --rm -v $PWD/../../..:/src/appmap-ruby app bash
+Starting rails_users_app_pg_1 ... done
+root@6fab5f89125f:/app# cd /src/app
+root@6fab5f89125f:/src/app# bundle config local.appmap /src/appmap-ruby
+root@6fab5f89125f:/src/app# bundle update appmap
+```
+
+At this point, the bundle is built with the `appmap` gem located  in `/src/appmap`, which is volume-mounted from the host.
+So you can edit the fixture code and the appmap code and run test commands such as `rspec` and `cucumber` in the container.
+For example:
+
+```sh-session
+root@6fab5f89125f:/src/app# bundle exec rspec
+Configuring AppMap from path appmap.yml
+....
+
+Finished in 0.07357 seconds (files took 2.1 seconds to load)
+4 examples, 0 failures
+```
+
 # Build status
 [![Build Status](https://travis-ci.org/applandinc/appmap-ruby.svg?branch=master)](https://travis-ci.org/applandinc/appmap-ruby)

data/Rakefile

@@ -122,7 +122,7 @@ end
 Rake::TestTask.new(:minitest) do |t|
   t.libs << 'test'
   t.libs << 'lib'
-  t.test_files = FileList['test/**/*_test.rb']
+  t.test_files = FileList['test/*_test.rb']
 end
 
 task spec: "spec:all"

data/appmap.gemspec

@@ -26,6 +26,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'faraday'
   spec.add_dependency 'gli'
   spec.add_dependency 'parser'
+  spec.add_dependency 'rack'
 
   spec.add_development_dependency 'bundler', '~> 1.16'
   spec.add_development_dependency 'minitest', '~> 5.0'

data/exe/appmap

@@ -3,6 +3,8 @@
 
 require 'gli'
 
+ENV['APPMAP_INITIALIZE'] = 'false'
+
 require 'appmap'
 require 'appmap/version'
 
@@ -136,7 +138,7 @@ module AppMap
       protected
 
       def interpret_config_option(fname)
-        AppMap.configure fname
+        AppMap.initialize fname
       end
 
       def interpret_output_file_option(file_name)

data/lib/appmap.rb

@@ -8,55 +8,52 @@ rescue NameError
 end
 
 require 'appmap/version'
+require 'appmap/hook'
+require 'appmap/config'
+require 'appmap/trace'
+require 'appmap/class_map'
+require 'appmap/metadata'
+require 'appmap/util'
+require 'appmap/open'
 
 module AppMap
-  BATCH_HEADER_NAME = 'AppLand-Scenario-Batch'
-
   class << self
-    @config = nil
-    @config_file_path = nil
+    @configuration = nil
+    @configuration_file_path = nil
 
-    # configuration gets the AppMap configuration.
+    # Gets the configuration. If there is no configuration, the default
+    # configuration is initialized.
     def configuration
-      raise "AppMap is not configured" unless @config
-
-      @config
+      @configuration ||= initialize
     end
 
-    # configure applies the configuration from a file. This method can only be performed once.
-    # Be sure and call it before +hook+ if you want non-default configuration.
-    #
-    # Default behavior is to configure from "appmap.yml".
-    def configure(config_file_path = 'appmap.yml')
-      if @config
-        return @config if @config_file_path == config_file_path
-
-        raise "AppMap is already configured from #{@config_file_path}, can't reconfigure from #{config_file_path}"
-      end
+    # Sets the configuration. This is only expected to happen once per
+    # Ruby process.
+    def configuration=(config)
+      warn 'AppMap is already configured' if @configuration && config
 
-      warn "Configuring AppMap from path #{config_file_path}"
-      require 'appmap/hook'
-      AppMap::Hook::Config.load_from_file(config_file_path).tap do |config|
-        @config = config
-        @config_file_path = config_file_path
-      end
+      @configuration = config
     end
 
-    # Activate the code hooks which record function calls as trace events.
+    # Configures AppMap for recording. Default behavior is to configure from "appmap.yml".
+    # This method also activates the code hooks which record function calls as trace events.
     # Call this function before the program code is loaded by the Ruby VM, otherwise
     # the load events won't be seen and the hooks won't activate.
-    def hook(config = configure)
-      require 'appmap/hook'
-      AppMap::Hook.hook(config)
+    def initialize(config_file_path = 'appmap.yml')
+      warn "Configuring AppMap from path #{config_file_path}"
+      Config.load_from_file(config_file_path).tap do |configuration|
+        self.configuration = configuration
+        Hook.new(configuration).enable
+      end
     end
 
-    # Access the AppMap::Tracers, which can be used to start tracing, stop tracing, and record events.
+    # Used to start tracing, stop tracing, and record events.
     def tracing
-      require 'appmap/trace'
-      @tracing ||= Trace::Tracers.new
+      @tracing ||= Trace::Tracing.new
     end
 
-    # Record a block and return the array of events.
+    # Records the events which occur while processing a block,
+    # and returns an AppMap as a Hash.
     def record
       tracer = tracing.trace
       begin
@@ -65,17 +62,36 @@ module AppMap
         tracing.delete(tracer)
       end
 
-      [].tap do |events|
-        events << tracer.next_event.to_h while tracer.event?
+      events = [].tap do |event_list|
+        event_list << tracer.next_event.to_h while tracer.event?
       end
+      {
+        'version' => AppMap::APPMAP_FORMAT_VERSION,
+        'metadata' => detect_metadata,
+        'classMap' => class_map(tracer.event_methods),
+        'events' => events
+      }
+    end
+
+    # Uploads an AppMap to the AppLand website and displays it.
+    def open(appmap = nil, &block)
+      appmap ||= AppMap.record(&block)
+      AppMap::Open.new(appmap).perform
+    end
+
+    # Builds a class map from a config and a list of Ruby methods.
+    def class_map(methods)
+      ClassMap.build_from_methods(configuration, methods)
     end
 
-    # Build a class map from a config and a list of Ruby methods.
-    def class_map(config, methods)
-      require 'appmap/class_map'
-      AppMap::ClassMap.build_from_methods(config, methods)
+    # Returns default metadata detected from the Ruby system and from the
+    # filesystem.
+    def detect_metadata
+      @metadata ||= Metadata.detect.freeze
+      @metadata.deep_dup
     end
   end
 end
 
 require 'appmap/railtie' if defined?(::Rails::Railtie)
+AppMap.initialize unless ENV['APPMAP_INITIALIZE'] == 'false'