RSpec 2.99 和 3.0 beta 版已發佈！

Myron Marston

RSpec 團隊剛剛發佈了 RSpec 3.0.0.beta1 – 第一個 RSpec 3 的預發行版本！同時，我們也發佈了 2.99.0.beta1，旨在協助升級過程。

我要感謝所有貢獻者，尤其是核心團隊（Andy、Bradley、Jon、Sam 和 Xavier），讓這次發佈得以實現。

我現在沒有精力撰寫完整的「RSpec 3 有哪些新功能」部落格文章，但我們主要是根據我們先前宣佈的 RSpec 3 計劃進行變更。詳細的發行說明如下，可讓您了解這些版本的詳細資訊。我們將在未來發佈其他部落格文章，深入討論新功能。

升級過程

RSpec 3 包含許多重大變更，但我們希望這次升級能成為您有史以來最順利的 gem 主要版本升級。為了協助此過程，我們一直在與 RSpec 3 同步開發 RSpec 2.99。每當我們在 3.0 的主分支中進行重大變更時，我們都會在 2.99 中新增相應的棄用。這不僅適用於已移除的 API；也適用於邊緣案例語義的細微變更（為了讓 RSpec 更一致），有些專案可能會依賴這些變更。RSpec 2.99 不僅提供描述所有重大變更（包括許多影響極少數使用者！）的通用升級文件，還為您提供詳細的升級檢查清單。

此外，Yuji Nakayama 一直在開發 transpec – 一個絕對驚人的工具，可以自動升級大多數 RSpec 套件。我在幾個專案上嘗試過，並且對它的運作效果感到驚訝。

以下是我建議將專案升級到 RSpec 3 的一般方法

1. 確保您的測試套件在您目前使用的任何 RSpec 2.x 版本上都是綠色的。
2. 安裝 RSpec 2.99.0.beta1（或您在執行此過程時的最新 2.99 版本）。
3. 執行您的測試套件並確保它仍然是綠色的。（應該是這樣，但我們可能犯了錯誤 – 如果它破壞了任何東西，請回報錯誤！）。現在是提交的好時機。
4. 您會注意到在規格執行結束時會印出一堆棄用警告。這些警告可能會被截斷，因為我們不想重複向您發送相同的棄用警告。若要取得完整的棄用清單，您可以透過設定 config.deprecation_stream = 'rspec.log' 選項將其導向到檔案。
5. 如果您想了解所有已棄用的內容，最好閱讀棄用訊息。在某些情況下，您有選擇 – 例如繼續透過已擷取的 rspec-collection_matchers gem 使用 have 集合基數匹配器，或將期望表達式重寫為類似 expect(list.size).to eq(3) 的形式。
6. gem install transpec（請注意，這不需要放入您的 Gemfile：您在套件組合的環境之外，以獨立的可執行檔形式執行 transpec）。
7. 在您的專案上執行 transpec。請參閱 transpec --help 或 README 以取得完整的選項清單。
8. 執行測試套件（它應該仍然是綠色的，但最好還是檢查一下！）並提交。
9. 如果還有任何剩餘的棄用警告（transpec 並不完全處理您可能收到的所有警告），請處理它們。
10. 一旦您使用 RSpec 2.99 執行無棄用的測試套件，您就可以升級到 RSpec 3。安裝 RSpec 3.0.0.beta1（或您在執行此過程時的最新 3.x 版本）。
11. 執行您的測試套件。它應該仍然是綠色的。如果任何東西失敗，請開啟 GitHub 問題 – 我們認為這是一個錯誤[^foot_1]！
12. 提交並享受使用最新 RSpec 版本！

下一步

雖然我們在 RSpec 3 上取得了重大進展，但我們還沒完成。我們還有更多事情要做。（我們還沒有完成我們計劃的一切。）我們認真看待 SemVer，這是我們多年來第一次有機會清理舊的雜物，所以我們想充分利用它 :)。我們希望在未來幾個月內發佈 RC，並在此之後不久發佈最終版本。

發行說明

rspec-core 2.99.0.beta1

完整變更記錄

增強功能

• 在範例（it、before(:each)、after(:each)、let 和 subject）環境中執行的基於區塊的 DSL 方法現在會將範例作為區塊引數傳回。（David Chelimsky）
• 當多個範例群組的名稱提交至 include_examples 及其別名時發出警告。（David Chelimsky）
• 新增 expose_current_running_example_as 配置選項，以便在外部 gem 使用已棄用的 RSpec::Core::ExampleGroup#example 和 RSpec::Core::ExampleGroup#running_example 方法時，在升級過程中使用。（Myron Marston）
• 限制棄用訊息的垃圾郵件程度。（Bradley Schaefer、Loren Segal）
• 新增 config.raise_errors_for_deprecations! 選項，該選項會將棄用警告轉為錯誤，以顯示呼叫位置的完整回溯。（Myron Marston）

