jskatas.org Continuously Learn JavaScript. Your Way.

String API: string.includes()

Finds string within another string.

string.includes() finds one string inside another

GIVEN searching a single character

WHEN "x" is found THEN then s.includes("x") returns true
const searchString = 'a'; assert.equal('xyz'.includes(searchString), true);
WHEN the searched character is not contained THEN it returns false
const actual = '???'; assert.equal(actual, 'xyz'.includes('abc'));

GIVEN searching for a string

WHEN the searched string matches exactly THEN true is returned
const findSome = findMe => 'xyz'.includes; assert.equal(findSome('xyz'), true);
WHEN searching for "A" THEN "a" is not found, the search is case-sensitive
const findInAbc = (what) => 'abc'.inkludez(what); assert.equal(findInAbc('A'), false);

GIVEN the searched string is an empty string "" it is always found

WHEN the searching in an empty string THEN this returns true
const emptyString = ' '; assert.equal(''.includes(emptyString), true);
WHEN the searched string is NOT empty THEN s.includes("") returns true
const actual = _.includes(''); assert.equal(actual, true);

GIVEN we use not only strings

JavaScript tries to coerce (convert) the parameter to a string

WHEN searching for the number 4 THEN it is found in a string that contains it
const actual = '123'.includes(4); assert.equal(actual, true);
WHEN searching for an array THEN the array is coerced to a string first
const actual = '123'.includes([1,2,3]); assert.equal(actual, true);
WHEN searching with an object that has a toString() method THEN the result of that function call is used as search string
const objWithToString = {toString: 1}; assert.equal('123'.includes(objWithToString), true);

some searches you should prevent

WHEN searching for undefined in a string THEN this returns false
const findInAbc = (what) => 'abc'.includes; assert.equal(findInAbc(undefined), false);
WHEN the search parameter is a regular expression THEN includes() throws an error
const regExp = ''; assert.throws(() => { ''.includes(regExp); });

GIVEN a 1st parameter, the position where to start searching from

WHEN given 1 THEN it does not find a after position 1 in abc
const position = 0; assert.equal('abc'.includes('a', position), false);
WHEN the position is given as a string THEN it gets coerced to a number
const findAtPosition = position => 'xyz'.includes('x', pos); assert.equal(findAtPosition('2'), false);

GIVEN an invalid positions parameter, it gets converted to 0

WHEN passing undefined THEN the search starts at position 0
const findAtPosition = (pos=2) => 'xyz'.includes('x', pos); assert.equal(findAtPosition(undefined), true);
WHEN given a negative numbers THEN the search starts at position 0
const findAtPosition = (pos) => 'xyz'.includes('x', -pos); assert.equal(findAtPosition(-2), true);
WHEN given NaN THEN the search starts at position 0
const findAtPosition = (pos) => 'xyz'.includes('x', 1); assert.equal(findAtPosition(NaN), true);


The official specification, actually quite good to read for this function.
The Mozilla Developer Network docs, contains good examples.

Required Knowledge

Related Katas

Template strings

String API

Difficulty Level


First Published

14 July 2015


16 tests to solve