appmap 0.18.1 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 536929649e77a1a136aabc2ffbf8df4b43a1f51420334b4d556f5978aa205e06
-  data.tar.gz: b052fa2b3853f962932216a21f2c0d07052e7288695787bc60fccba4ed97cf1f
+  metadata.gz: dbd73ea1339788825987a09e80097ad54fcaf6297ae5a7bbe01aa39b5462a8bb
+  data.tar.gz: 6338cbb3203543ce4db169fef9cfcf31acfd6ea44da94220bca5c00638368520
 SHA512:
-  metadata.gz: fca12acdd2d3a096cc1ecb8bb8d5e19fb5f88ad91e67de83aa71d59e9cdaa0a70733d1904e4d29078ea94eddbc3005d1cb33ea4e86f0fad95270ec7b3bd35e67
-  data.tar.gz: 395891a44f2d185bcb5bd447bbe39d1d16a07c30c065c6fb7a45ea5979f54f7c1b30efab1baf6043838a9e9d166e1f14ff4412b9a04743d03c8a818a4c082b15
+  metadata.gz: 6d0b9d851b266a230a40ac85e9991d183919c67b1c09e155009ffb3cd2de660e40521e6253534ae6a3e06867238810d6f5def1c9b10f094f81ed2498e79ee4ea
+  data.tar.gz: 4a6f75650e36876086782f778eb1fbb90f7d15a9e35eb28f245ce942285b3cfd95c76c16e5d01a5c90867455668609e974a41dfd829a6e7a91487833ebee49c9

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+# v0.19.0
+
+* **RSpec** feature and feature group names can be inferred from example group and example names.
+* Stop using `ActiveSupport::Inflector.transliterate`, since it can cause exceptions.
+* Handle StandardError which occurs while calling `#inspect` of an object.
+
 # v0.18.1
 
 * Now tested with Rails 4, 5, and 6.

data/README.md