棄用

• 棄用 RSpec::Core::ExampleGroup#example 和 RSpec::Core::ExampleGroup#running_example 方法。如果您需要存取範例（例如，取得其中繼資料），請改用區塊引數。（David Chelimsky）
• 棄用使用 autotest/rspec2 而改用 rspec-autotest。（Jon Rowe）
• 棄用 RSpec 的內建除錯器支援。請改用 CLI 選項，例如 -rruby-debug（用於 ruby-debug gem）或 -rdebugger（用於 debugger gem）。（Myron Marston）
• 棄用 config.treat_symbols_as_metadata_keys_with_true_values = false。RSpec 3 將不支援將此選項設定為 false。（Myron Marston）
• 棄用在 after(:all) 掛鉤中存取 let 或 subject 宣告。（Myron Marston、Jon Rowe）
• 由於計劃在 RSpec 3 中移除，因此棄用內建的 its 用法，而改用 rspec-its gem。（Peter Alfvin）
• 棄用 RSpec::Core::PendingExampleFixedError 而改用 RSpec::Core::Pending::PendingExampleFixedError。（Myron Marston）
• 棄用 RSpec::Core::Configuration#out 和 RSpec::Core::Configuration#output 而改用 RSpec::Core::Configuration#output_stream。（Myron Marston）
• 以下每一項都已棄用，而改用 register_ordering(:global)（Myron Marston）
  • RSpec::Core::Configuration#order_examples
  • RSpec::Core::Configuration#order_groups
  • RSpec::Core::Configuration#order_groups_and_examples
• 這些已棄用，沒有替代方案，因為在 RSpec 3 中，排序是個別範例群組的屬性，而不只是整個測試套件的整體屬性（Myron Marston）
  • RSpec::Core::Configuration#order
  • RSpec::Core::Configuration#randomize?
  • --order default 已棄用，而改用 --order defined

rspec-core 3.0.0.beta1

完整變更記錄

重大變更

• 移除對 1.8.6 的明確支援。（Jon Rowe）
• 移除 RSpec::Core::ExampleGroup#example 和 RSpec::Core::ExampleGroup#running_example 方法。如果您需要存取範例（例如，取得其中繼資料），請改用區塊引數。（David Chelimsky）
• 移除 TextMateFormatter，它已移至 rspec-tmbundle。（Aaron Kromer）
• 移除 RCov 整合。（Jon Rowe）
• 移除對 RSpec 1 建構的已棄用支援（Myron Marston）
  • Spec 和 Rspec 常數（而不是 RSpec）。
  • Spec::Runner.configure 而不是 RSpec.configure。
  • Rake::SpecTask 而不是 RSpec::Core::RakeTask。
• 移除對 share_as 的已棄用支援。（Myron Marston）
• 移除 --debug 選項（以及 RSpec::Core::Configuration 上的對應選項）。請改用 -r<除錯器 gem 名稱> 來載入您想要使用的任何除錯器 gem（例如 ruby-debug、debugger 或 pry）。（Myron Marston）
• 將 Autotest 支援擷取到單獨的 gem。（Jon Rowe）
• 當在 before(:all) 或 after(:all) 掛鉤中存取 let 或 subject 宣告時，引發錯誤。（Myron Marston）
• 將 its 支援擷取到單獨的 gem。（Peter Alfvin）
• 禁止從同級環境使用共用範例群組，使其完全隔離。2.14 和 2.99 允許這樣做，但會印出棄用警告。（Jon Rowe）
• 移除 RSpec::Core::Configuration#output 和 RSpec::Core::Configuration#out 作為 RSpec::Core::Configuration#output_stream 的別名。（Myron Marston）

增強功能

• 以 coderay gem 取代未維護的語法 gem。（Xavier Shay）
• 個人資料輸出中的時間現在會以粗體顯示，而不是 failure_color。（Matthew Boedicker）
• 新增 --no-fail-fast 命令列選項。（Gonzalo Rodríguez-Baltanás Díaz）
• 現在，執行器在 Drb 下執行時，會考量本機系統 IP 位址。（Adrian CB）
• JsonFormatter 現在包含 --profile 資訊。（Alex / @MasterLambaster）
• 一律將作為中繼資料引數傳遞的符號視為具有 true 值的雜湊索引鍵。RSpec 2 透過 treat_symbols_as_metadata_keys_with_true_values 支援此功能，但現在此行為一律啟用。（Myron Marston）
• 新增 --dry-run 選項，該選項會印出您的套件的格式器輸出，而不執行任何範例或掛鉤。（Thomas Stratmann、Myron Marston）
• 在 RSpec 產生的 spec_helper.rb 檔案中，記錄配置選項和預設值。（Parker Selbert）
• 讓產生的範例群組類別具有從 docstring 衍生的易讀名稱，而不是像「Nested_2」之類的名稱。（Myron Marston）
• 避免在隨機化範例時影響使用者程式碼的隨機化，以便使用者可以依賴其自己的種子運作。（Travis Herrick）

