Implement collection singleton matcher

Implement #732

(cherry picked from commit 04d09f5)

kotlintest-assertions/src/main/kotlin/io/kotlintest/matchers/collections/matchers.kt

@@ -1,7 +1,18 @@
 package io.kotlintest.matchers.collections
 
-import io.kotlintest.*
-import io.kotlintest.matchers.*
+import io.kotlintest.Matcher
+import io.kotlintest.Result
+import io.kotlintest.matchers.beEmpty
+import io.kotlintest.matchers.beSorted
+import io.kotlintest.matchers.containAll
+import io.kotlintest.matchers.containsInOrder
+import io.kotlintest.matchers.haveSize
+import io.kotlintest.matchers.singleElement
+import io.kotlintest.neverNullMatcher
+import io.kotlintest.should
+import io.kotlintest.shouldHave
+import io.kotlintest.shouldNot
+import io.kotlintest.stringRepr
 
 fun <T> Collection<T>.shouldContainOnlyNulls() = this should containOnlyNulls()
 fun <T> Collection<T>.shouldNotContainOnlyNulls() = this shouldNot containOnlyNulls()
@@ -182,6 +193,41 @@ infix fun <T> Collection<T>.shouldNotHaveSingleElement(t: T) = this shouldNot si
 infix fun <T> Collection<T>.shouldHaveSize(size: Int) = this should haveSize(size)
 infix fun <T> Collection<T>.shouldNotHaveSize(size: Int) = this shouldNot haveSize(size)
 
