capybara_spa 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19ed7589902a6d0325189f481b625b7b51c76f69e1db77007908d782ec8f8284
-  data.tar.gz: 5e3812be9fffb593695a0c29b3aa989a9d0930410883bb8040f062a308b41b64
+  metadata.gz: ee0028ff6473dfd7ee60d23ed3ca3f3a07e1412fa11beed4faf28a7da1e110b1
+  data.tar.gz: faa416fd1f5adb9cf61be4b465351c67771229f9bbb393fea143d46a39214fe2
 SHA512:
-  metadata.gz: 8dfff66e5fd86435ff0daa5f1786d537fb581c55d588923b7d373811d0fa4426567072134d8ad82c621fc5f514ae9b3e8e61fd86f55348b05784f665a7f2c45e
-  data.tar.gz: 9c2b0307ddb544cb7745cc9922ea7ec78a435f1cc4cc9c74bd1a34e480a9faad08ac7561a6d46cf6f608c8e2ac73801e6f04dc082b7e10d408bc100196352d2e
+  metadata.gz: b0a7cf1c8f639162f80e6040c8f3d20766aa80e8aec827002e53561ea87bed3ace6d3141f05b6741de842d5fdc952bd12a12b0c5af14181fd53293c8f74ac0ff
+  data.tar.gz: 6e810df6910e92e214a76a93242b4e62b331a26ca3dd7a35f2af002c719d04f938ac1d7d92d5b5a9ec115236eaa5aade1afd818fd30448b0930969689b154d3a

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    capybara_spa (0.3.0)
+    capybara_spa (0.4.0)
       capybara (~> 3.0)
 
 GEM
@@ -13,7 +13,7 @@ GEM
       io-like (~> 0.3.0)
     bump (0.6.0)
     byebug (10.0.2)
-    capybara (3.0.3)
+    capybara (3.1.0)
       addressable
       mini_mime (>= 0.1.3)
       nokogiri (~> 1.8)

data/README.md

@@ -1,15 +1,32 @@
 # CapybaraSpa
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/capybara_spa`. To experiment with that code, run `bin/console` for an interactive prompt.
+![https://travis-ci.org/mhs/capybara_spa.svg?branch=master](https://travis-ci.org/mhs/capybara_spa.svg?branch=master)
 
-TODO: Delete this and the text above, and describe your gem
+CapybaraSpa is a library to ease testing single page applications with Capybara.
+
+Often, when developing an API server and a front-end client separately it can be a real pain to set up an integration testing environment.
+
+## How does it work?
+
+CapybaraSpa either runs (and terminates) an external processes for the front-end application, or, it will connect to an externally running process on a specified port. When the test suite boots up it will spawn a child process that server your front-end application.
+
+It also updates Capybara's `visit` method to wait for the application to boot up before running the tests.. Then, when the test suite is done it will terminate any child processes.
+
+Currently, you can:
+
+* Run an inline static Angular 2, 4, 5, or 6 application using the `CapybaraSpa::Server::NgStaticServer`
+* Connect to an external process running on a specified port using the `CapybaraSpa::Server::ExternalServer`
+
+Coming soon you'll be able to:
+
+* Run an inline external process by providing the command to start
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add this line to the `test` group of application's Gemfile:
 
 ```ruby
