sus-fixtures-benchmark 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91585211a64e9c0976bfb3df369a629697cc777f7fdbf542a4465e20aa546f12
-  data.tar.gz: 2198dc293faa26db8c3e7d200f825debb60c317851185f020e95f743422e034c
+  metadata.gz: de94d05fdae13b52e4e260d2f2fc5fc65792436d6756409fb332e77e4bc64b81
+  data.tar.gz: c0a75a615f5021dbd5ae2f26bb6d5a1eb4ac7c9d5ae22955bffe6573106d260b
 SHA512:
-  metadata.gz: 88b568301dda12a68ddab43ef83a53bce07506ef050ae1d9649bdbe76a377dc4b847d8543e76355bea556ced03c22d98e2898f36bfeae488844d459125c62f10
-  data.tar.gz: daad4662ef40498501e446211544d931e7af0dc6d9823d2a496292af2659928af96cbe16e74f8a4bc94c07a4c4aa74dcf3e675b28a5bda94947a0500e6b01143
+  metadata.gz: 0212ff21fd9e1dc27a2ee42d08bce8e1a2a713bdb204c869789f37a651fa828ff9047d4c2b4f4c85cf1322c822ce232fa2691da90a8d1808e1e7b94636eeb9e4
+  data.tar.gz: 72b37243db4d7c841924e17458dae86e8c028f1327f27711ece5603cb21f87831399498756fe2e1b4ad09be3119db714208c918c99d22a8742bb9efff1c47d0d

data/context/getting-started.md

@@ -0,0 +1,127 @@
+# Getting Started
+
+This guide explains how to use the `sus-fixtures-benchmark` gem to measure and benchmark code performance within your Sus test suite.
+
+## Quick Start
+
+### Project Structure
+
+We recommend organizing your benchmarks in a dedicated `benchmark/` directory:
+
+```
+your-project/
+├── benchmark/
+│   ├── database_performance.rb
+│   ├── algorithm_comparison.rb
+│   └── memory_usage.rb
+├── test/
+├── lib/
+└── Gemfile
+```
+
+This keeps your benchmarks separate from your regular tests and makes them easy to find and run.
+
+### Basic Measurement
+
+The simplest way to measure code performance is using the `measure` method:
+
+```ruby
+# benchmark/array_performance.rb
+require "sus/fixtures/benchmark"
+
+describe "Array Performance" do
+  include Sus::Fixtures::Benchmark
+  
+  let(:data) {(1..1000).to_a}
+  
+  measure "array iteration" do |repeats|
+    repeats.times do
+      data.each{|i| i * 2}
+    end
+  end
+end
+```
+
+This will automatically run your code until statistical convergence is reached and report the results.
+
+**Run with:** `sus --verbose benchmark/array_performance.rb`
+
+### Understanding the Output
+
+When you run your tests with `sus --verbose`, you'll see output like:
+
+```
+measure array iteration 34 samples, mean: 0.15ms, standard deviation: 0.02ms, standard error: 0.003ms
+```
+
+**Important:** You must run `sus --verbose` to see the benchmark output. Without the verbose flag, the benchmark results will not be displayed.
+
+This tells you:
+- **34 samples**: How many times the code was executed.
+- **mean: 0.15ms**: Average execution time.
+- **standard deviation: 0.02ms**: How much variation there was between runs.
+- **standard error: 0.003ms**: How reliable the mean estimate is.
+
+## Measurement Modes
+
+### Automatic Convergence (Default)
+
+By default, the benchmark runs until it achieves statistical convergence:
+
+```ruby
+measure "database query" do |repeats|
+  repeats.times do
+    User.where(active: true).count
+  end
+end
+```
+
+The system will automatically determine when it has enough samples to provide a reliable measurement based on:
+- **Confidence level**: 95% by default
+- **Margin of error**: 2% of the mean by default (0.02)
+- **Minimum samples**: 8 by default
+
+### Fixed Number of Iterations
+
+If you need a specific number of iterations, use the `exactly` method:
+
+```ruby
+measure "quick test" do |repeats|
+  repeats.exactly(10).times do
+    # Your code here
+  end
+end
+```
+
+This is useful for:
+- Quick smoke tests.
+- When you know the exact number of iterations needed.
+- Debugging or development scenarios.
+
+## Configuration Options
+
+### Customizing the Sampler
+
+You can customize the statistical parameters directly in the `measure` method:
+
+```ruby
+measure "high precision", minimum: 20, confidence: 0.98, margin_of_error: 0.01 do |repeats|
+  repeats.times do
+    # Your code here
+  end
+end
+```
+
+### Parameter Reference
+
+You should try to avoid deviating from the defaults.
+
+  - **`minimum`** (Integer): Minimum samples before convergence (default: 8). 
+    - **Lower `minimum`**: Quick development feedback (e.g., `minimum: 3`)
+    - **Higher `minimum`**: High-variance operations (e.g., `minimum: 30`)
+  - **`confidence`** (Float): Confidence level 0.0-1.0 (default: 0.95). High confidence (above 0.98) may take an extremely long time to converge.
+    - **Lower `confidence`**: Faster results (e.g., `confidence: 0.90`)
+    - **Higher `confidence`**: Production guarantees (e.g., `confidence: 0.98`)
+  - **`margin_of_error`** (Float): Acceptable error as a fraction of the mean (default: 0.02 = 2%).
+    - **Lower `margin_of_error`**: High precision (e.g., `margin_of_error: 0.01`)
+    - **Higher `margin_of_error`**: Rough estimates (e.g., `margin_of_error: 0.05`)