+/**
+ * Verifies this collection contains only one element
+ *
+ * This assertion is an alias to `collection shouldHaveSize 1`. This will pass if the collection have exactly one element
+ * (definition of a Singleton Collection)
+ *
+ * ```
+ * listOf(1).shouldBeSingleton()    // Assertion passes
+ * listOf(1, 2).shouldBeSingleton() // Assertion fails
+ * ```
+ *
+ * @see [shouldHaveSize]
+ * @see [shouldNotBeSingleton]
+ * @see [shouldHaveSingleElement]
+ */
+fun <T> Collection<T>.shouldBeSingleton() = this shouldHaveSize 1
+
+/**
+ * Verifies this collection doesn't contain only one element
+ *
+ * This assertion is an alias to `collection shouldNotHaveSize 1`. This will pass if the collection doesn't have exactly one element
+ * (definition of a Singleton Collection)
+ *
+ * ```
+ * listOf(1, 2).shouldNotBeSingleton()    // Assertion passes
+ * listOf<Int>().shouldNotBeSingleton()   // Assertion passes
+ * listOf(1).shouldNotBeSingleton()       // Assertion fails
+ * ```
+ *
+ * @see [shouldNotHaveSize]
+ * @see [shouldBeSingleton]
+ * @see [shouldNotHaveSingleElement]
+ */
+fun <T> Collection<T>.shouldNotBeSingleton() = this shouldNotHaveSize 1
+
 infix fun <T, U> Collection<T>.shouldBeLargerThan(other: Collection<U>) = this should beLargerThan(other)
 fun <T, U> beLargerThan(other: Collection<U>) = object : Matcher<Collection<T>> {
   override fun test(value: Collection<T>) = Result(

kotlintest-tests/kotlintest-tests-core/src/test/kotlin/com/sksamuel/kotlintest/matchers/collections/CollectionMatchersTest.kt

@@ -1,8 +1,73 @@
 package com.sksamuel.kotlintest.matchers.collections
 
-import io.kotlintest.*
-import io.kotlintest.matchers.*
-import io.kotlintest.matchers.collections.*
+import io.kotlintest.matchers.beEmpty
+import io.kotlintest.matchers.collections.atLeastSize
+import io.kotlintest.matchers.collections.atMostSize
+import io.kotlintest.matchers.collections.beLargerThan
+import io.kotlintest.matchers.collections.beSameSizeAs
+import io.kotlintest.matchers.collections.beSmallerThan
+import io.kotlintest.matchers.collections.contain
+import io.kotlintest.matchers.collections.containDuplicates
+import io.kotlintest.matchers.collections.containExactly
+import io.kotlintest.matchers.collections.containExactlyInAnyOrder
+import io.kotlintest.matchers.collections.containNoNulls
+import io.kotlintest.matchers.collections.containNull
+import io.kotlintest.matchers.collections.containOnlyNulls
+import io.kotlintest.matchers.collections.endWith
+import io.kotlintest.matchers.collections.haveElementAt
+import io.kotlintest.matchers.collections.shouldBeEmpty
+import io.kotlintest.matchers.collections.shouldBeLargerThan
+import io.kotlintest.matchers.collections.shouldBeOneOf
+import io.kotlintest.matchers.collections.shouldBeSameSizeAs
+import io.kotlintest.matchers.collections.shouldBeSingleton
+import io.kotlintest.matchers.collections.shouldBeSmallerThan
+import io.kotlintest.matchers.collections.shouldBeSorted
+import io.kotlintest.matchers.collections.shouldBeSortedWith
+import io.kotlintest.matchers.collections.shouldContain
+import io.kotlintest.matchers.collections.shouldContainAll
+import io.kotlintest.matchers.collections.shouldContainDuplicates
+import io.kotlintest.matchers.collections.shouldContainExactly
+import io.kotlintest.matchers.collections.shouldContainExactlyInAnyOrder
+import io.kotlintest.matchers.collections.shouldContainNoNulls
+import io.kotlintest.matchers.collections.shouldContainNull
+import io.kotlintest.matchers.collections.shouldContainOnlyNulls
+import io.kotlintest.matchers.collections.shouldEndWith
+import io.kotlintest.matchers.collections.shouldExist
+import io.kotlintest.matchers.collections.shouldHaveAtLeastSize
+import io.kotlintest.matchers.collections.shouldHaveAtMostSize
+import io.kotlintest.matchers.collections.shouldHaveElementAt
+import io.kotlintest.matchers.collections.shouldHaveSingleElement
+import io.kotlintest.matchers.collections.shouldHaveSize
+import io.kotlintest.matchers.collections.shouldNotBeEmpty
+import io.kotlintest.matchers.collections.shouldNotBeOneOf
+import io.kotlintest.matchers.collections.shouldNotBeSingleton
+import io.kotlintest.matchers.collections.shouldNotBeSorted
+import io.kotlintest.matchers.collections.shouldNotBeSortedWith
+import io.kotlintest.matchers.collections.shouldNotContainAll
+import io.kotlintest.matchers.collections.shouldNotContainDuplicates
+import io.kotlintest.matchers.collections.shouldNotContainExactly
+import io.kotlintest.matchers.collections.shouldNotContainExactlyInAnyOrder
+import io.kotlintest.matchers.collections.shouldNotContainNoNulls
+import io.kotlintest.matchers.collections.shouldNotContainNull
+import io.kotlintest.matchers.collections.shouldNotContainOnlyNulls
+import io.kotlintest.matchers.collections.shouldNotEndWith
+import io.kotlintest.matchers.collections.shouldNotHaveElementAt
+import io.kotlintest.matchers.collections.shouldNotHaveSize
+import io.kotlintest.matchers.collections.shouldNotStartWith
+import io.kotlintest.matchers.collections.shouldStartWith
+import io.kotlintest.matchers.collections.startWith
+import io.kotlintest.matchers.containAll
+import io.kotlintest.matchers.containsInOrder
+import io.kotlintest.matchers.haveSize
+import io.kotlintest.matchers.singleElement
+import io.kotlintest.matchers.sorted
+import io.kotlintest.should
+import io.kotlintest.shouldBe
+import io.kotlintest.shouldFail
+import io.kotlintest.shouldHave
+import io.kotlintest.shouldNot
+import io.kotlintest.shouldNotHave
+import io.kotlintest.shouldThrow
 import io.kotlintest.specs.WordSpec
 import java.util.*
 
@@ -208,6 +273,37 @@ class CollectionMatchersTest : WordSpec() {
 
       }
     }
+
+    "should be singleton" should {
+      "pass for collection with a single element" {
+        listOf(1).shouldBeSingleton()
+      }
+
+      "fail for collection with 0 elements" {
+        shouldThrow<AssertionError> { listOf<Int>().shouldBeSingleton() }
+      }
+
+      "fail for collection with 2+ elements" {
+        shouldThrow<AssertionError> { listOf(1, 2).shouldBeSingleton() }
+        shouldThrow<AssertionError> { listOf(1, 2, 3, 4).shouldBeSingleton() }
+      }
+    }
+
+    "should not be singleton" should {
+      "pass for collection with 0 elements" {
+        listOf<Int>().shouldNotBeSingleton()
+      }
+
+      "pass for collection with 2+ elements" {
+        listOf(1, 2).shouldNotBeSingleton()
+        listOf(1, 2, 3, 4).shouldNotBeSingleton()
+      }
+
+      "fail for collection with a single element" {
+        shouldThrow<AssertionError> { listOf(1).shouldNotBeSingleton() }
+
+      }
+    }
 
     "shouldExist" should {
       "test that a collection contains at least one element that matches a predicate" {