Spec: update integration spec task and update docs

Author: aramprice

ci/tasks/test-integration.yml

@@ -24,5 +24,4 @@ params:
   SPEC_PATH:                  ~
   SHA2_MODE:                  ~
   DEFAULT_UPDATE_VM_STRATEGY: "delete-create"
-  NUM_PROCESSES:
   GOOS:                       linux

docs/running_tests.md

@@ -53,16 +53,12 @@ Integration tests describe communication between BOSH components focusing on the
 bosh/src$ bundle exec rake spec:integration
 ```
 
-In order to run the integration tests in parallel:
+Individual specs can be run by setting `SPEC_PATH` to a comma separated list of spec paths relative to `bosh/src/` (ex: `spec/integration/deploy/basic_spec.rb,spec/integration/cli_cck/cloud_config_update_spec.rb`). By default, integration specs are executed in parallel via `parallel_rspec`, if a line number is specified (ex: `some_spec.rb:123`) then `rspec` is used. More information about the integration test set up can  be found in the [workstation setup docs](workstation_setup.md).
 
-```
-export NUM_PROCESSES=<n>
-```
-
-You can run individual tests by invoking `rspec` directly after setting up the sandbox with `rake spec:integration:install_dependencies` and `rake  spec:integration:download_bosh_agent`. More information about the integration test set up can  be found in the [workstation setup docs](workstation_setup.md).
+NOTE: as of 2025-01 the team has not invested in ensuring that local execution is possible, one-off integration spec execution is done via Concourse using the `fly:integration` task. This task also accepts `SPEC_PATH`, as well as `DB` environment variables. Concourse execution requires privileges on that Concourse instance, and a functioning bosh CI pipeline (see: `ci/pipeline.yml`)
 
 ```
-bosh/src$ bundle exec rspec spec/integration/cli_env_spec.rb
+bosh/src$ bundle exec rake fly:integration
 ```
 
 Run tests against a specific database by setting the `DB` environment variable.

src/tasks/spec.rake

@@ -1,36 +1,29 @@
 namespace :spec do
-  namespace :integration do
+  desc 'Run all integration tests against a local sandbox'
+  task :integration do
     $LOAD_PATH << File.join(BOSH_SRC_ROOT, 'spec')
     require 'integration_support/sandbox'
+    IntegrationSupport::Sandbox.setup
 
-    def run_integration_specs(tags: nil)
-      IntegrationSupport::Sandbox.setup
+    rspec_opts = ['--format documentation']
+    rspec_opts += ENV.fetch('RSPEC_TAGS', '').split(',').map { |t| "--tag #{t}" }
 
-      proxy_env = 'https_proxy= http_proxy='
+    paths = ENV.fetch('SPEC_PATH', 'spec').split(',').join(' ')
 
-      rspec_opts += "--tag #{tags}" if tags
-      rspec_opts = "SPEC_OPTS='--format documentation #{rspec_opts}'"
+    spec_runner_command =
+      if paths =~ /:\d+/ # line number was specified; run with `rspec`
+        "bundle exec rspec #{rspec_opts.join(' ')} #{paths}"
 
-      parallel_options = '--multiply-processes 0.5'
-      unless (num_processes = ENV.fetch('NUM_PROCESSES', '')).empty?
-        parallel_options += " -n #{num_processes}"
+      else
+        # no line number specified; run with `parallel_rspec`
+        "SPEC_OPTS='#{rspec_opts.join(' ')}' bundle exec parallel_rspec --multiply-processes 0.5"
       end
 
-      paths = ENV.fetch('SPEC_PATH', ['spec']).split(',').join(' ')
-
-      command =
-        "#{proxy_env} #{rspec_opts} bundle exec parallel_rspec #{parallel_options} #{paths}"
-
-      puts command
-      raise unless system(command)
-    ensure
-      IntegrationSupport::Sandbox.teardown
-    end
-  end
+    proxy_env = 'https_proxy= http_proxy='
 
-  desc 'Run all integration tests against a local sandbox'
-  task :integration do
-    run_integration_specs
+    sh("#{proxy_env} #{spec_runner_command} #{paths}")
+  ensure
+    IntegrationSupport::Sandbox.teardown
   end
 
   desc 'Run template test unit tests (i.e. Bosh::Template::Test)'
@@ -55,13 +48,13 @@ namespace :spec do
     desc 'Run all release unit tests (ERB templates)'
     task :release do
       puts 'Run unit tests for the release (ERB templates)'
-      sh("cd #{File.expand_path('..')} && rspec")
+      sh("cd #{BOSH_REPO_ROOT} && rspec")
     end
 
     namespace :release do
       task :parallel do
         puts 'Run unit tests for the release (ERB templates)'
-        sh("cd #{File.expand_path('..')} && parallel_rspec spec")
+        sh("cd #{BOSH_REPO_ROOT} && parallel_rspec spec")
       end
     end