What is the official way to run jest programmatically?

[IgorAufricht]

My question is how to run jest programmatically. There are some examples on the internet:
https://stackoverflow.com/a/30562836/1652273
https://stackoverflow.com/a/33669530/1652273
#3848

All of them reference requiring jest or jest-cli and calling runCLI(), but it does not seem to be documented anywhere (I haven't found anything in the jest docs nor is there any documentation for the jest-cli package).

Is this the official supported way? Thanks.

[IgorAufricht]

I guess my main question is: is the runCli() a part of public API?

For example this commit 200b032 changed the runCli() - it removed the onComplete callback and replaced it with a Promise, which is not reflected in the commit message and/or the changelog.

[thymikee]

I think there's no official way, that's why it's not referenced in the docs and changelog.
Other way to do it would be jest-editor-support package by @orta

@cpojer what do you think about an "officially supported" way of invoking Jest as a node process?
@IgorAufricht would you be interesting in writing about this?

[IgorAufricht]

To add a bit of context - I'm adding jest into our grunt-based build process. I basically have these options:

1. Run jest outside grunt (e.g. the build script could be something like npm run jest && grunt build)
2. Use the deprecated grunt-jest
3. Run jest from grunt as a process (e.g. using grunt-run)
4. Run jest programmatically from a grunt task
   From these options the nicest would be the last one, hence my question.

If there is currently not an official way to run jest from node, then adding it would involve more than just a documentation change (probably some more thinking about the public API, adding tests and documentation, etc.). While I personally think it might be useful to add an official way to run jest programmatically, it's up to the jest maintainers to decide whether to add support for this or not.

@thymikee I'm not entirely sure what you're asking (writing about what?). But yes, I'm happy to help.

[cpojer]

@thymikee yeah, I'm not opposed, Jest already has an API that can be used but it requires people to read the source to understand how it works, so it's not optimal. The other thing is that we may choose to break the API from major to major.

[orta]

FWIW, I'd love this - I think exposing a consistent JS API to run tests in jest-editor-support would mean that jest-x deps APIs can break between majors, but editor-support could provide a facade for whatever has to actually happen under the hood.

[cpojer]

I'm gonna close this because the issue is a question. If you'd like to use Jest's programmatic API, check out the main module of jest-cli. If you'd like it to do things that it doesn't currently do, please send as a well-tested PR that adds or changes behavior.

[tquinlan1992]

const jest = require('jest');

jest.run(argv);

[slavafomin]

I'm also interested in running jest programmatically from node.js, sadly it's not documented anywhere and the API doesn't look very thoughtful for this use case.

[SimenB]

It's not. That's something we want to improve though (although a bit down the priority list at the moment)

[slavafomin]

@SimenB I've just found out that Jest is working pretty fine in this scenario actually, the only problem is the documentation and typings support.

I've posted a small example on how to use Jest in this scenario:
— How to run Jest programmatically in node.js (Jest JavaScript API)

@cpojer Is there an issue where the progress on this feature could be tracked?