From dc1ba134272a292073cf8ac5deb7ba5cdf2f1d1a Mon Sep 17 00:00:00 2001
From: kholdrex <alexandrkholodniak@gmail.com>
Date: Thu, 4 Jun 2026 03:29:45 -0500
Subject: [PATCH] test: cover README examples

---
 CHANGELOG.md                 |  3 ++
 spec/readme_examples_spec.rb | 55 ++++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 spec/readme_examples_spec.rb

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a33215f..b4d1618 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,9 @@ All notable changes to this project are documented in this file.
 
 ## [Unreleased]
 
+### Added
+- Added executable specs for README usage examples to keep the documented Rasch, 2PL, 3PL, and missing-data flows aligned with the public API.
+
 ### Changed
 - Clarified that response data must be a `Matrix` or array of arrays containing only integer `0`, integer `1`, or `nil`; floats, strings, booleans, and other values are rejected.
 
diff --git a/spec/readme_examples_spec.rb b/spec/readme_examples_spec.rb
new file mode 100644
index 0000000..0ab246a
--- /dev/null
+++ b/spec/readme_examples_spec.rb
@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "matrix"
+
+RSpec.describe "README examples" do
+  let(:data) do
+    Matrix[
+      [1, 0, 1],
+      [0, 1, 0],
+      [1, 1, 1]
+    ]
+  end
+
+  it "runs the Rasch quick-start example" do
+    model = IrtRuby::RaschModel.new(data)
+    result = model.fit
+
+    expect(result[:abilities].size).to eq(data.row_count)
+    expect(result[:difficulties].size).to eq(data.column_count)
+  end
+
+  it "runs the 2PL and 3PL examples" do
+    two_pl_result = IrtRuby::TwoParameterModel.new(data).fit
+    three_pl_result = IrtRuby::ThreeParameterModel.new(data).fit
+
+    expect(two_pl_result[:abilities].size).to eq(data.row_count)
+    expect(two_pl_result[:difficulties].size).to eq(data.column_count)
+    expect(two_pl_result[:discriminations].size).to eq(data.column_count)
+
+    expect(three_pl_result[:abilities].size).to eq(data.row_count)
+    expect(three_pl_result[:difficulties].size).to eq(data.column_count)
+    expect(three_pl_result[:discriminations].size).to eq(data.column_count)
+    expect(three_pl_result[:guessings].size).to eq(data.column_count)
+  end
+
+  it "runs the missing-data example with array input" do
+    data_with_missing = [
+      [1, nil, 0],
+      [nil, 1, 0],
+      [0, 1, 1]
+    ]
+
+    model = IrtRuby::RaschModel.new(
+      data_with_missing,
+      max_iter: 300,
+      learning_rate: 0.01,
+      missing_strategy: :treat_as_incorrect
+    )
+    result = model.fit
+
+    expect(result[:abilities].size).to eq(data_with_missing.size)
+    expect(result[:difficulties].size).to eq(data_with_missing.first.size)
+  end
+end