specwrk 0.4.5 → 0.4.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b752ad94605b60fec10d72935d86e9d37cc0b3cf7ae107163921259f1895affa
-  data.tar.gz: 131680d8a177b839c46c11d910841e704d3eff134c0578356f639a22df325d69
+  metadata.gz: ed8dbd2952f7e8caf1de7903bb7a03b02ddaba8a735246e347b2f56e7770b22e
+  data.tar.gz: a4a8403a07f36363e9a7d8239f824f7d33bffed98478540a044d6f8d293b130f
 SHA512:
-  metadata.gz: 5b4c33485613191a342c8b614663a954b181a551ef53efa23fe35ae2c964bcbe843a56493d6afcaae33d88aee9b6272d8edfe7e2323b46fc7d144101c1b8628f
-  data.tar.gz: ed8d728db0fc51274083efc82ddeb4db2766113893f3bf646feda0061a7ce601d0ebd82109545d8434c989437ec7fb2885607c1b077166066647d9c9c1a383f3
+  metadata.gz: fa9f2687d4009ee526037b19155225d24a9746b124101962dce1ecde652ea5c0f1bc788933f4bf5c7713f7983d018b7d5a2ddf2684361b6d5c0a951518010391
+  data.tar.gz: 77dd8e7ea504a2e02905f7dd6b5a1d13ece46a72653af791cea40bc6e3dbf9788c9238c28b1ee70cdcc0f8bab59c5dc235012cbe8d8ddf43541db3c5ddf06f7c

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,49 @@ 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 (see `config.ru`)
+
+### 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/config.ru

@@ -0,0 +1,3 @@
+require "specwrk/web/app"
+
+run Specwrk::Web::App.rackup

data/docker/Dockerfile.server

@@ -1,5 +1,12 @@
 FROM ruby:3.4-alpine
 
+RUN apk add --no-cache \
+      build-base \
+      ruby-dev \
+      linux-headers \
+      zlib-dev \
+      libffi-dev
+
 WORKDIR /app
 
 RUN mkdir .specwrk/
@@ -12,6 +19,9 @@ COPY $GEMFILE ./
 RUN gem install ./$GEMFILE --no-document
 RUN rm ./$GEMFILE
 
+RUN gem install puma
+COPY config.ru ./
+
 COPY docker/entrypoint.server.sh /usr/local/bin/entrypoint
 RUN chmod +x /usr/local/bin/entrypoint
 

data/docker/entrypoint.server.sh

@@ -1,3 +1,5 @@
 #!/bin/sh
 
-exec specwrk serve --port ${PORT:-$SPECWRK_SRV_PORT} --bind 0.0.0.0 --no-single-run --verbose
+export SPECWRK_SRV_SINGLE_RUN=1
+
+exec puma --port ${PORT:-$SPECWRK_SRV_PORT} --bind tcp://0.0.0.0 --threads 1 --workers 0 --silent

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.7"
 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.7
 platform: ruby
 authors:
 - Daniel Westendorf
@@ -142,12 +142,14 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".circleci/config.yml"
 - ".rspec"
 - ".standard.yml"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- config.ru
 - docker/Dockerfile.server
 - docker/entrypoint.server.sh
 - exe/specwrk