tests: rationalize rspec suites toward common API usage examples

Trim duplicated RSpec coverage for core tree families and keep specs focused on readable common API usage flows.

Retain exhaustive edge-case and regression coverage in Test::Unit.

Update README, spec/README, and CHANGELOG to reflect suite responsibilities.

Validation: rake lint, rake test:all, rake doc:check.

Author: evolve75

CHANGELOG.md

@@ -8,6 +8,9 @@ Changes section to scan for breaking or behavioral changes.
 
 ### 3.0.0pre / 2026-02-10
 
+* Rationalize RSpec coverage for core tree families so specs emphasize common
+  API usage readability, while exhaustive edge-case and regression coverage
+  remains in the Test::Unit suite.
 * Add non-breaking API aliases for consistency:
   `Tree::AATree#lookup`, `Tree::BTree#lookup`,
   `Tree::FenwickTree#query`, `Tree::SegmentTree#query`,

README.md

@@ -180,7 +180,8 @@ Development dependencies (not required for installing the gem):
 * [Bundler][] for creating the stable build environment
 * [Rake][] for building the package
 * [YARD][] for the documentation
-* [RSpec][] for additional Ruby Spec test files
+* Test::Unit for exhaustive edge-case and regression coverage in `test/`
+* [RSpec][] for readable common API usage examples in `spec/`
 * [RuboCop][] for linting the code
 
 Note: `Tree::TreeNode.new` accepts `{ checks: false }` to disable validation

spec/README.md

@@ -1,5 +1,8 @@
 # RSpec Coverage Notes
 
-RSpec examples in this repository focus on small, readable behavior checks
-such as initialization and cloning. API-level and regression coverage lives
+RSpec examples in this repository focus on readable, common API usage flows
+for each tree type (construction, typical mutations, and representative
+queries/traversals).
+
+Edge-case matrices, exhaustive invariants, and regression contracts live
 primarily in the Test::Unit suite under `test/`.

spec/tree/aa_tree_spec.rb

@@ -9,143 +9,73 @@ def build_tree(entries)
     described_class.new(entries)
   end
 
-  describe 'insert' do
-    it 'keeps keys ordered' do
-      tree = build_tree([[10, 'a'], [20, 'b'], [5, 'c'], [6, 'd'], [12, 'e']])
-      expect(tree.keys).to eq(tree.keys.sort)
-    end
-  end
+  describe 'common key/value usage' do
+    let(:tree) { build_tree([[10, 'a'], [20, 'b'], [5, 'c']]) }
 
-  describe 'search' do
-    it 'finds an existing key' do
-      tree = build_tree([[10, 'a'], [20, 'b'], [5, 'c']])
+    it 'supports lookup by key' do
       expect(tree.search(20)).to eq('b')
     end
 
-    it 'returns nil for a missing key' do
-      tree = build_tree([[10, 'a'], [20, 'b']])
-      expect(tree.search(99)).to be_nil
-    end
-  end
-
-  describe 'delete' do
-    it 'removes a leaf key' do
-      tree = build_tree([[10, 'a'], [20, 'b'], [5, 'c']])
-      expect(tree.delete(5)).to eq('c')
-    end
-
-    it 'removes the key from the tree' do
-      tree = build_tree([[10, 'a'], [20, 'b'], [5, 'c']])
-      tree.delete(5)
-      expect(tree.search(5)).to be_nil
-    end
-
-    it 'keeps keys ordered after delete' do
-      tree = build_tree([[10, 'a'], [20, 'b'], [5, 'c'], [6, 'd'], [12, 'e']])
-      tree.delete(10)
-      expect(tree.keys).to eq(tree.keys.sort)
+    it 'keeps keys in sorted order' do
+      expect(tree.keys).to eq([5, 10, 20])
     end
   end
 
-  describe 'initialize' do
-    it 'accepts array entries' do
-      tree = build_tree([[1, 'a'], [2, 'b']])
-      expect(tree.to_a).to eq([[1, 'a'], [2, 'b']])
-    end
+  describe 'index-style access' do
+    let(:tree) { build_tree([[10, 'a'], [20, 'b']]) }
 
