specwrk 0.4.5 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b752ad94605b60fec10d72935d86e9d37cc0b3cf7ae107163921259f1895affa
-  data.tar.gz: 131680d8a177b839c46c11d910841e704d3eff134c0578356f639a22df325d69
+  metadata.gz: 29b6d72df4f3e3a4ff055b9d9203e6af31173fbab4fe43235495bcadcbf7c37e
+  data.tar.gz: 3b9c0af70e17efd7f5a42529550b49c2ce6b58e62f7b0f8c2fa4d66d14f09822
 SHA512:
-  metadata.gz: 5b4c33485613191a342c8b614663a954b181a551ef53efa23fe35ae2c964bcbe843a56493d6afcaae33d88aee9b6272d8edfe7e2323b46fc7d144101c1b8628f
-  data.tar.gz: ed8d728db0fc51274083efc82ddeb4db2766113893f3bf646feda0061a7ce601d0ebd82109545d8434c989437ec7fb2885607c1b077166066647d9c9c1a383f3
+  metadata.gz: b6088d190bcbbd0b274f76d992626c851637c27d132fb5642298c15cfa49f891265836f800bf0dbca77eee3dc680cb606ddb6262cd18bc09776ed7623e81d494
+  data.tar.gz: ffcda0f107b0b82d40d3bf2472a1b0447afed956bdb969abc1765e8c158b03a2ffa32c8d7ed2d130b46d5d42294e97d6f32be05ff3c299a61f75b154d4be5465

data/.circleci/config.yml

@@ -0,0 +1,155 @@
+version: 2.1
+
+workflows:
+  test_workflow:
+    jobs:
+      - test
+      - specwrk-single-node
+      - specwrk-multi-node-prepare
+      - specwrk-multi-node:
+          requires:
+            - specwrk-multi-node-prepare
+
+jobs:
+  test:
+    docker:
+      - image: cimg/ruby:3.4.4
+    working_directory: ~/project
+    steps:
+      - checkout
+
+      - restore_cache:
+          keys:
+            - v1-deps-{{ checksum "Gemfile" }}-{{ checksum "specwrk.gemspec" }}
+            - v1-deps-{{ checksum "Gemfile" }}
+            - v1-deps-
+
+      - run:
+          name: Install Gems
+          command: |
+            bundle config path vendor/bundle
+            bundle install --jobs 4 --retry 2
+
+      - save_cache:
+          paths:
+            - vendor/bundle
+          key: v1-deps-{{ checksum "Gemfile" }}-{{ checksum "specwrk.gemspec" }}
+
+      - run:
+          name: Run RSpec
+          command: bundle exec rspec
+
+  specwrk-single-node:
+    docker:
+      - image: cimg/ruby:3.4.4
+    working_directory: ~/project
+    steps:
+      - checkout
+
+      - restore_cache:
+          keys:
+            - v1-deps-{{ checksum "Gemfile" }}-{{ checksum "specwrk.gemspec" }}
+            - v1-deps-{{ checksum "Gemfile" }}
+            - v1-deps-
+
+      ## SPECWRK STEP ##
+      - restore_cache:
+          keys:
+            - specwrk-{{ .Branch }}
+            - specwrk-
+      ## /SPECWRK STEP ##
+          
+      - run:
+          name: Install Gems
+          command: |
+            bundle config path vendor/bundle
+            bundle install --jobs 4 --retry 2
+
+      - save_cache:
+          paths:
+            - vendor/bundle
+          key: v1-deps-{{ checksum "Gemfile" }}-{{ checksum "specwrk.gemspec" }}
+
+      ## SPECWRK STEP ##
+      - run:
+          name: Run tests via specwrk start
+          command: bundle exec specwrk start --count 2 spec/
+      ## /SPECWRK STEP ##
+        
+      ## SPECWRK STEP ##
+      - save_cache:
+          paths:
+            - .specwrk/report.json
+          key: specwrk-{{ .Branch }}
+      ## /SPECWRK STEP ##
+        
+  specwrk-multi-node-prepare:
+    docker:
+      - image: cimg/ruby:3.4.4
+    steps:
+      - checkout
+
+      - restore_cache:
+          keys:
+            - gem-cache-{{ checksum "Gemfile" }}-{{ checksum "specwrk.gemspec" }}
+            - gem-cache-{{ checksum "Gemfile" }}
+            - gem-cache-
+
+      - run:
+          name: bundle install
+          command: |
+            bundle config path vendor/bundle
+            bundle install --jobs 4 --retry 2
+
+      - save_cache:
+          paths:
+            - vendor/bundle
+          key: gem-cache-{{ checksum "Gemfile" }}-{{ checksum "specwrk.gemspec" }}
+
+      ## SPECWRK STEP ##
+      - run:
+          name: Seed examples to specwrk server
+          command: |
+            bundle exec specwrk seed \
+              --uri "$SPECWRK_URI" \
+              --key "$SPECWRK_KEY" \
+              --run "$CIRCLE_WORKFLOW_ID" \
+              spec/
+
+      ## /SPECWRK STEP ##
+
+  specwrk-multi-node:
+    parallelism: 2
+    docker:
+      - image: cimg/ruby:3.4.4
+    working_directory: ~/project
+    steps:
+      - checkout
+
+      - restore_cache:
+          keys:
+            - v1-deps-{{ checksum "Gemfile" }}-{{ checksum "specwrk.gemspec" }}
+            - v1-deps-{{ checksum "Gemfile" }}
+            - v1-deps-
+
+      - run:
+          name: Install Gems
+          command: |
+            bundle config path vendor/bundle
+            bundle install --jobs 4 --retry 2
+
+      - save_cache:
+          paths:
+            - vendor/bundle
+          key: v1-deps-{{ checksum "Gemfile" }}-{{ checksum "specwrk.gemspec" }}
+
+      ## SPECWRK STEP ##
+      - run:
+          name: Run tests via specwrk work
+          command: |
+            bundle exec specwrk work \
+              --uri "$SPECWRK_URI" \
+              --key "$SPECWRK_KEY" \
+              --run "$CIRCLE_WORKFLOW_ID" \
+              --count 2
+      ## /SPECWRK STEP ##

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 ## [Unreleased]
 
