appmap 0.25.2 → 0.28.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ee5199f1f1f4c05ba3837f3caf04adb9798bb223c3bf0deb71cdd80216181a0
-  data.tar.gz: 3aeb05be87430862426a25075a236d54d2d20bb0a1d893b71b1eaa63c8c44c01
+  metadata.gz: 8619a5924ba51ee48d76ebfe5c72030629c5338217b4fe659cd0a580eaa6ddb9
+  data.tar.gz: 0d8b1e8fcd41e0785b362350a53c95c5bc0ba5c628371b7b6216315b7ddcd85e
 SHA512:
-  metadata.gz: fc4042fe8d7f56a87b205145fcd9e520beb946d27f1e17f5134f4a5127f7ca9c2ee8645cf8377339c34cf814b4faf348894d91f20d31a68e743ede3d5d863419
-  data.tar.gz: 3c4dba46e95a77b51030065af14e9987f66294ba396a38ef396b79d86b37540d36229670b170e4f632972b563369184d0fa1a4e5b4c18d99d1deb5243b166014
+  metadata.gz: c4da2cadb6a852b1213d1938b035ca147a939e7dc1378ef435d1e8b4d42d6f5b98e19191ecd2e1d1e48493817117123e0b9167080308dcc9ea5527bb676f436b
+  data.tar.gz: 04c2a36c913a3eec42dcd8aa61e789b9b91fed1e43b4bfe84729c6a7b4451fb1064c6efdba39e3818674df8f9560caa486e1d4c8170f04682938775fbb2c4d7e

data/.gitignore

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

data/CHANGELOG.md

@@ -1,3 +1,33 @@
+# 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
+  the [AppLand CLI](https://github.com/applandinc/appland-cli).
+
 # v0.25.2
 
 * Stop checking a whitelist to see if each SQL query should be recorded. Record

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 and uploading
-[AppMaps](https://github.com/applandinc/appmap) of your code. 
+`appmap-ruby` is a Ruby Gem for recording
+[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,24 +27,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.
 
-When you record AppMaps on the command line (for example, by running RSpec tests), you use the `appmap upload` command to
-upload them to the AppLand website. On the AppLand website, you'll be able to
+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
+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.
@@ -58,7 +54,7 @@ group :development, :test do
 end
 ```
 
-Then install with `bundle`. 
+Then install with `bundle`.
 
 # Configuration
 
@@ -88,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`.
 
@@ -96,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
@@ -141,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.
@@ -179,13 +201,75 @@ Note that using this method is kind of a blunt instrument. Recording RSpecs and
 
 # Uploading AppMaps
 
-To upload an AppMap file to AppLand, run the `appmap upload` command. For example (with binstubs installed):
+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
-$ ./bin/appmap upload tmp/appmap/rspec/*
-Uploading "tmp/appmap/rspec/Hello_app_says_hello_when_prompted.appmap.json"
-Scenario Id: 4da4f267-bdea-48e8-bf67-f39463844230
-Batch Id: a116f1df-ee57-4bde-8eef-851af0f3d7bc
+$ 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

data/exe/appmap

@@ -3,6 +3,8 @@
 
 require 'gli'
 
+ENV['APPMAP_INITIALIZE'] = 'false'
+
 require 'appmap'
 require 'appmap/version'
 
@@ -125,62 +127,6 @@ module AppMap
       end
     end
 
-    desc 'Upload a scenario file to AppLand.'
-    arg_name 'filename'
-    command :upload do |c|
-      output_file_flag(c, default_value: '-')
-
-      c.desc 'Whether to open the new scenario in the browser'
-      c.default_value true
-      c.switch [:open]
-
-      c.desc 'AppLand website URL'
-      c.default_value ENV['APPLAND_URL'] || 'https://appland-staging.herokuapp.com'
-      c.flag :url
-
-      # TODO: This will be replaced with proper login
-      c.desc 'User id to own the scenario'
-      c.default_value(ENV['APPLAND_USER'])
-      c.flag :user
-
-      c.desc 'Organization id to own the scenario'
-      c.default_value(ENV['APPLAND_ORG'])
-      c.flag :org
-
-      c.action do |_, options, args|
-        require 'appmap/command/upload'
-
-        filenames = args
-        help_now!("'filename' argument is required") if filenames.empty?
-
-        url = options[:url]
-        user = options[:user]
-        org = options[:org]
-
-        batch_id = nil
-        uuids = filenames.map do |filename|
-          appmap = JSON.parse(File.read(filename))
-
-          warn "Uploading #{filename.inspect}"
-          upload = AppMap::Command::Upload.new(appmap, url, user, org)
-          upload.batch_id = batch_id if batch_id
-          upload.perform.tap do |response|
-            batch_id ||= response.batch_id
-            @output_file.puts "Scenario Id: #{response.scenario_uuid}"
-          end.scenario_uuid
-        end
-        @output_file.puts "Batch Id: #{batch_id}"
-
-        if options[:open] && STDIN.tty?
-          if uuids.length == 1
-            system "open #{url}/scenarios/#{uuids.first}"
-          else
-            system "open #{url}/scenario_batches/#{batch_id}"
-          end
-        end
-      end
-    end
-
     pre do |global, _, options, _|
       @config = interpret_config_option(global[:config])
       @output_file = interpret_output_file_option(options[:output])
@@ -192,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,58 +10,77 @@ 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
-
-        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)
+    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
 
-    # Build a class map from a config and a list of Ruby methods.
-    def class_map(config, methods)
+    # 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)
       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'