Added documentation for rspec matchers

README.rdoc

@@ -162,6 +162,11 @@ NOTE: Post processing will not even *start* if the attachment is not valid
 according to the validations. Your callbacks and processors will *only* be
 called with valid attachments.
 
+==Testing
+
+Paperclip provides rspec-compatible matchers for testing attachments. See the
+documentation on Paperclip::Shoulda::Matchers for more information.
+
 ==Contributing
 
 If you'd like to contribute a feature or bugfix: Thanks! To make sure your

lib/paperclip/matchers.rb

@@ -2,3 +2,32 @@ require 'paperclip/matchers/have_attached_file_matcher'
 require 'paperclip/matchers/validate_attachment_presence_matcher'
 require 'paperclip/matchers/validate_attachment_content_type_matcher'
 require 'paperclip/matchers/validate_attachment_size_matcher'
+
+module Paperclip
+  module Shoulda
+    # Provides rspec-compatible matchers for testing Paperclip attachments.
+    #
+    # In spec_helper.rb, you'll need to require the matchers:
+    #
+    #   require "paperclip/matchers"
+    #
+    # And include the module:
+    #
+    #   Spec::Runner.configure do |config|
+    #     config.include Paperclip::Shoulda::Matchers
+    #   end
+    #
+    # Example:
+    #   describe User do
+    #     it { should have_attached_file(:avatar) }
+    #     it { should validate_attachment_presence(:avatar) }
+    #     it { should validate_attachment_content_type(:avatar).
+    #                   allowing('image/png', 'image/gif').
+    #                   rejecting('text/plain', 'text/xml') }
+    #     it { should validate_attachment_size(:avatar).
+    #                   less_than(2.megabytes) }
+    #   end
+    module Matchers
+    end
+  end
+end

lib/paperclip/matchers/have_attached_file_matcher.rb

 module Paperclip
   module Shoulda
     module Matchers
+      # Ensures that the given instance or class has an attachment with the
+      # given name.
+      #
+      # Example:
+      #   describe User do
+      #     it { should have_attached_file(:avatar) }
+      #   end
       def have_attached_file name
         HaveAttachedFileMatcher.new(name)
       end

lib/paperclip/matchers/validate_attachment_content_type_matcher.rb

 module Paperclip
   module Shoulda
     module Matchers
+      # Ensures that the given instance or class validates the content type of
+      # the given attachment as specified.
+      #
+      # Example:
+      #   describe User do
+      #     it { should validate_attachment_content_type(:icon).
+      #                   allowing('image/png', 'image/gif').
+      #                   rejecting('text/plain', 'text/xml') }
+      #   end
       def validate_attachment_content_type name
         ValidateAttachmentContentTypeMatcher.new(name)
       end

lib/paperclip/matchers/validate_attachment_presence_matcher.rb

 module Paperclip
   module Shoulda
     module Matchers
+      # Ensures that the given instance or class validates the presence of the
+      # given attachment.
+      #
+      # describe User do
+      #   it { should validate_attachment_presence(:avatar) }
+      # end
       def validate_attachment_presence name
         ValidateAttachmentPresenceMatcher.new(name)
       end

lib/paperclip/matchers/validate_attachment_size_matcher.rb

 module Paperclip
   module Shoulda
     module Matchers
+      # Ensures that the given instance or class validates the size of the
+      # given attachment as specified.
+      #
+      # Examples:
+      #   it { should validate_attachment_size(:avatar).
+      #                 less_than(2.megabytes) }
+      #   it { should validate_attachment_size(:icon).
+      #                 greater_than(1024) }
+      #   it { should validate_attachment_size(:icon).
+      #                 in(0..100) }
       def validate_attachment_size name
         ValidateAttachmentSizeMatcher.new(name)
       end