feat: add toIncludeCaseInsensitive matcher

.changeset/blue-sheep-run.md

@@ -0,0 +1,5 @@
+---
+'jest-extended': minor
+---
+
+Introduce new matcher `toIncludeCaseInsensitive`

.gitignore

@@ -8,3 +8,4 @@ coverage
 .vs
 .vscode
 package-lock.json
+yarn.lock

src/matchers/index.js

@@ -53,6 +53,7 @@ export { toHaveBeenCalledBefore } from './toHaveBeenCalledBefore';
 export { toHaveBeenCalledOnce } from './toHaveBeenCalledOnce';
 export { toHaveBeenCalledExactlyOnceWith } from './toHaveBeenCalledExactlyOnceWith';
 export { toInclude } from './toInclude';
+export { toIncludeCaseInsensitive } from './toIncludeCaseInsensitive';
 export { toIncludeAllMembers } from './toIncludeAllMembers';
 export { toIncludeAllPartialMembers } from './toIncludeAllPartialMembers';
 export { toIncludeAnyMembers } from './toIncludeAnyMembers';

src/matchers/toIncludeCaseInsensitive.js

@@ -0,0 +1,23 @@
+export function toIncludeCaseInsensitive(actual, expected) {
+  const { printReceived, printExpected, matcherHint } = this.utils;
+
+  const pass = String(actual).toLocaleLowerCase().includes(String(expected).toLocaleLowerCase());
+
+  return {
+    pass,
+    message: () =>
+      pass
+        ? matcherHint('.not.toIncludeCaseInsensitive') +
+          '\n\n' +
+          'Expected string to not include while ignoring case:\n' +
+          `  ${printExpected(expected)}\n` +
+          'Received:\n' +
+          `  ${printReceived(actual)}`
+        : matcherHint('.toIncludeCaseInsensitive') +
+          '\n\n' +
+          'Expected string to include while ignoring case:\n' +
+          `  ${printExpected(expected)}\n` +
+          'Received:\n' +
+          `  ${printReceived(actual)}`,
+  };
+}

test/matchers/__snapshots__/toIncludeCaseInsensitive.test.js.snap

@@ -0,0 +1,28 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`.not.toIncludeCaseInsensitive fails when a string does have a given substring 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).not.toIncludeCaseInsensitive(</intensity><green>expected</color><dim>)</intensity>
+
+Expected string to not include while ignoring case:
+  <green>"ell"</color>
+Received:
+  <red>"hello world"</color>"
+`;
+
+exports[`.toIncludeCaseInsensitive fails if string is not included despite case 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toIncludeCaseInsensitive(</intensity><green>expected</color><dim>)</intensity>
+
+Expected string to include while ignoring case:
+  <green>"bbbb"</color>
+Received:
+  <red>"aaaa"</color>"
+`;
+
+exports[`.toIncludeCaseInsensitive passes if string is included despite case 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toIncludeCaseInsensitive(</intensity><green>expected</color><dim>)</intensity>
+
+Expected string to include while ignoring case:
+  <green>"bbbb"</color>
+Received:
+  <red>"aaaa"</color>"
+`;

test/matchers/toIncludeCaseInsensitive.test.js

@@ -0,0 +1,29 @@
+import * as matcher from 'src/matchers/toIncludeCaseInsensitive';
+
+expect.extend(matcher);
+
+describe('.toIncludeCaseInsensitive', () => {
+  test('passes if string is included despite case', () => {
+    expect('a').toIncludeCaseInsensitive('A');
+    expect('aAA').toIncludeCaseInsensitive('aa');
+    expect('hello world').toIncludeCaseInsensitive('ell');
+    expect('HELLO world').toIncludeCaseInsensitive('ell');
+    expect('hello WORLD').toIncludeCaseInsensitive('ELL');
+    expect('HELLO WORLD').toIncludeCaseInsensitive('ELL');
+    expect(() => expect('aaaa').toIncludeCaseInsensitive('bbbb')).toThrowErrorMatchingSnapshot();
+  });
+
+  test('fails if string is not included despite case', () => {
+    expect(() => expect('aaaa').toIncludeCaseInsensitive('bbbb')).toThrowErrorMatchingSnapshot();
+  });
+});
+
+describe('.not.toIncludeCaseInsensitive', () => {
+  test('passes when a string does not have a given substring', () => {
+    expect('hello world').not.toIncludeCaseInsensitive('bob');
+  });
+
+  test('fails when a string does have a given substring', () => {
+    expect(() => expect('hello world').not.toIncludeCaseInsensitive('ell')).toThrowErrorMatchingSnapshot();
+  });
+});

types/index.d.ts

@@ -366,6 +366,13 @@ interface CustomMatchers<R> extends Record<string, any> {
    */
   toInclude(substring: string): R;
 
+  /**
+   * Use `.toIncludeCaseInsensitive` when checking if a `String` includes the given `String` substring, despite case.
+   *
+   * @param {String} substring
+   */
+  toIncludeCaseInsensitive(substring: string): R;
+
   /**
    * Use `.toIncludeRepeated` when checking if a `String` includes the given `String` substring the correct number of times.
    *

website/docs/matchers/String.mdx

@@ -87,6 +87,20 @@ Use `.toInclude` when checking if a `String` includes the given `String` substri
 });`}
 </TestFile>
 
+### .toIncludeCaseInsensitive(substring)
+
+Use `.toIncludeCaseInsensitive` when checking if a `String` includes the given `String` substring, despite case.
+
+<TestFile name="toIncludeCaseInsensitive">
+  {`test('passes if string is included despite case', () => {
+  expect('hello world').toIncludeCaseInsensitive('ell');
+  expect('HELLO world').toIncludeCaseInsensitive('ell');
+  expect('hello WORLD').toIncludeCaseInsensitive('ELL');
+  expect('HELLO WORLD').toIncludeCaseInsensitive('ELL');
+  expect('hello world').not.toIncludeCaseInsensitive('bob');
+});`}
+</TestFile>
+
 ### .toIncludeRepeated(substring, times)
 
 Use `.toIncludeRepeated` when checking if a `String` includes the given `String` substring the correct number of times.

website/docs/matchers/index.md

@@ -98,6 +98,7 @@ sidebar_position: 1
 - [.toStartWith(prefix)](/docs/matchers/string/#tostartwithprefix)
 - [.toEndWith(suffix)](/docs/matchers/string/#toendwithsuffix)
 - [.toInclude(substring)](/docs/matchers/string/#toincludesubstring)
+- [.toIncludeCaseInsensitive(substring)](/docs/matchers/string/#toIncludeCaseInsensitivesubstring)
 - [.toIncludeRepeated(substring, times)](/docs/matchers/string/#toincluderepeatedsubstring-times)
 - [.toIncludeMultiple([substring])](/docs/matchers/string/#toincludemultiplesubstring)
 - [.toEqualIgnoringWhitespace(string)](/docs/matchers/string/#toequalignoringwhitespacestring)