-## [0.1.0] - 2025-05-12
+## v0.4.5
 
-- Initial release
+- Set ENV var when generating seed examples [#47](https://github.com/danielwestendorf/specwrk/issues/47). by @danielwestendorf 
+## v0.4.4
+
+- Don’t dump the completed queue if it’s empty [#45](https://github.com/danielwestendorf/specwrk/issues/45). by @danielwestendorf
+- Move single-run CLI option to only be an option for the `serve` command [#41](https://github.com/danielwestendorf/specwrk/issues/41). by @danielwestendorf
+- Don’t complete examples which are not in the processing queue [#44](https://github.com/danielwestendorf/specwrk/issues/44). by @danielwestendorf
+
+## v0.4.3
+
+- Fix CLI’s `--uri` option description. by @danielwestendorf
+- Add an unauthenticated `/health` endpoint to the server [#40](https://github.com/danielwestendorf/specwrk/issues/40). by @danielwestendorf
+- Add support excluding server paths from authentication [#39](https://github.com/danielwestendorf/specwrk/issues/39). by @danielwestendorf
+
+## v0.4.2
+
+- Add specwrk variations to CI [#38](https://github.com/danielwestendorf/specwrk/issues/38). by @danielwestendorf
+- Support specifying if subsequent seeds should be ignored for a run [#37](https://github.com/danielwestendorf/specwrk/issues/37). by @danielwestendorf
+
+## v0.4.1
+
+- Make the number of seed waits configurable [#35](https://github.com/danielwestendorf/specwrk/issues/35). by @danielwestendorf
+
+## v0.4.0
+
+- Worker wait for seeding [#32](https://github.com/danielwestendorf/specwrk/issues/32). by @danielwestendorf
+- Track if the worker has processed *any* examples [#31](https://github.com/danielwestendorf/specwrk/issues/31). by @danielwestendorf
+
+## v0.3.0
+
+- Assign `Specwrk.net_http` to `Net::HTTP` before WebMock can mock it [#22](https://github.com/danielwestendorf/specwrk/issues/22). by @danielwestendorf
+- Worker PIDs representative exit status [#20](https://github.com/danielwestendorf/specwrk/issues/20). by @danielwestendorf
+- Track an individual worker’s failures [#19](https://github.com/danielwestendorf/specwrk/issues/19). by @danielwestendorf
+- Default localhost server URI is not SSL. by @danielwestendorf
+- Handle SSL-protected srv endpoints [#18](https://github.com/danielwestendorf/specwrk/issues/18). by @danielwestendorf
+
+## v0.2.0
+
+- Tag v0.2.0 by @danielwestendorf

data/README.md

@@ -8,7 +8,7 @@ One CLI command to:
 3. Execute
 
 ## Install
-Start by adding specwrk to your project or installing it.
+Start by adding `specwrk` to your project or installing it.
 ```sh
 $ bundle add specwrk -g development,test
 ```
@@ -30,7 +30,7 @@ Commands:
 ```
 
 ### `specwrk start -c 8 spec/`
-Indended for quick-adhoc runs in development. This command starts a queue server, seeds it with examples from the `spec/` directory, and starts `8` worker processes. It will report the ultimate success or failure.
+Intended for quick ad-hoc local host development or single-node CI runs. This command starts a queue server, seeds it with examples from the `spec/` directory, and starts `8` worker processes. It will report the ultimate success or failure.
 
 ```sh
 $ start --help
@@ -158,14 +158,78 @@ Rails has had easy multi-process test setup for a while now by creating unique t
 -- Capybara.server_port = 5550
 ++ Capybara.server_port = 5550 + ENV.fetch("TEST_ENV_NUMBER", "1").to_i
 ++ Capybara.always_include_port = true
+-- ActiveRecord::Migration.maintain_test_schema!
+++ ActiveRecord::Migration.maintain_test_schema! unless ENV["SPECWRK_SEED"]
 ```
 
+YMMV, but please submit an issue if your setup required more configuration.
+
 ## CI
 Run `specwrk` in CI in either a single-node or multi-node configuration.
 
 ### Single-node, multi-process
-Single-node + multi-process is the easiest way to get started. Add it to your existing configuration
+Single-node, multi-process works best when you only have a single node running tests, but that node has many unused CPUs. This is similar to running `specwrk` locally with `bundle exec specwrk start spec/` which spins up a local server, seeds the server with examples that need to be run, and then spawns child worker processes which execute those examples in parallel.
+
+Make sure to persist `$SPECWRK_OUT/report.json` between runs so that subsequent run queues can be optimized.
+
+[GitHub Actions Example](https://github.com/danielwestendorf/specwrk/blob/main/.github/workflows/specwrk-single-node.yml)
+
+[CircleCI Example](https://github.com/danielwestendorf/specwrk/blob/main/.circleci/config.yml) (specwrk-single-node job)
+
+### Multi-node, multi-process
+Multi-node, multi-process works best when have many nodes running tests. This distributes the test execution across the nodes until the queue is for the run is empty, optimizing for slowest specs first. This distributes test execution across all nodes evenly(-ish).
+
+To accomplish this, a central queue server is required, examples must be explicitly seeded, and workers explicitly started.
+
+1. Start a centralized queue server (see [Running a persistent Queue Server](#running-a-persistent-queue-server)) 
+2. Seed the server with the specs for the current `SPECWWRK_RUN` pointed at your central server
+3. Execute `specwrk work` for the given process count, for the current `SPECWRK_RUN`, pointed at your central server
+
+[GitHub Actions Example](https://github.com/danielwestendorf/specwrk/blob/main/.github/workflows/specwrk-multi-node.yml)
+
+[CircleCI Example](https://github.com/danielwestendorf/specwrk/blob/main/.circleci/config.yml) (see specwrk-multi-node-prepare, specwrk-multi-node jobs)
+
+
+## Running a persistent Queue Server
+Start a persistent Queue Server given one of the following methods
+- The explicit ruby command `bundle exec specwrk serve --port $PORT`
+- Via [docker image](https://hub.docker.com/repository/docker/danielwestendorf/specwrk-server/general): `docker run -e PORT=5139 -p 5139:5139 docker.io/danielwestendorf/specwrk-server:latest`
+- By mounting the app as an Rack app
+  ```ruby
+  require 'rack'
+  require 'specwrk/web'
+
+  app = Specwrk::Web.rackup   # this is a Rack::Builder instance
+
+  Rack::Server.start(
+    app:    app,              
+    server: 'webrick',        
+    Host:   '0.0.0.0',        
+    Port:   9292
+  )
+
+  # OR maybe
+  # Rack::Handler::WEBrick.run(app, Host: '0.0.0.0', Port: 9292)
+  # Rack::Handler::Puma.run(app, Host: '0.0.0.0', Port: 9292)
+
+  # OR maybe
+  # config.ru
+  require_relative 'lib/specwrk/web'
+
+  run Specwrk::Web.rackup
+
+  # OR maybe
+  # config/routes.rb
+  Rails.application.routes.draw do
+    # everything under /specwrk will be handled by your Rack::Builder
+    mount Specwrk::Web.rackup, at: '/specwrk'
+  end
+  ```
+### Configuring your Queue Server
+- Secure your server with a key either with the `SPECWRK_SRV_KEY` environment variable or `--key` CLI option
+- Configure the server output to be a persisted volume so your timings survive between restarts with  the `SPECWRK_OUT` environment variable or `--out` CLI option 
 
+See [specwrk serve --help](#specwrk-serve) for all possible configuration options.
 
 ## Contributing
 

data/lib/specwrk/cli.rb

@@ -122,8 +122,10 @@ module Specwrk
         Client.new.seed(examples)
       rescue Errno::ECONNREFUSED
         puts "Server at #{ENV.fetch("SPECWRK_SRV_URI", "http://localhost:5138")} is refusing connections, exiting...#{ENV["SPECWRK_FLUSH_DELIMINATOR"]}"
+        exit 1
       rescue Errno::ECONNRESET
         puts "Server at #{ENV.fetch("SPECWRK_SRV_URI", "http://localhost:5138")} stopped responding to connections, exiting...#{ENV["SPECWRK_FLUSH_DELIMINATOR"]}"
+        exit 1
       end
     end
 
@@ -184,6 +186,9 @@ module Specwrk
         self.class.setup(**args)
         $stdout.sync = true
 
+        # nil this env var if it exists to prevent never-ending workers
+        ENV["SPECWRK_SRV_URI"] = nil
+
         web_pid = Process.fork do
           require "specwrk/web"
           require "specwrk/web/app"
@@ -210,7 +215,10 @@ module Specwrk
           status "Samples seeded ✓"
         end
 
-        Specwrk.wait_for_pids_exit([seed_pid])
+        if Specwrk.wait_for_pids_exit([seed_pid]).value?(1)
+          Process.kill("INT", web_pid)
+          exit(1)
+        end
 
         return if Specwrk.force_quit
         status "Starting #{worker_count} workers..."

data/lib/specwrk/client.rb

@@ -102,13 +102,13 @@ module Specwrk
     def complete_examples(examples)
       response = post "/complete", body: examples.to_json
 
-      (response.code == "200") ? true : UnhandledResponseError.new("#{response.code}: #{response.body}")
+      (response.code == "200") ? true : raise(UnhandledResponseError.new("#{response.code}: #{response.body}"))
     end
 
     def seed(examples)
       response = post "/seed", body: examples.to_json
 
-      (response.code == "200") ? true : UnhandledResponseError.new("#{response.code}: #{response.body}")
+      (response.code == "200") ? true : raise(UnhandledResponseError.new("#{response.code}: #{response.body}"))
     end
 
     private

data/lib/specwrk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Specwrk
-  VERSION = "0.4.5"
+  VERSION = "0.4.6"
 end

data/lib/specwrk/web/app.rb

@@ -49,7 +49,7 @@ module Specwrk
         def rackup
           Rack::Builder.new do
             use Rack::Runtime
-            use Specwrk::Web::Logger, $stdout
+            use Specwrk::Web::Logger, $stdout, %w[/health]
             use Specwrk::Web::Auth, %w[/health] # global auth check
             run Specwrk::Web::App.new           # your router
           end

data/lib/specwrk/web/endpoints.rb

@@ -82,9 +82,7 @@ module Specwrk
         def response
           processing_queue.synchronize do |processing_queue_hash|
             payload.each do |example|
-              next unless processing_queue_hash.key?(example[:id])
-
-              processing_queue_hash.delete(example[:id])
+              next unless processing_queue_hash.delete(example[:id])
               completed_queue[example[:id]] = example
             end
           end

data/lib/specwrk/web/logger.rb

@@ -3,11 +3,15 @@
 module Specwrk
   class Web
     class Logger
-      def initialize(app, out = $stdout)
-        @app, @out = app, out
+      def initialize(app, out = $stdout, ignored_paths = [])
+        @app = app
+        @out = out
+        @ignored_paths = ignored_paths
       end
 
       def call(env)
+        return @app.call(env) if @ignored_paths.include? env["PATH_INFO"]
+
         start_time = Time.now
         start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         status, headers, body = @app.call(env)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: specwrk
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.4.6
 platform: ruby
 authors:
 - Daniel Westendorf
@@ -142,6 +142,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".circleci/config.yml"
 - ".rspec"
 - ".standard.yml"
 - CHANGELOG.md