-gem 'capybara_spa'
+gem 'capybara_spa', group :test
 ```
 
 And then execute:
@@ -22,7 +39,130 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+You can use this with any Ruby testing library that Capybara works with.
+
+### Require it in your test_helper, spec_helper, rails_helper, etc.
+
+Here's a sample of using this library on a Rails project. Just update the `rails_helper.rb` after you Capybara is loaded. Then, create the server:
+
+```ruby
+require 'capybara/rails'
+require 'capybara_spa'
+
+FrontendServer = CapybaraSpa::Server::NgStaticServer.new(
+  build_path: File.dirname(__FILE__) + '/../../public/app',
+  http_server_bin_path: File.dirname(__FILE__) + '/../../node_modules/.bin/angular-http-server',
+  log_file: File.dirname(__FILE__) + '/../../log/angular-process.log',
+  pid_file: File.dirname(__FILE__) + '/../../tmp/angular-process.pid'
+)
+```
+
+### Configure your test library to start and stop the server
+
+Since we're using RSpec in this README, the next thing to do is configure RSpec to start and stop the server:
+
+```ruby
+RSpec.configure do |config|
+  config.before(:each) do |example|
+    if self.class.metadata[:js]
+      begin
+        FrontendServer.start unless FrontendServer.started?
+      rescue CapybaraSpa::Server::Error => ex
+        # Server raised an exception when starting. Force exit
+        # so developer see the error immediately. Otherwise, RSpec/Capybara
+        # are hanging around waiting for Puma to boot up.
+        STDERR.puts ex.message, ex.backtrace.join("\n")
+        exit!
+      end
+    end
+  end
+
+  config.after(:suite) do
+    FrontendServer.stop if FrontendServer.started?
+  end
+end
+```
+
+### Starting and Stopping
+
+Above, we added a `before(:each)` block to conditionally start the server. Since starting the server can be an expensive operation we only want to do it when we are running javascript specs (e.g. `:js`) and we only want to incur the cost once. So we essentially start it on the very first test that uses javascript and then we leave it running throughout of the test suite.
+
+After that, an `after(:suite)` block is added to ensure that we stop the server. Technically, this is not necessary as  `CapybaraSpa` will install `at_exit` handlers to ensure that any child processes are terminated (to ensure no zombie processes creep up).
+
+### Connecting to an external server
+
+Let's say that you don't want to incur the startup cost of booting up the frontend server on every single test run. You can keep a frontend server running in a separate terminal tab and tell the test suite what port to connect to. For example, the above `CapybaraSpa::Server::NgStaticServer` could be replaced with the below lines:
+
+```ruby
+FrontendServer = CapybaraSpa::Server::ExternalServer.new(
+  port: 5001 # port is the port that your front-end application server is running on
+)
+```
+
+If you use the `CapybaraSpa::Server::ExternalServer` you will want to leave the `start` and `stop` configuration for your test library in place. This is so that you are notified of a failure if the external process/server is not running, not listening on the correct port, or does not stop.
+
+By default, `CapybaraSpa::Server::ExternalServer` will wait up to 1 minute to attempt to connect to the port and it will wait up to 1 second for it to be stopped. You can change these values by passing in the `start_timeout` and `stop_timeout` options to the constructor.
+
+### Why use a global constant?
+
+The above example uses a global constant because it makes it accessible anywhere (e.g. say we're debugging a test and want to inspect the front-end server process) and because it essentially makes our server instance a singleton.
+
+You can use a dollar-sign global (e.g. `$frontend_server`) or even a local variable (`frontend_server`). You can also name it whatever you like. Your call. Have fun.
+
+### Configure Capybara
+
+Here's a sample configuration of Capybara. It sets the `app_host` to be the front-end application that the browser will hit, and then it sets the back-end server to run on port 3001.
+
+```ruby
+Capybara.app_host = "http://localhost:#{FrontendServer.port}"
+```
+
+Next, be sure to tell Capybara to hit the backend server process on the right port, e.g.
+
+```ruby
+Capybara.server_port = 3001
+```
+
+This will require that your front-end application is also configured to connect to the backend on the same port.
+
+
+### Configure the front-end app
+
+For Angular 5 and 6 make a new environment (e.g. `ANGULAR_APP/src/environments/environment.integration.ts`) based off from an existing environment (either dev or production) but with the necessary API url configured to look for the API server on port 3001.
+
+```javascript
+export const environment = {
+  production: false,
+  apiUrl: 'http://localhost:3001'
+};
+```
+
+Angular 6 requires one more change to. This time, a change to the `angular.json` configuration file. Be sure to add an integration `configuration`, e.g.:
+
+```javascript
+    "configurations": {
+        "integration": {
+            "fileReplacements": [
+            {
+                "replace": "src/environments/environment.ts",
+                "with": "src/environments/environment.integration.ts"
+            }
+            ],
+            "optimization": true,
+            "outputHashing": "all",
+            "sourceMap": false,
+            "extractCss": true,
+            "namedChunks": false,
+            "aot": true,
+            "extractLicenses": true,
+            "vendorChunk": false,
+            "buildOptimizer": true
+        },
+        // ....
+    }
+```
+
+Now, you should be ready to go.
 
 ## Development
 
@@ -32,7 +172,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/zdennis/capybara_spa.
+Bug reports and pull requests are welcome on GitHub at https://github.com/mhs/capybara_spa.
 
 ## License
 

data/Rakefile

@@ -3,4 +3,30 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task :default => :spec
+
+namespace :version do
+  desc "Show the current gem version"
+  task :show do
+    system <<-SHELL
+      bump current
+    SHELL
+  end
+
+  namespace :bump do
+    desc "Bump the gem one major version"
+    task :major do
+      system "bump major"
+    end
+
+    desc "Bump the gem one minor version"
+    task :minor do
+      system "bump minor"
+    end
+
+    desc "Bump the gem one patch version"
+    task :patch do
+      system "bump patch"
+    end
+  end
+end

data/lib/capybara_spa.rb

@@ -1,18 +1,19 @@
-require File.join(File.dirname(__FILE__), 'capybara_spa/capybara_dsl_ext')
-require File.join(File.dirname(__FILE__), 'capybara_spa/server/ng_static_server')
-
 module CapybaraSpa
   class << self
-    #  * NG_APP_TAG: the HTML tag where the angular app is stored. Defaults to app-root.
+    # +app_tag+ is the HTML tag where the single page application is stored. Defaults to app-root. \
+    #   This can be set thru the SPA_APP_TAG environment variable.
     attr_accessor :app_tag
 
-    #  * NG_LOG_FILE: where to log the output of angular-http-server. Defaults to /dev/null
+    # +log_file+ where to log the output of angular-http-server. Defaults to /dev/null \
+    #   This can be set thru the SPA_LOG_FILE environment variable.
     attr_accessor :log_file
   end
 
-  self.app_tag = ENV.fetch('NG_APP_TAG', 'app-root')
-  self.log_file = ENV.fetch('NG_LOG_FILE', STDOUT)
+  self.app_tag = ENV.fetch('SPA_APP_TAG', 'app-root')
+  self.log_file = ENV.fetch('SPA_LOG_FILE', STDOUT)
+end
 
-  module Server
-  end
-end
+require File.join(File.dirname(__FILE__), 'capybara_spa/capybara_dsl_ext')
+require File.join(File.dirname(__FILE__), 'capybara_spa/server')
+require File.join(File.dirname(__FILE__), 'capybara_spa/server/external_server')
+require File.join(File.dirname(__FILE__), 'capybara_spa/server/ng_static_server')

data/lib/capybara_spa/server.rb

@@ -0,0 +1,5 @@
+module CapybaraSpa
+  module Server
+    class Error < ::StandardError ; end
+  end
+end

data/lib/capybara_spa/server/external_server.rb

@@ -0,0 +1,102 @@
+require 'socket'
+require 'timeout'
+
+module CapybaraSpa
+  module Server
+    class ExternalServerNotFoundOnPort < Error ; end
+    class ExternalServerStillRunning < Error ; end
+
+    # CapybaraSpa::Server::ExternalServer is a class that wraps a server running as
+    # as an external process. For example, let's say you wanted to always have an
+    # a version of your single-page-application up and running for integration tests.
+    # You would start this in a different terminal or shell like this:
+    #
+    #     ng serve --port 5001
+    #
+    # Then you would configure your CapybaraSpa server in your test helper (e.g. \
+    # spec_helper.rb, rails_helper.rb, etc):
+    #
+    #   server = CapybaraSpa::Server::ExternalServer.new(
+    #     port: 5001
+    #   )
+    #
+    class ExternalServer
+      # +host+ is a string of the host or ip address to connect to
+      attr_accessor :host
+
+      # +port+ is port number that the external process is running on
+      attr_accessor :port
+
+      # +start_timeout+ is the number of seconds to wait for the external process
+      # to begin listening on +port+. Applies to #start and #started?
+      attr_accessor :start_timeout
+
+      # +stop_timeout+ is the number of seconds to wait when determining the external
+      # process is no longer running. Applies to #stop and #stopped?
+      attr_accessor :stop_timeout
+
+      def initialize(host: 'localhost', port: 5001, start_timeout: 60, stop_timeout: 1)
+        @host = host
+        @port = port
+        @start_timeout = start_timeout
+        @stop_timeout = stop_timeout
+      end
+
+      # +start+ is a no-op, but it will wait up to the +start_timeout+ for the external
+      # process to start listening on the specified +port+ before giving up and raising
+      # an ExternalServerNotFoundOnPort error.
+      def start
+        unless is_port_open?(timeout: start_timeout)
+          raise ExternalServerNotFoundOnPort, <<-ERROR.gsub(/^\s*\|/, '')
+            |Tried for #{start_timeout} seconds but nothing was listening
+            |on port #{port}. Please make sure the external process is running
+            |successfully and that the port is correct.
+          ERROR
+        end
+      end
+
+      # Returns true if the an external process is running on the +host+ and +port+.
+      # Otherwise, returns false.
+      def started?
+        is_port_open?(timeout: start_timeout)
+      end
+
+      # +stop+ is a no-op, but it will wait up to the +stop_timeout+ for the external
+      # process to stop listening on the specified +port+ before giving up
+      # and raising an ExternalServerStillRunning error.
+      def stop
+        unless !is_port_open?(timeout: stop_timeout)
+          raise ExternalServerStillRunning, <<-ERROR.gsub(/^\s*\|/, '')
+            |I tried for #{stop_timeout} seconds to verify that the
+            |external process listening on #{port} had stopped listening,
+            |but it hasn't. You may have a zombie process
+            |or may need to increase the stop_timeout.
+          ERROR
+        end
+      end
+
+      # Returns true if the an external process is not running on the +host+ and +port+.
+      # Otherwise, returns true.
+      def stopped?
+        !is_port_open?(timeout: stop_timeout)
+      end
+
+      private
+
+      def is_port_open?(timeout: 10)
+        Timeout.timeout(timeout) do
+          begin
+            s = TCPSocket.new(host, port)
+            s.close
+            return true
+          rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
+            sleep 1
+            retry
+          end
+        end
+      rescue Timeout::Error
+        return false
+      end
+    end
+  end
+end

data/lib/capybara_spa/version.rb

@@ -1,3 +1,3 @@
 module CapybaraSpa
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: capybara_spa
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Zach Dennis
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-05-09 00:00:00.000000000 Z
+date: 2018-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
@@ -158,6 +158,8 @@ files:
 - capybara_spa.gemspec
 - lib/capybara_spa.rb
 - lib/capybara_spa/capybara_dsl_ext.rb
+- lib/capybara_spa/server.rb
+- lib/capybara_spa/server/external_server.rb
 - lib/capybara_spa/server/ng_static_server.rb
 - lib/capybara_spa/version.rb
 homepage: https://github.com/mhs/capybara-spa