棄用

• treat_symbols_as_metadata_keys_with_true_values 已棄用，並且現在不再具有任何影響，因為它啟用的行為已一律啟用。（Myron Marston）

rspec-mocks 2.99.0.beta1

完整變更記錄

棄用

• 預期使用 lambda 或其他強基數實作來處理具有不符基數的 stub 方法已棄用，並且對它們的支援將在 3.0 中移除。請提供正確數量的引數或使用弱基數實作（具有 splat 或 proc 的方法）。（Jon Rowe）
• 在多個範例中使用相同的測試雙精度實例已棄用。測試雙精度實例僅適用於一個範例。在範例之間一律會重設模擬和 stub；但是，在 2.x 中，as_null_object 狀態未重設，有些使用者依賴此功能來擁有用於多個範例的 null 物件雙精度實例。此行為將在 3.0 中移除。（Myron Marston）
• 當未使用明確設定新的 yield_receiver_to_any_instance_implementation_blocks 配置選項時，使用 any_instance 實作區塊時，會印出詳細的警告，因為 RSpec 3.0 預設為啟用此新功能。（Sam Phippen）

增強功能

• 新增配置選項，將接收器傳回給 any_instance 實作區塊。（Sam Phippen）

rspec-mocks 3.0.0.beta1

完整變更記錄

重大變更

• 如果使用 should_not_receive(...).and_return，則會引發明確錯誤。（Sam Phippen）
• 移除 1.8.6 的變通方法。（Jon Rowe）
• 移除 stub! 和 unstub!。（Sam Phippen）
• 移除 mock(name, methods) 和 stub(name, methods)，保留 double(name, methods) 用於建立測試替身。（Sam Phippen, Michi Huber）
• 移除 any_number_of_times，因為 should_receive(:msg).any_number_of_times 實際上是以模擬物件形式存在的樁件。（Sam Phippen）
• 移除在多個範例中重複使用相同 null-object 測試替身的功能。測試替身設計為僅在一個範例中存在。（Myron Marston）
• 讓 at_least(0) 引發錯誤。（Sam Phippen）
• 移除對 require 'spec/mocks' 的支援，該支援是為了與 RSpec 1 向後相容而保留的。（Myron Marston）
• 提供給 with 的程式碼區塊始終用作實作。（Xavier Shay）
• 在 2.99 版中新增的配置選項，將接收器傳遞給 any_instance 實作區塊，現在預設為「開啟」。（Sam Phippen）

增強功能

• 允許 have_received 匹配器使用程式碼區塊來設定關於參數的進一步期望。（Tim Cowlishaw）
• 提供 instance_double 和 class_double 來建立驗證替身，從 rspec-fire 移植。（Xavier Shay）
• 驗證替身上的 as_null_object 僅回應已定義的方法。（Xavier Shay）
• 提供 object_double 來建立特定物件實例的驗證替身。（Xavier Shay）
• 提供 verify_partial_doubles 配置，在部分模擬上提供類似 object_double 的驗證行為。（Xavier Shay）
• 改善了替身建立的效能，特別是那些具有許多屬性的替身。（Xavier Shay）
• 可以配置用於常數樁件的 transfer_nested_constants 選項的預設值。（Xavier Shay）
• 可以透過 receive_messages(:message => :value) 批量允許或期望訊息。（Jon Rowe）
• allow(Klass.any_instance) 和 expect(Klass.any_instance) 現在會印出警告。這通常是一個錯誤，使用者通常想要的是 allow_any_instance_of 或 expect_any_instance_of。（Sam Phippen）
• 如果底層模組已載入，並且被調用方法的引數數量與實際實作的方法引數數量不符，instance_double 和 class_double 會引發 ArgumentError。（Andy Lindeman）
• 間諜（Spies）現在可以檢查它們的調用順序是否正確。（Jon Rowe）

棄用

• 使用舊的 :should 語法而不明確配置它已被棄用。它將繼續運作，但如果您沒有明確啟用它，則在 RSpec 3 中會發出棄用警告。（Sam Phippen）

