appmap 0.26.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75d21c5ea95115ab89fb0dd6674a601d19455473f787344d07f7a935aec58aec
-  data.tar.gz: 9d76905534e5c3277c318376708224f318f6357ab41647a6a14a82edf63cbe54
+  metadata.gz: 54b9a05aeb3eea84572b115a6de1106e6743b74046048e3c168f99a75aa9e669
+  data.tar.gz: eb8a690376d833c4bec9f0789c5499f413f7dcb3b1ef111257785bd344861f64
 SHA512:
-  metadata.gz: c6ca34edd66c0cec51119cc2af49ea5824c91023e54ac1507493eebc3ef39d8308db2b013fdd83d9a1102fc3f6f791dbcec5cf7c75a0cda409d4ade695739815
-  data.tar.gz: 3e5ff519cc8ce4964771806f20258590b607a48a497bb4f100a72ce31f0b40305542315ac3ecfdf1ec5b92723c30369041707327fdf2bf0ac35a5f526e77a969
+  metadata.gz: 453f06041220ecd0a4fc563ae007e7f8247d3dfcccf49657cbf47ddc53d0175e6834d1dbd89a2338a032d6cfae866929216b58a11bb6f0fe3fd2ea69508d7b2a
+  data.tar.gz: 77f372ad255c3c664c690affa2962958cebd1e8f34579809e4d975fdf57404889d8506f9153d44a95afda297ffe7b1654529252a5293487477e803bdf0cc9608

data/.gitignore

@@ -1,7 +1,6 @@
 .DS_Store
 /html/
-/.appmap/
-/.bundle/
+.bundle
 /.yardoc
 /_yardoc/
 /coverage/

data/CHANGELOG.md

@@ -1,3 +1,41 @@
+# 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.
+
+# v0.26.1
+
+* Fix a bug that caused duplicate entries in the list of frameworks that appear
+  in the `metadata` section of an appmap.
+  
 # v0.26.0
 
 * **appmap upload** is removed. Upload functionality has been moved to

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,7 +28,7 @@ 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
@@ -31,17 +37,6 @@ by the [AppLand CLI](https://github.com/applandinc/appland-cli/releases), to
 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,7 +85,7 @@ 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`.
 
@@ -98,28 +93,16 @@ To instrument RSpec tests, follow these additional steps:
 require 'appmap/rspec'
 ```
 
-2) Add `appmap: true` to the tests you want to instrument.
-
-```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
-```
-
-3) *Optional* Add `feature: '<feature name>'` and `feature_group: '<feature group name>'` annotations to your 
+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 +126,67 @@ 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'
+```
+
+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'
+```
+
+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 +227,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/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,60 +8,80 @@ rescue NameError
 end
 
 require 'appmap/version'
+require 'appmap/hook'
+require 'appmap/config'
+require 'appmap/trace'
+require 'appmap/class_map'
+require 'appmap/metadata'
 
 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.
+    # 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 ||= configure
     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
+    # configuration= 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.
+    # initialize 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}"
+      self.configuration = Config.load_from_file(config_file_path)
+      Hook.new(configuration).enable
     end
 
-    # Access the AppMap::Tracers, which can be used to start tracing, stop tracing, and record events.
+    # tracing can be used to start tracing, stop tracing, and record events.
     def tracing
-      require 'appmap/trace'
-      @tracing ||= Trace::Tracers.new
+      @tracing ||= Trace::Tracing.new
+    end
+
+    # record records the events which occur while processing a block,
+    # and returns an AppMap as a Hash.
+    def record
+      tracer = tracing.trace
+      begin
+        yield
+      ensure
+        tracing.delete(tracer)
+      end
+
+      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
+
+    # class_map 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)
+    # detect_metadata 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'