-    it 'accepts hash entries' do
-      tree = build_tree([{ key: 2, value: 'b' }, { key: 1, value: 'a' }])
-      expect(tree.to_a).to eq([[1, 'a'], [2, 'b']])
-    end
-  end
-
-  describe '[]' do
-    it 'returns the value for a key' do
-      tree = build_tree([[10, 'a'], [20, 'b']])
+    it 'reads values with []' do
       expect(tree[20]).to eq('b')
     end
-  end
 
-  describe '[]=' do
-    it 'updates the value for a key' do
-      tree = build_tree([[10, 'a'], [20, 'b']])
+    it 'updates values with []=' do
       tree[20] = 'z'
       expect(tree.search(20)).to eq('z')
     end
   end
 
-  describe 'each' do
-    it 'yields entries in key order' do
-      tree = build_tree([[10, 'a'], [5, 'b'], [20, 'c']])
-      expect(tree.map(&:key)).to eq([5, 10, 20])
-    end
-  end
-
-  describe 'preordered_each' do
-    it 'yields all keys' do
-      tree = build_tree([[10, 'a'], [5, 'b'], [20, 'c'], [15, 'd']])
-      keys = tree.preordered_each.map(&:key)
-      expect(keys.sort).to eq([5, 10, 15, 20])
-    end
-  end
+  describe 'delete' do
+    let(:tree) { build_tree([[10, 'a'], [20, 'b'], [5, 'c']]) }
 
-  describe 'postordered_each' do
-    it 'yields all keys' do
-      tree = build_tree([[10, 'a'], [5, 'b'], [20, 'c'], [15, 'd']])
-      keys = tree.postordered_each.map(&:key)
-      expect(keys.sort).to eq([5, 10, 15, 20])
+    it 'returns the deleted value' do
+      expect(tree.delete(5)).to eq('c')
     end
-  end
 
-  describe 'breadth_each' do
-    it 'yields all keys' do
-      tree = build_tree([[10, 'a'], [5, 'b'], [20, 'c'], [15, 'd']])
-      keys = tree.breadth_each.map(&:key)
-      expect(keys.sort).to eq([5, 10, 15, 20])
+    it 'removes the key from lookup results' do
+      tree.delete(5)
+      expect(tree.search(5)).to be_nil
     end
-  end
 
-  describe 'keys' do
-    it 'returns keys in order' do
-      tree = build_tree([[10, 'a'], [5, 'b'], [20, 'c']])
-      expect(tree.keys).to eq([5, 10, 20])
+    it 'keeps ordered keys after deletion' do
+      tree.delete(5)
+      expect(tree.keys).to eq([10, 20])
     end
   end
 
-  describe 'values' do
-    it 'returns values in key order' do
-      tree = build_tree([[10, 'a'], [5, 'b'], [20, 'c']])
-      expect(tree.values).to eq(%w[b a c])
-    end
-  end
+  describe 'enumeration and serialization usage' do
+    let(:tree) { build_tree([[10, 'a'], [5, 'b'], [20, 'c']]) }
 
-  describe 'to_a' do
-    it 'returns key/value pairs in order' do
-      tree = build_tree([[10, 'a'], [5, 'b'], [20, 'c']])
-      expect(tree.to_a).to eq([[5, 'b'], [10, 'a'], [20, 'c']])
+    it 'enumerates entries in key order' do
+      pairs = tree.map { |entry| [entry.key, entry.value] }
+      expect(pairs).to eq([[5, 'b'], [10, 'a'], [20, 'c']])
     end
-  end
 
-  describe 'to_h and from_hash' do
-    it 'round trips the tree' do
-      tree = build_tree([[10, 'a'], [5, 'b'], [20, 'c']])
+    it 'round-trips via hash conversion' do
       rebuilt = described_class.from_hash(tree.to_h)
       expect(rebuilt.to_a).to eq(tree.to_a)
     end
   end
 
-  describe 'as_json' do
-    it 'returns a hash representation' do
-      tree = build_tree([[10, 'a']])
-      expect(tree.as_json).to be_a(Hash)
+  describe 'shovel insertion' do
+    let(:tree) { build_tree([]) }
+
+    it 'returns the inserted entry' do
+      expect((tree << [10, 'a']).key).to eq(10)
     end
-  end
 
-  describe '<=>' do
-    it 'compares by ordered entries' do
-      left = build_tree([[10, 'a'], [5, 'b']])
-      right = build_tree([[10, 'a'], [5, 'c']])
-      expect(left <=> right).to eq(-1)
+    it 'stores the inserted value' do
+      tree << [10, 'a']
+      expect(tree.search(10)).to eq('a')
     end
   end
 