錯誤修復

• 修復 and_call_original 以處理涉及單例類別祖先的複雜邊緣情況。（Marc-André Lafortune, Myron Marston）
• 在產生非預期引數的錯誤訊息時，如果 #description 返回 nil 或 ''，則使用 #inspect 而不是 #description，以便您仍然可以獲得有用的訊息。（Nick DeLuca）

rspec-expectations 2.99.0.beta1

完整變更記錄

棄用

• 棄用 have、have_at_least 和 have_at_most。您可以透過 https://github.com/rspec/rspec-collection_matchers 繼續使用這些匹配器，或者您可以使用類似 `expect(your_object.size).to eq(num)` 的方式重寫您的期望。（Hugo Baraúna）
• 當 xyz? 是私有方法時，棄用 be_xyz 謂詞匹配器。（Jon Rowe）
• 棄用 be_true/be_false，改用 be_truthy/be_falsey（用於 Ruby 的條件語義）或 be true/be false（用於精確相等）。（Sam Phippen）
• 棄用從具有錯誤範圍的自訂匹配器呼叫輔助方法。（Myron Marston）
  • def self.foo / extend Helper 可用於新增巨集方法（例如呼叫自訂匹配器 DSL 方法的方法），但不應用於定義從 DSL 區塊內呼叫的輔助方法。
  • def foo / include Helper 則相反：它用於可從 DSL 區塊內呼叫的輔助方法，但不適用於定義巨集。
  • RSpec 2.x 允許以任何方式定義的輔助方法用於任何目的，但 RSpec 3.0 將不允許。

rspec-expectations 3.0.0.beta1

完整變更記錄

重大變更

• 移除對 1.8.6 的明確支援。（Jon Rowe）
• 移除已棄用的 be_close 匹配器，改為使用 be_within。（Sam Phippen）
• 將 be_true 和 be_false 重新命名為 be_truthy 和 be_falsey。（Sam Phippen）
• 讓 expect { }.to_not raise_error(SomeSpecificClass, message)、expect { }.to_not raise_error(SomeSpecificClass) 和 expect { }.to_not raise_error(message) 無效，因為它們容易隱藏失敗。請改用 expect { }.to_not raise_error（不帶引數）。（Sam Phippen）
• 在 RSpec::Matchers.define 區塊中，透過 def self.helper 或 extend HelperModule 提供的輔助方法不再可用於 match 區塊（或任何其他區塊）。請改為 include 您的輔助模組並將輔助方法定義為實例方法。（Myron Marston）

增強功能

• 支援使用 raise_error 匹配器的 do..end 樣式程式碼區塊。（Yuji Nakayama）
• 重寫了自訂匹配器 DSL 以簡化其實作並解決一些問題。（Myron Marston）
• 允許從自訂匹配器 DSL 區塊內提前 return。（Myron Marston）
• 自訂匹配器 DSL 的 chain 現在可以接受程式碼區塊。（Myron Marston）
• 支援透過鏈式 with_message 方法呼叫在 raise_error 匹配器上設定期望。（Sam Phippen）

錯誤修復

• 允許從 DSL 定義的自訂匹配器的 match 區塊內使用 include 和 match 匹配器。（Myron Marston）

棄用

• 使用舊的 :should 語法而不明確配置它已被棄用。它將繼續運作，但如果您沒有明確啟用它，則在 RSpec 3 中會發出棄用警告。（Sam Phippen）

rspec-rails 2.99.0.beta1

完整變更記錄

棄用

• 棄用 autotest 集成，改用 rspec-autotest gem。（Andy Lindeman）

增強功能

• 支援 Rails 4.1 和 Minitest 5。（Patrick Van Stee）

錯誤修復

• 修復當啟用 --warnings 時，控制器規格引發的「warning: instance variable @orig_routes not initialized」（警告：實例變數 @orig_routes 未初始化）。（Andy Lindeman）
• 在可能的情況下，檢查 ActiveRecord 的版本，而不是 Rails 的版本。可以在沒有所有 Rails 的情況下使用 rspec-rails 的某些部分。（Darryl Pogue）
• 明確依賴 activemodel。這允許不引入所有 rails 的函式庫使用 rspec-rails。（John Firebaugh）

rspec-rails 3.0.0.beta1

完整變更記錄

重大變更

• 將 autotest 和 autotest-rails 支援提取到 rspec-autotest gem。（Andy Lindeman）

[^foot_1]：雖然這有一個注意事項：我們只會在您的測試套件按照文件記錄的方式使用 RSpec API 時才將其視為錯誤。Ruby 的動態特性使其可以以我們無法支援的方式使用 RSpec。