data/lib/sus/fixtures/benchmark/version.rb

@@ -6,7 +6,7 @@
 module Sus
 	module Fixtures
 		module Benchmark
-			VERSION = "0.2.0"
+			VERSION = "0.2.1"
 		end
 	end
 end

data/readme.md

@@ -12,11 +12,15 @@ bundle add sus-fixtures-benchmark
 
 ## Usage
 
-Please see the [project documentation](https://suspecting.github.io/sus-fixtures-benchmark/) for more details.
+Please see the [project documentation](https://socketry.github.io/sus-fixtures-benchmark/) for more details.
 
 ## Releases
 
-Please see the [project releases](https://suspecting.github.io/sus-fixtures-benchmark/releases/index) for all releases.
+Please see the [project releases](https://socketry.github.io/sus-fixtures-benchmark/releases/index) for all releases.
+
+### v0.2.1
+
+  - Fix links and add context.
 
 ### v0.2.0
 

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.2.1
+
+  - Fix links and add context.
+
 ## v0.2.0
 
   - Added `exactly(count)` method to `Sus::Fixtures::Benchmark::Repeats` which returns an `Exactly` instance for fixed-count benchmarking.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sus-fixtures-benchmark
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -57,6 +57,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - agent.md
+- context/getting-started.md
 - lib/sus/fixtures/benchmark.rb
 - lib/sus/fixtures/benchmark/repeats.rb
 - lib/sus/fixtures/benchmark/sampler.rb
@@ -65,13 +66,13 @@ files:
 - license.md
 - readme.md
 - releases.md
-homepage: https://github.com/suspecting/sus-fixtures-benchmark
+homepage: https://github.com/socketry/sus-fixtures-benchmark
 licenses:
 - MIT
 metadata:
-  documentation_uri: https://suspecting.github.io/sus-fixtures-benchmark/
+  documentation_uri: https://socketry.github.io/sus-fixtures-benchmark/
   funding_uri: https://github.com/sponsors/ioquatix/
-  source_code_uri: https://github.com/suspecting/sus-fixtures-benchmark.git
+  source_code_uri: https://github.com/socketry/sus-fixtures-benchmark.git
 rdoc_options: []
 require_paths:
 - lib