appmap 0.27.0 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd23faab460498cfac79b397c4fc87920df8d1a984142909542f524057d1e4cb
-  data.tar.gz: a967224c65d6a479287768389feb73a378e6e1be133f1033d06be6034a43b18e
+  metadata.gz: d94a20303fe329af9dfa6f4a0d4b14666a7eb25cba58d0ea6ede64b5991e85f9
+  data.tar.gz: c441d6ee26453338fa449fed7762a0768155eaa934168c2245c47a5deb78cb38
 SHA512:
-  metadata.gz: 7822e4c821cb5e57579163fdd080bc3b74fb5ad0c8999bc6e3d29ace636301d8ed931966abfe9a59a6a59603f83af03e82130c241293ee198173ef6f6f41ebd1
-  data.tar.gz: 8ba03667929d4571e13439ab53420934e0b1c9ee4605dfd71e9a7ff82b984d34e37ca43e206cbf5dc750201df93dc8dc9babbdafbadf12a86051e52efc6ef985
+  metadata.gz: a66524169eeb5e8d78974a8ac37122f52d5e2285cb4ff6f88f58947e8016d2b4ac458430df07a5b4e9c5ab37fdc7122bb887c694e375a7013bc8f34bf1b6b6b2
+  data.tar.gz: 665354eca628d2d0f68706cf297667b9b3392a43e6dc364923f1f45f5316a6d3db54dea2d1e75ae83cd53c3ed9cb40ecc3794c10c9d6ee1c310aeed6710bb931

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,12 @@
+# 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,23 @@
 - [About](#about)
-- [Testing](#testing)
 - [Installation](#installation)
 - [Configuration](#configuration)
 - [Running](#running)
   - [RSpec](#rspec)
+  - [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 +27,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 +36,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 +54,7 @@ group :development, :test do
 end
 ```
 
-Then install with `bundle`. 
+Then install with `bundle`.
 
 # Configuration
 
@@ -90,7 +84,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 +92,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 +125,44 @@ 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.
 
+## 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 +203,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/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

@@ -10,53 +10,43 @@ end
 require 'appmap/version'
 
 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
+    # 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
 
-        raise "AppMap is already configured from #{@config_file_path}, can't reconfigure from #{config_file_path}"
-      end
-
-      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)
+    def initialize(config_file_path = 'appmap.yml')
+      warn "Configuring AppMap from path #{config_file_path}"
       require 'appmap/hook'
-      AppMap::Hook.hook(config)
+      self.configuration = Hook::Config.load_from_file(config_file_path)
+      Hook.hook(configuration)
     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 a block and return the array of events.
+    # record records the events which occur while processing a block,
+    # and returns an AppMap as a Hash.
     def record
       tracer = tracing.trace
       begin
@@ -65,17 +55,32 @@ 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
 
-    # Build a class map from a config and a list of Ruby methods.
-    def class_map(config, methods)
+    # class_map builds a class map from a config and a list of Ruby methods.
+    def class_map(methods)
       require 'appmap/class_map'
-      AppMap::ClassMap.build_from_methods(config, methods)
+      ClassMap.build_from_methods(configuration, methods)
+    end
+
+    # detect_metadata returns default metadata detected from the Ruby system and from the
+    # filesystem.
+    def detect_metadata
+      require 'appmap/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'

data/lib/appmap/command/record.rb

@@ -5,66 +5,7 @@ module AppMap
     RecordStruct = Struct.new(:config, :program)
 
     class Record < RecordStruct
-      class << self
-        # Builds a Hash of metadata which can be detected by inspecting the system.
-        def detect_metadata
-          {
-            language: {
-              name: 'ruby',
-              engine: RUBY_ENGINE,
-              version: RUBY_VERSION
-            },
-            client: {
-              name: 'appmap',
-              url: AppMap::URL,
-              version: AppMap::VERSION
-            }
-          }.tap do |m|
-            if defined?(::Rails)
-              m[:frameworks] ||= []
-              m[:frameworks] << {
-                name: 'rails',
-                version: ::Rails.version
-              }
-            end
-            m[:git] = git_metadata if git_available
-          end
-        end
-
-        protected
-
-        def git_available
-          @git_available = system('git status 2>&1 > /dev/null') if @git_available.nil?
-        end
-
-        def git_metadata
-          git_repo = `git config --get remote.origin.url`.strip
-          git_branch = `git rev-parse --abbrev-ref HEAD`.strip
-          git_sha = `git rev-parse HEAD`.strip
-          git_status = `git status -s`.split("\n").map(&:strip)
-          git_last_annotated_tag = `git describe --abbrev=0 2>/dev/null`.strip
-          git_last_annotated_tag = nil if git_last_annotated_tag.blank?
-          git_last_tag = `git describe --abbrev=0 --tags 2>/dev/null`.strip
-          git_last_tag = nil if git_last_tag.blank?
-          git_commits_since_last_annotated_tag = `git describe`.strip =~ /-(\d+)-(\w+)$/[1] rescue 0 if git_last_annotated_tag
-          git_commits_since_last_tag = `git describe --tags`.strip =~ /-(\d+)-(\w+)$/[1] rescue 0 if git_last_tag
-
-          {
-            repository: git_repo,
-            branch: git_branch,
-            commit: git_sha,
-            status: git_status,
-            git_last_annotated_tag: git_last_annotated_tag,
-            git_last_tag: git_last_tag,
-            git_commits_since_last_annotated_tag: git_commits_since_last_annotated_tag,
-            git_commits_since_last_tag: git_commits_since_last_tag
-          }
-        end
-      end
-
       def perform(&block)
-        AppMap::Hook.hook(config)
-
         tracer = AppMap.tracing.trace
 
         events = []
@@ -85,8 +26,8 @@ module AppMap
           quit = true
           event_thread.join
           yield AppMap::APPMAP_FORMAT_VERSION,
-                self.class.detect_metadata,
-                AppMap.class_map(config, tracer.event_methods),
+                AppMap.detect_metadata,
+                AppMap.class_map(tracer.event_methods),
                 events
         end