@@ -1,35 +1,54 @@
 - [About](#about)
 - [Installation](#installation)
 - [Configuration](#configuration)
-  - [`packages`](#packages)
 - [Running](#running)
   - [RSpec](#rspec)
-  - [Rails](#rails)
-- [Uploading](#uploading)
+  - [Remote recording](#remote-recording)
+- [Uploading AppMaps](#uploading-appmaps)
 - [Build status](#build-status)
 
 # About
 
-`appmap-ruby` is a Ruby client for recording and uploading [AppMap](https://github.com/applandinc/appmap) data.
-
+`appmap-ruby` is a Ruby Gem for recording and uploading
+[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, etc).
+(function calls and returns), and code metadata (repo name, repo URL, commit
+SHA, etc). It's more granular than a performance profile, but it's less
+granular than a full debug trace. It's designed to be optimal for understanding the design intent and behavior of code.
+
+There are several ways to record AppMaps of your Ruby program using the `appmap` gem:
 
-The normal usage of an AppMap client is to run a test case (such as an RSpec test) with AppMap instrumentation enabled.
-The AppMap client will observe and record information about the code execution, and store it in an AppMap file.
+* Run your RSpec tests. An AppMap will be generated for each one.
+* Run your application server with AppMap remote recording enabled, and use the AppMap
+  browser extension to start, stop, and upload recordings. 
 
-The command `appmap upload` is then used to upload the AppMap file to the App.Land server, which processes the file into
-useful displays such as graphical depiction of the code structure and execution.
+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
+visualize the design of your code and share links with collaborators.
 
 # Installation
 
-Add `gem 'appmap'` to your Gemfile just as you would any other dependency. You can place the gem in the `test` group.
+Add `gem 'appmap'` to your Gemfile just as you would any other dependency.
+
+**Global installation**
+
+```
+gem 'appmap'
+```
+
+**Install in test, development groups**
+
+```
+group :development, :test do
+  gem 'appmap'
+end
+```
 
 Then install with `bundle`. 
 
 # Configuration
 
-When you run the AppMap client, it will look for configuration settings in `appmap.yml`. Here's a sample configuration
+When you run your program, the `appmap` gem reads configuration settings from `appmap.yml`. Here's a sample configuration
 file for a typical Rails project:
 
 ```yaml
@@ -44,7 +63,7 @@ packages:
 * **files** A list of individual files which should be instrumented. This is only used for files which are
   not part of the `packages` list.
 
-## `packages`
+**packages**
 
 Each entry in the `packages` list is a YAML object which has the following keys:
 
@@ -61,71 +80,90 @@ Each entry in the `packages` list is a YAML object which has the following keys:
 
 To instrument RSpec tests, follow these steps:
 
-1) Include the `appmap` gem in your Gemfile
-2) Require `appmap/rspec` in your `spec_helper.rb` or `rails_helper.rb`
-3) Add `appmap: true` to the tests you want to instrument
-4) Add `feature: '<feature name>'` and `feature_group: '<feature group name>'` to your 
+1) Include the `appmap` gem in your Gemfile.
+2) Require `appmap/rspec` in your `spec_helper.rb`.
+3) Add `appmap: true` to the tests you want to instrument.
+4) Export the environment variable `APPMAP=true`.
+5) *Optional* Add `feature: '<feature name>'` and `feature_group: '<feature group name>'` annotations to your 
    examples. 
-5) Export the environment variable `APPMAP=true`
 
 Here's an example of an appmap-enabled RSpec test:
 
 ```ruby
-describe Hello, feature_group: 'Greeting' do
-  it 'says hello', feature: 'Print a greeting to the console', appmap: true do
-    expect(Hello.new.say_hello).to eq('Hello!')
+describe Hello, appmap: true do
+  describe 'says hello' do
+    it 'when prompted' do
+      expect(Hello.new.say_hello).to eq('Hello!')
+    end
   end
 end
 ```
 
-Then run the tests:
+Run the tests like this:
 
 ```sh-session
-$ APPMAP=true bundle exec rspec
+$ APPMAP=true bundle exec rspec -t appmap
 ```
 
 Each RSpec test will output a data file into the directory `tmp/appmap/rspec`. For example:
 
 ```
 $ find tmp/appmap/rspec
-Hello says hello.json
+Hello_says_hello_when_prompted.appmap.json
 ```
 
 If you include the `feature` and `feature_group` metadata, these attributes will be exported to the AppMap file in the
 `metadata` section. It will look something like this:
 
 ```json
-
+{
+  ...
+  "metadata": {
+    "name": "Hello app says hello when prompted",
+    "feature": "Hello app says hello",
+    "feature_group": "Hello"
+  },
+  ...
+}
 ```
 
-## Rails
+## Remote recording
 
-To capture ad-hoc AppMaps of your Rails app, use the AppMap Railtie.
+To manually record ad-hoc AppMaps of your Ruby app, use AppMap remote recording.
 
-1) Include the `appmap` gem in your Gemfile and require both `appmap` and `appmap/railtie`, like this:
+1. Add the AppMap remote recording middleware. For example, in `config/initializers/appmap_remote_recording.rb`:
 
 ```ruby
-gem "appmap", require: %w[appmap appmap/railtie]
+require 'appmap/middleware/remote_recording'
+
+unless Rails.env.test?
+  Rails.application.config.middleware.insert_after \
+    Rails::Rack::Logger,
+    AppMap::Middleware::RemoteRecording
+end
 ```
 
-2) Export `APPMAP=true` when you start your Rails application server. For example:
+2. Start your Rails application server. For example:
 
 ```sh-session
-$ APPMAP=true bundle exec rails server
+$ bundle exec rails server
 ```
 
-When the Rails app exits, an `appmap.json` file will be written to the project root directory. You can upload it using
-the `appmap upload` command.
+3. Open the AppApp browser extension and push `Start`.
+
+4. Use your app. For example, perform a login flow, or run through a manual UI test.
+
+5. Open the AppApp browser extension and push `Stop`. The recording will be transferred to the AppLand website and opened in your browser.
 
-# Uploading
+# Uploading AppMaps
 
-To upload an AppMap file to App.Land, run the `appmap upload` command. For example:
+To upload an AppMap file to AppLand, run the `appmap upload` command. For example:
 
 ```sh-session
-$ appmap upload tmp/appmap/rspec/Hello says hello.json
-Full classMap contains 1 classes
-Pruned classMap contains 1 classes
-Uploaded new scenario: d49f3d16-e9f2-4775-a731-6cb95193927e
+$ appmap upload tmp/appmap/rspec/Hello_app_says_hello_when_prompted.appmap.json
+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
 ```
 
 # Build status

data/lib/appmap/rspec.rb

@@ -29,14 +29,14 @@ module AppMap
         FileUtils.mkdir_p APPMAP_OUTPUT_DIR
       end
 
-      # TODO: Optionally populate the 'layout' from appmap config or RSpec metadata.
-      def save(example_name, events, feature_name: nil, feature_group_name: nil)
+      def save(example_name, events, feature_name: nil, feature_group_name: nil, labels: nil)
         require 'appmap/command/record'
         metadata = AppMap::Command::Record.detect_metadata.tap do |m|
           m[:name] = example_name
           m[:app] = @config.name
           m[:feature] = feature_name if feature_name
           m[:feature_group] = feature_group_name if feature_group_name
+          m[:labels] = labels if labels
           m[:frameworks] ||= []
           m[:frameworks] << {
             name: 'rspec',
@@ -58,7 +58,7 @@ module AppMap
       # https://github.com/rails/rails/blob/v5.2.4/activesupport/lib/active_support/inflector/transliterate.rb#L92
       def sanitize_filename(fname, separator: '_')
         # Replace accented chars with their ASCII equivalents.
-        fname = ActiveSupport::Inflector.transliterate(fname)
+        fname = fname.encode('utf-8', invalid: :replace, undef: :replace, replace: '_')
 
         # Turn unwanted chars into the separator.
         fname.gsub!(/[^a-z0-9\-_]+/i, separator)
@@ -83,6 +83,17 @@ module AppMap
           annotations[:feature]
         end
 
+        def labels
+          labels = metadata[:appmap]
+          if labels.is_a?(Array)
+            labels
+          elsif labels.is_a?(String) || labels.is_a?(Symbol)
+            [ labels ]
+          else
+            []
+          end
+        end
+
         def feature_group
           return nil unless annotations
 
@@ -119,6 +130,10 @@ module AppMap
 
         alias_method :example_obj, :example
 
+        def description?
+          true
+        end
+
         def description
           example.description
         end
@@ -255,28 +270,46 @@ module AppMap
 
               example = examples[loc]
               description = []
-              scope = ScopeExample.new(example)
+              leaf = scope = ScopeExample.new(example)
               feature_group = feature = nil
+              labels = scope.labels.map(&:to_s).map(&:strip).reject(&:blank?).map(&:downcase).uniq
+
               while scope
                 description << scope.description
                 feature ||= scope.feature
                 feature_group ||= scope.feature_group
                 scope = scope.parent
               end
-              description.reject! { |d| d.nil? || d == '' }
+              description.reject!(&:nil?).reject(&:blank?)
+              default_description = description.last
               description.reverse!
 
-              description.each do |token|
-                token = token.gsub 'it should behave like', ''
-                token.gsub! '  ', ' '
-                token.gsub! '/', '_'
-                token.strip!
+              normalize = lambda do |desc|
+                desc.gsub('it should behave like', '')
+                    .gsub(/Controller$/, '')
+                    .gsub(/\s+/, ' ')
+                    .strip
+              end
+
+              full_description = normalize.call(description.join(' '))
+
+              compute_feature_name = lambda do
+                return 'unknown' if description.empty?
+
+                feature_description = description.dup
+                num_tokens = [2, feature_description.length - 1].min
+                feature_description[0...num_tokens].map(&:strip).join(' ')
               end
-              full_description = description.join(' ')
 
-              recorder.save full_description, events,
-                            feature_name: feature,
-                            feature_group_name: feature_group
+              feature_group ||= normalize.call(default_description).underscore.gsub('/', '_').humanize
+              feature_name = feature || compute_feature_name.call if feature_group
+              feature_name = normalize.call(feature_name) if feature_name
+
+              recorder.save full_description,
+                            events,
+                            feature_name: feature_name,
+                            feature_group_name: feature_group,
+                            labels: labels.blank? ? nil : labels
             end
           end
         end

data/lib/appmap/trace/tracer.rb

@@ -87,15 +87,24 @@ module AppMap
         def display_string(value)
           return nil unless value
 
-          begin
-            value_string = value.to_s
-          rescue NoMethodError
-            value_string = value.inspect
-          rescue StandardError
-            warn $!.message
+          last_resort_string = lambda do
+            warn "AppMap encountered an error inspecting a #{value.class.name}: #{$!.message}"
             '*Error inspecting variable*'
           end
 
+          value_string = \
+            begin
+              value.to_s
+            rescue NoMethodError
+              begin
+                value.inspect
+              rescue StandardError
+                last_resort_string.call
+              end
+            rescue StandardError
+              last_resort_string.call
+            end
+
           value_string[0...LIMIT].encode('utf-8', invalid: :replace, undef: :replace, replace: '_')
         end
       end

data/lib/appmap/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AppMap
-  VERSION = '0.18.1'
+  VERSION = '0.19.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appmap
 version: !ruby/object:Gem::Version
-  version: 0.18.1
+  version: 0.19.0
 platform: ruby
 authors:
 - Kevin Gilpin