@@ -155,20 +85,4 @@ def build_tree(entries)
       expect { tree.insert(nil, 'a') }.to raise_error(ArgumentError)
     end
   end
-
-  describe '<<' do
-    it 'returns the inserted entry' do
-      tree = build_tree([])
-      inserted = tree << [10, 'a']
-
-      expect(inserted.key).to eq(10)
-    end
-
-    it 'stores the inserted key/value pair' do
-      tree = build_tree([])
-      tree << [10, 'a']
-
-      expect(tree.search(10)).to eq('a')
-    end
-  end
 end

spec/tree/avl_tree_node_spec.rb

@@ -42,88 +42,42 @@ def height_of(node)
 
   def build_tree(values)
     root = described_class.new('root', values.first)
-    values.drop(1).each_with_index do |value, idx|
-      root.insert("n#{idx}", value)
+    values.drop(1).each_with_index do |value, index|
+      root.insert("n#{index}", value)
     end
     root
   end
 
-  describe 'inserts' do
-    let(:root) { build_tree([10, 5, 15, 12, 18, 2, 8, 6, 1]) }
+  let(:root) { build_tree([10, 5, 15, 12, 18, 2, 8]) }
 
-    it 'keeps in-order traversal sorted' do
-      expect(inorder_contents(root)).to eq(inorder_contents(root).sort)
-    end
-
-    it 'maintains AVL invariants' do
-      expect(avl_valid?(root)).to be(true)
-    end
+  it 'finds inserted keys' do
+    expect(root.search(15).content).to eq(15)
   end
 
-  describe 'search' do
-    let(:root) { build_tree([10, 5, 15]) }
-
-    it 'finds an existing key' do
-      expect(root.search(15).content).to eq(15)
-    end
-
-    it 'returns nil for a missing key' do
-      expect(root.search(7)).to be_nil
-    end
+  it 'returns nil for missing keys' do
+    expect(root.search(7)).to be_nil
   end
 
-  describe 'delete leaf' do
-    let(:root) { build_tree([10, 5, 15, 2]) }
-
-    before { root.delete(2) }
-
-    it 'keeps in-order traversal sorted' do
-      expect(inorder_contents(root)).to eq(inorder_contents(root).sort)
-    end
-
-    it 'maintains AVL invariants' do
-      expect(avl_valid?(root)).to be(true)
-    end
+  it 'keeps in-order traversal sorted' do
+    expect(inorder_contents(root)).to eq(inorder_contents(root).sort)
   end
 
-  describe 'delete node with one child' do
-    let(:root) { build_tree([10, 5, 2]) }
-
-    before { root.delete(5) }
-
-    it 'keeps in-order traversal sorted' do
-      expect(inorder_contents(root)).to eq(inorder_contents(root).sort)
-    end
-
-    it 'maintains AVL invariants' do
-      expect(avl_valid?(root)).to be(true)
-    end
+  it 'maintains AVL invariants after inserts' do
+    expect(avl_valid?(root)).to be(true)
   end
 
-  describe 'delete node with two children' do
-    let(:root) { build_tree([10, 5, 15, 12, 18, 2]) }
-
-    before { root.delete(15) }
+  describe 'delete usage' do
+    before { root.delete(12) }
 
-    it 'keeps in-order traversal sorted' do
-      expect(inorder_contents(root)).to eq(inorder_contents(root).sort)
-    end
-
-    it 'maintains AVL invariants' do
-      expect(avl_valid?(root)).to be(true)
+    it 'removes deleted keys from search' do
+      expect(root.search(12)).to be_nil
     end
-  end
-
-  describe 'delete root' do
-    let(:root) { build_tree([10, 5, 15, 12]) }
 
-    before { root.delete(10) }
-
-    it 'keeps in-order traversal sorted' do
-      expect(inorder_contents(root.root)).to eq(inorder_contents(root.root).sort)
+    it 'keeps in-order traversal sorted after delete' do
+      expect(inorder_contents(root)).to eq(inorder_contents(root).sort)
     end
 
-    it 'maintains AVL invariants' do
+    it 'maintains AVL invariants after delete' do
       expect(avl_valid?(root)).to be(true)
     end
   end