Add docs for NonCaseSwappableValueError

.yardopts

@@ -1,8 +1,10 @@
 --no-private
 --protected
 --readme README.md
---files NEWS.md
 --markup markdown
 --hide-tag return
 --hide-tag param
 -e ./doc_config/yard/setup.rb
+-
+NEWS.md
+docs/**/*.md

docs/errors/NonCaseSwappableValueError.md

@@ -0,0 +1,111 @@
+# @title NonCaseSwappableValueError
+
+# NonCaseSwappableValueError
+
+This error is raised when using `validate_uniqueness_of`. This matcher, of
+course, tests that an attribute disallows a non-unique value -- and what
+constitutes as "unique" depends on whether the case-sensitivity of that value
+matters. If it does matter -- meaning that the uniqueness validation in your
+model isn't using `case_sensitive: false` and you haven't qualified the matcher
+with `case_insensitive` -- then the matcher will run the following test:
+
+> Creating first a record with a value of "A":
+>
+> * A new record with a value of "A" should not be valid (failing the uniqueness
+>  validation)
+> * A new record with a value of "a" should be valid
+
+The test value we're using is in this case "A", and this is what the matcher
+will use if an existing record is not already present in the database. But if
+a record already exists, then the matcher will use it as comparison -- it will
+read the attribute under test off of the record and use its value. So a better
+example might be:
+
+> Given an existing record with a value:
+>
+> * A new record with the same value should not be valid (failing the uniqueness
+>  validation)
+> * A new record with the same value, but where the case is swapped (using
+>  String#swapcase), should be valid
+
+Now, what happens if an existing record is there, but the value being used is
+not one whose case can be swapped, such as `"123"` or `"{-#%}"`? Then the second
+assertion cannot be made effectively.
+
+So this is why you're getting this exception. What can you do about it? As the
+error message explains, you have two options:
+
+1. If you want the uniqueness validation in the model to operate
+ case-sensitively and you didn't mean to use a non-case-swappable value,
+ then you need to provide an existing record with a different value, one that
+ contains alpha characters. Here's an example:
+
+  # Model
+  class User < ActiveRecord::Base
+  validates_uniqueness_of :username
+  end
+
+  # RSpec
+  describe User do
+  context "validations" do
+  subject do
+  # Note that "123" == "123".swapcase. This is a problem!
+  User.new(username: "123")
+  end
+
+  it do
+  # So you can either override it like this, or just fix the subject.
+  user = User.create!(username: "john123")
+  expect(user).to validate_uniqueness_of(:username)
+  end
+  end
+  end
+
+  # Minitest (Shoulda)
+  class UserTest < ActiveSupport::TestCase
+  context "validations" do
+  subject do
+  # Note that "123" == "123".swapcase. This is a problem!
+  User.new(username: "123")
+  end
+
+  should "validate uniqueness of :username" do
+  # So you can either override it like this, or just fix the subject.
+  user = User.create!(username: "john123")
+  assert_accepts validate_uniqueness_of(:username), record
+  end
+  end
+  end
+
+2. If you don't want the uniqueness validation to operate case-sensitively,
+ then you need to add `case_sensitive: false` to the validation and add
+ `case_insensitive` to the matcher:
+
+  # Model
+  class User < ActiveRecord::Base
+  validates_uniqueness_of :username, case_sensitive: false
+  end
+  
+  # RSpec
+  describe User do
+  context "validations" do
+  subject do
+  # Note that "123" == "123".swapcase, but it's okay
+  User.new(username: "123")
+  end
+
+  it { should validate_uniqueness_of(:username).case_insensitive }
+  end
+  end
+  
+  # Minitest (Shoulda)
+  class UserTest < ActiveSupport::TestCase
+  context "validations" do
+  subject do
+  # Note that "123" == "123".swapcase, but it's okay
+  User.new(username: "123")
+  end
+
+  should validate_uniqueness_of(:username).case_insensitive
+  end
+  end