jest-elasticsearch

August 22, 2026 · View on GitHub

Jest preset for running tests with local Elasticsearch

How to mock Elasticsearch with Jest?

Usage

0. Install

pnpm add --save-dev --save-exact @shelf/jest-elasticsearch

1. Create `jest.config.js`

module.exports = {
  preset: '@shelf/jest-elasticsearch'
};

If you have a custom jest.config.js make sure you remove testEnvironment property, otherwise it will conflict with the preset.

2. Create `jest-es-config.js`

module.exports = () => {
  return {
    esVersion: '8.4.0', // ! must be exact version. Ref: https://github.com/elastic/elasticsearch-js .
    // don't be shy to fork our code and update deps to correct.
    clusterName: 'your-cluster-name',
    nodeName: 'your-node-name',
    port: 9200,
    indexes: [
      {
        name: 'your-index-name',
        body: {
          settings: {
            number_of_shards: '1',
            number_of_replicas: '1'
          },
          aliases: {
            'your-alias': {}
          },
          mappings: {
            dynamic: false,
            properties: {
              //here you should paste your mapping
              //Example:
              id: {
                type: 'keyword'
              }
            }
          }
        }
      }
    ]
  };
};

4. PROFIT! Write tests

it();

Monorepo Support

By default the jest-es-config.js is read from cwd directory, but this might not be suitable for monorepos with nested jest projects with nested jest.config.* files nested in subdirectories.

If your jest-es-config.js file is not located at {cwd}/jest-es-config.js or you are using nested jest projects, you can define the environment variable JEST_ELASTICSEARCH_CONFIG with the absolute path of the respective jest-es-config.js file.

Example Using `JEST_ELASTICSEARCH_CONFIG` in nested project

// src/nested/project/jest.config.js
const path = require('path');

// Define path of project level config - extension not required as file will be imported
// via `require(process.env.JEST_ELASTICSEARCH_CONFIG)`
process.env.JEST_ELASTICSEARCH_CONFIG = path.resolve(__dirname, './jest-es-config');

module.exports = {
  preset: '@shelf/jest-elasticsearch'
  displayName: 'nested-project',
};

Troubleshooting

Issue running tests locally - Exception in thread "main"

Exception in thread "main'
java.lang.UnsupportedOperationException The Security Manager is deprecated and will be removed in a future release
at java.base/java.lang.System.setSecurityManager(System. java: 416)
at ora.elasticsearch.bootstrap.Elasticsearch.main(Elasticsearch.iava:71

The main reason why this issue appears is that you have an incompatible java version installed to run elastic locally.

What to do?

List current java versions

$ /usr/libexec/java_home -V

If you see version 18.0.x Add this command to your bashrc, zshrc, etc

$ /usr/libexec/java_home -v 18

If you see no versions or do not have a compatible version installed - Install version 18 https://www.oracle.com/java/technologies/downloads/#java18
Reload the console and check the java version with

$ java -version

Output for proper work

$ java -version
java version "18.0.2.1"
Java(TM) SE Runtime Environment (build 18.0.2.1+1-1)
Java HotSpot(TM) 64-Bit Server VM (build 18.0.2.1+1-1, mixed mode, sharing)

Go to step 2 and set version 18.xx as a default for the shell

Note: If you need to run elastic <= v7.17.x locally, then perform the steps above but for the java version 1.8.xxx

The preset downloads, configures, starts, and stops the requested Elasticsearch version. No separate local Elasticsearch package is required.

Publish

git checkout master
pnpm version
pnpm publish
git push origin master --tags

Create and publish a GitHub release with your tag

Go to repository
Select Releases
Select Draft a new release
Choose a tag, fill title and describe changes
Press a Publish release