feat(wrapper array): Allow negative indices to be passed to .at()

Passing a negative index to .at() lets you retrieve elements by starting from the end of the wrapper
array (i.e. last item is at index -1)

Author: paulgv

docs/api/wrapper-array/at.md

@@ -1,6 +1,7 @@
 ## at
 
 Returns `Wrapper` at `index` passed. Uses zero based numbering (i.e. first item is at index 0).
+If `index` is negative, indexing starts from the last element (i.e. last item is at index -1).
 
 - **Arguments:**
 
@@ -16,6 +17,10 @@ import Foo from './Foo.vue'
 
 const wrapper = shallowMount(Foo)
 const divArray = wrapper.findAll('div')
+
 const secondDiv = divArray.at(1)
-expect(secondDiv.is('p')).toBe(true)
+expect(secondDiv.is('div')).toBe(true)
+
+const lastDiv = divArray.at(-1)
+expect(lastDiv.is('div')).toBe(true)
 ```

packages/test-utils/src/wrapper-array.js

@@ -23,10 +23,13 @@ export default class WrapperArray implements BaseWrapper {
   }
 
   at(index: number): Wrapper | VueWrapper {
-    if (index > this.length - 1) {
-      throwError(`no item exists at ${index}`)
+    const normalizedIndex = index < 0 ? this.length + index : index
+    if (normalizedIndex > this.length - 1 || normalizedIndex < 0) {
+      let error = `no item exists at ${index}`
+      error += index < 0 ? ` (normalized to ${normalizedIndex})` : ''
+      throwError(error)
     }
-    return this.wrappers[index]
+    return this.wrappers[normalizedIndex]
   }
 
   attributes(): void {

test/specs/wrapper-array/at.spec.js

@@ -13,6 +13,19 @@ describeWithShallowAndMount('at', mountingMethod => {
     expect(p.classes()).to.contain('index-1')
   })
 
+  it('returns Wrapper at index from the end when index is negative', () => {
+    const TestComponent = {
+      template: '<div><p class="index-first" /><p class="index-last"/></div>'
+    }
+    const all = mountingMethod(TestComponent).findAll('p')
+    const last = all.at(-1)
+    const first = all.at(-2)
+    expect(last.vnode).to.be.an('object')
+    expect(last.classes()).to.contain('index-last')
+    expect(first.vnode).to.be.an('object')
+    expect(first.classes()).to.contain('index-first')
+  })
+
   it('throws error if no item exists at index', () => {
     const index = 2
     const TestComponent = {
@@ -27,4 +40,19 @@ describeWithShallowAndMount('at', mountingMethod => {
       .to.throw()
       .with.property('message', message)
   })
+
+  it('throws error if no item exists at negative index', () => {
+    const index = -3
+    const TestComponent = {
+      template: '<div><p /><p class="index-1"/></div>'
+    }
+    const message = `[vue-test-utils]: no item exists at -3 (normalized to -1)`
+    expect(() =>
+      mountingMethod(TestComponent)
+        .findAll('p')
+        .at(index)
+    )
+      .to.throw()
+      .with.property('message', message)
+  })
 })