How to run tests from the command line in JavaScript

When you’re working with testing frameworks or any build tools, the command line is where everything converges. It’s your single source of truth. No fancy GUIs that try to hide complexity, no magical buttons that do “the right thing.” Just the raw commands that tell your machine exactly what to do.

This is where repeatability lives. If you can’t run the exact same command twice with the same environment and get the same results, you’re in trouble. Your teammates, your CI server, and even your future self depend on this. So always start with the command line – it’s your contract with the machine.

For example, if you’re using jest, you want to be able to run:

npx jest --coverage --runInBand

and know exactly what happens. No surprises. --coverage tells jest to collect code coverage metrics, and --runInBand forces it to run tests serially instead of in parallel, which is useful when debugging or when you want deterministic output.

Think about this from a build server perspective too. Your CI pipeline should invoke the exact same command line commands that you run locally. If you type npm test and it runs jest --coverage --runInBand behind the scenes, make sure that’s documented and consistent. Nothing worse than a build passing locally but failing on CI because someone ran a different command.

Sometimes you’ll want to add environment variables inline to tweak behavior without changing code. For instance:

CI=true jest --coverage --runInBand

Here, CI=true may cause jest to alter its output formatting to be more machine-readable, which helps for automated parsing in logs.

Another point: If your test runner spits out huge logs or colors that break your terminal, the command line is where you can control that. Flags like --silent, --verbose, or --no-color are not just cosmetic; they make debugging easier and logs more parseable.

It’s tempting to rely on IDE integrations or GUI test runners because they’re convenient, but those are layers of abstraction. They can introduce subtle differences or mask failures. When your tests fail on CI but not in the IDE, 99% of the time it’s because your IDE runs things differently than your command line.

Here’s a minimal example of running mocha tests with environment variables and reporter options, all from the command line:

REPORTER=spec NODE_ENV=test mocha --timeout 5000 --exit

This sets the test environment, chooses a reporter style, increases the timeout, and ensures Mocha exits after running tests (because sometimes it hangs when async operations are left open).

Master the command line first, script it into your package.json with npm scripts, and your workflow becomes bulletproof. For example, add this to your package.json:

"scripts": {
  "test": "jest --coverage --runInBand",
  "test:ci": "CI=true npm test"
}

Now anyone can run npm test for local development or npm run test:ci for CI environments, guaranteeing consistent behavior.

Remember, the command line is not just a tool; it’s the language you speak with your computer. If you can’t express your intent clearly here, you’re building on shaky ground. Your entire testing ecosystem depends on this clarity and repeatability.

So when you get a new project or library, the first thing you do is figure out exactly how to run the tests from the terminal. If that’s not obvious, you fix it. Because if it’s not easy to run tests from the command line, it won’t get done regularly.

And you don’t have to memorize every flag. Wrap those commands in scripts, write a README, make it as simple as npm test. But never lose sight of the fact that under the hood, it’s the command line that runs the show. Every test run starts and ends there. Without that, you’re flying blind.

Next time you look at a failing test, check the command line invocation. What flags did you add? What environment variables are set? What’s different from your teammate’s machine? That’s where the truth lives. The command line won’t lie.

And if you want to automate running tests on file changes, don’t rely on some fancy watcher UI. Use something like nodemon or watchman and hook it directly into your command line test runner:

nodemon --watch src --ext js,jsx --exec "npm test"

This way, every file save triggers the exact same npm test command you trust-no surprises, no magic.

At the end of the day, your build and test process is code like any other. Keeping it visible, explicit, and simple means fewer bugs, less frustration, and more time actually writing software instead of debugging why tests won’t run consistently.

So don’t shy away from the terminal. Embrace it. Make it your single source of truth. Because once you do, your testing workflow becomes bulletproof, and that’s the real win.

Picking your tools is half the battle

Now that you’ve committed to the command line, you have to decide what commands you’re actually going to run. The JavaScript testing landscape is a jungle of frameworks, runners, assertion libraries, and mocking tools. It’s easy to get paralyzed by choice, spending weeks debating the merits of mocha vs. jest vs. ava. This is a classic form of yak shaving. The goal is to test your code, not to build the most theoretically perfect testing toolchain known to man.

The most important decision you’ll make is between a “batteries-included” framework and a modular, build-it-yourself stack. On one side, you have jest. It comes with a test runner, an assertion library, and a powerful mocking system, all in one package. It’s the Toyota Camry of testing frameworks: it’s not flashy, but it’s reliable, gets the job done, and you don’t have to think about it too much.

With Jest, a simple test looks like this. Notice that test, expect, and the matchers like .toBe() are all globally available in your test files. No imports needed.

// userService.test.js
const { findUser } = require('./userService');

test('findUser should retrieve the correct user', () => {
  const user = findUser(1);
  expect(user).toBeDefined();
  expect(user.id).toBe(1);
  expect(user.name).toBe('John Doe');
});

On the other side, you have the modular approach, most famously represented by mocha. Mocha is just a test runner. It gives you a way to structure your tests with describe() and it() blocks, but that’s it. It has no idea how to check if a value is correct. For that, you need to bring your own assertion library, like chai. And if you need to create test doubles (mocks, stubs, spies), you need another library, like sinon.

Here’s the same test, but written with Mocha and Chai. You have to assemble the pieces yourself.

// userService.test.js
const { expect } = require('chai');
const { findUser } = require('./userService');

describe('userService', () => {
  it('findUser should retrieve the correct user', () => {
    const user = findUser(1);
    expect(user).to.not.be.undefined;
    expect(user.id).to.equal(1);
    expect(user.name).to.equal('John Doe');
  });
});

The modular approach gives you flexibility. Don’t like Chai’s expect syntax? Fine, use its should syntax or switch to a different assertion library entirely. The problem is, this flexibility is also a liability. Now every developer on your team has to agree on which pieces to use, and you have to configure them to work together. This is more cognitive overhead and more room for inconsistencies that provide zero business value.

Jest’s all-in-one nature solves this. It makes a lot of decisions for you, and frankly, they’re pretty good decisions. The integrated mocking is a huge productivity win. Let’s say you need to test a function that makes an API call with axios. With Jest, you can mock the axios module with one line of code.

// dataFetcher.test.js
const axios = require('axios');
const { fetchData } = require('./dataFetcher');

jest.mock('axios');

test('fetchData should call the correct endpoint and return data', async () => {
  const mockData = { message: 'Success' };
  axios.get.mockResolvedValue({ data: mockData });

  const result = await fetchData(123);

  expect(axios.get).toHaveBeenCalledWith('/api/data/123');
  expect(result).toEqual(mockData);
});

Look how clean that is. jest.mock('axios') automatically replaces axios with a mock version, and you can then tell any of its methods what to return. Now compare that to the Mocha/Chai/Sinon equivalent. You have to manually create a stub, run your test, and-crucially-restore the original function afterwards. Forgetting to restore your stubs is a common source of bugs where tests bleed state into one another.

// dataFetcher.test.js
const sinon = require('sinon');
const axios = require('axios');
const { expect } = require('chai');
const { fetchData } = require('./dataFetcher');

describe('dataFetcher', () => {
  afterEach(() => {
    sinon.restore(); // Don't forget this!
  });

  it('should call the correct endpoint and return data', async () => {
    const mockData = { message: 'Success' };
    const axiosStub = sinon.stub(axios, 'get').resolves({ data: mockData });

    const result = await fetchData(123);

    expect(axiosStub.calledWith('/api/data/123')).to.be.true;
    expect(result).to.deep.equal(mockData);
  });
});

That afterEach block with sinon.restore() is pure boilerplate, and it’s critical. Jest handles this cleanup for you automatically. For 95% of projects, especially in the React/Node.js ecosystem where it dominates, Jest is the pragmatic choice. You install one package, get a sensible configuration out of the box, and your team can immediately start writing tests instead of debating tooling.

This doesn’t mean other tools are useless. For end-to-end (E2E) testing, where you need to control a real browser, a specialized tool like Cypress or Playwright is vastly superior. They are designed for that specific, complex job. Using Jest for E2E testing is like trying to build a house with a screwdriver. You need the right tool for the job. For unit and integration tests, Jest is your multipurpose power tool. For E2E tests, you need the heavy machinery of Cypress.

The cost of choosing the wrong tool isn’t just a one-time setup fee. It’s a recurring tax on developer productivity. If writing tests is painful because the tools are clunky or confusing, developers will write fewer of them. The goal is to make testing the path of least resistance. Pick a battle-tested, all-in-one framework for your core unit tests, and you remove a whole class of problems that have nothing to do with actually shipping your product.

The anatomy of a single test run

Now that you’ve settled on your testing tool, let’s dive into what actually happens during a single test run. Understanding this “anatomy” helps you troubleshoot failures and optimize your workflow.

At a high level, a test run consists of these phases:

• Setup: The test runner loads your test files, sets up the environment, and prepares any global fixtures or mocks.
• Execution: Each test case is run, assertions are evaluated, and any asynchronous operations are awaited.
• Teardown: Any cleanup is performed, such as restoring mocks, closing database connections, or clearing timers.
• Reporting: Results are collected, formatted, and output to the console or a file.

Let’s look at a Jest example to see these phases in action:

describe('Calculator', () => {
  let calc;

  beforeAll(() => {
    // Setup: runs once before all tests
    calc = new Calculator();
  });

  beforeEach(() => {
    // Setup: runs before each test
    calc.reset();
  });

  afterEach(() => {
    // Teardown: runs after each test
    jest.clearAllMocks();
  });

  afterAll(() => {
    // Teardown: runs once after all tests
    calc = null;
  });

  test('adds numbers correctly', () => {
    const result = calc.add(2, 3);
    expect(result).toBe(5);
  });

  test('subtracts numbers correctly', () => {
    const result = calc.subtract(5, 3);
    expect(result).toBe(2);
  });
});

Here’s what’s going on:

• beforeAll() sets up shared state before any tests run.
• beforeEach() resets state so tests don’t leak into each other.
• afterEach() cleans up mocks or side effects after every test.
• afterAll() tears down global state when all tests finish.

This lifecycle is crucial. If you skip proper setup or teardown, tests will become flaky, order-dependent, or polluted by side effects. The test runner orchestrates this lifecycle automatically, but your job is to write idempotent setup and teardown code.

Another important detail is how asynchronous tests work. Jest supports returning Promises or using async/await. If you forget to do this, your test might pass incorrectly or timeout.

test('fetches user data asynchronously', async () => {
  const data = await fetchUser(1);
  expect(data.id).toBe(1);
});

Notice there’s no callback or done parameter. Jest waits for the Promise to resolve before proceeding. If you mix async patterns or forget to return the Promise, your test runner won’t know when to stop.

Under the hood, the test runner collects all test files matching your pattern (e.g., **/*.test.js), loads them in memory, and executes each test() or it() block in sequence or parallel, depending on configuration. Parallel runs speed things up but can introduce race conditions if tests aren’t isolated.

When you run with --runInBand, Jest forces serial execution, which helps when debugging or dealing with shared resources like databases or file systems.

Coverage collection is another layer. When you run jest --coverage, the runner instruments your source code before executing tests. This means it wraps your code with counters to track which lines, functions, and branches were executed. After the run, it aggregates this data into a report.

Here’s a typical coverage summary after a run:

--------------------|---------|----------|---------|---------|-------------------
File                | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
--------------------|---------|----------|---------|---------|-------------------
All files           |   85.71 |    75.00 |    90.0 |   85.71 |                   
 calculator.js      |     100 |      100 |     100 |     100 |                   
 utils.js           |    75.0 |    50.00 |    80.0 |    75.0 | 12-15, 22          
--------------------|---------|----------|---------|---------|-------------------

Interpreting this report helps you identify untested code paths. You can configure thresholds so that your test run fails if coverage drops below a certain percentage, enforcing discipline.

In CI environments, test runners often emit machine-readable output formats like JUnit XML or JSON. You can configure Jest with reporters:

jest --coverage --json --outputFile=report.json

This allows your CI server to parse results, show test trends, and alert when tests regress.

Finally, watch out for common traps during a test run:

• Tests that depend on global state without resetting it.
• Tests that leave timers or database connections open, causing hangs.
• Flaky tests that pass or fail nondeterministically due to async timing or shared resources.
• Excessive console output that buries relevant failures.

To catch these, add explicit afterEach() cleanup, use timeout flags like --timeout 10000, and keep your test output tidy.

In summary, a test run is more than just “run tests and see green.” It’s a carefully choreographed dance of setup, execution, teardown, and reporting. Mastering this flow means fewer surprises, faster debugging, and a more reliable codebase.

Next up: how to make sure nobody breaks the build again.

Making sure nobody breaks the build again

So you’ve got a great test suite, and everyone on the team knows how to run it from the command line. Fantastic. The very next day, someone pushes a change that breaks the build on the main branch. All work stops. Fingers get pointed. It’s a huge waste of time and morale. The problem isn’t that the developer is lazy or malicious; it’s that your process allows for human error. The solution is to make it impossible to merge broken code. Not difficult, not discouraged, but impossible.

Your first line of defense is to automate checks on the developer’s machine before the code even leaves their computer. This is done with Git hooks, which are scripts that Git executes before or after events like committing or pushing. Managing these hooks manually is a pain, so you use a tool like husky to make it declarative. You add it to your project, and it sets up the hooks for anyone who clones the repository and runs npm install.

First, you install husky and set up a script to initialize it automatically after an install.

npm install husky --save-dev
npm pkg set scripts.prepare="husky install"
npm run prepare

Then, you add a hook. For example, to run your tests before any commit, you create a pre-commit hook.

npx husky add .husky/pre-commit "npm test"

This creates a file at .husky/pre-commit containing the command npm test. Now, when a developer types git commit, Git will first execute npm test. If the tests fail (meaning the script exits with a non-zero status code), Git aborts the commit entirely. The developer is forced to fix the tests before they can even write their commit message. This simple step catches a huge number of errors at the earliest possible moment.

Running the entire test suite on every commit can be slow, though. A better approach is to only run tests and linters on the files that are actually being changed. This is where a tool like lint-staged comes in. It integrates with husky to run commands only against staged files.

You install it and configure it in your package.json. Here, we’re telling it to run ESLint and Jest on any staged JavaScript files. Notice the Jest flags: --bail stops the test run on the first failure, and --findRelatedTests intelligently runs only the tests affected by the changed files, which is much faster.

// package.json
"lint-staged": {
  "*.js": [
    "eslint --fix",
    "jest --bail --findRelatedTests"
  ]
}

Then you update your pre-commit hook to use lint-staged instead of directly calling npm test.

npx husky set .husky/pre-commit "npx lint-staged"

But pre-commit hooks are just a safety net for the developer. They are not a guarantee for the team. Why? Because they are client-side. Any developer can bypass them with a simple git commit --no-verify. They’re a helpful convention, not a hard rule. For a rule, you need a neutral, third-party enforcer: the Continuous Integration (CI) server.

The CI server is the ultimate source of truth. It’s a clean, sterile environment that pulls your code after every push to a branch, installs dependencies from scratch, and runs your tests exactly as you’ve defined them. It doesn’t have weird global packages installed or strange environment variables set. If the tests pass here, you can be confident they actually pass.

Setting this up with a service like GitHub Actions is straightforward. You create a YAML file in your repository that defines the workflow. This workflow tells GitHub what to do whenever code is pushed.

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          cache: 'npm'
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test

This configuration runs on every push or pull request to the main branch. It checks out the code, sets up Node.js, and then runs npm ci followed by npm test. Using npm ci is critical here; it performs a clean install based on the package-lock.json file, ensuring a reproducible build every time, unlike npm install which can install different sub-dependency versions.

Now you have a CI pipeline that reports a pass or fail status on every pull request. The final step is to enforce that status. In your repository settings on GitHub (or GitLab, or Bitbucket), you enable branch protection rules for your main branch. You create a rule that says, “Require status checks to pass before merging.” Then you select the name of your CI job (in the example above, it’s “test”).

This is the lock on the door. With this rule enabled, the “Merge pull request” button on GitHub will be physically disabled if the CI tests fail. It doesn’t matter if you’re the project owner or an admin; the rule applies to everyone. You cannot merge broken code. The only way to proceed is to push a fix to the pull request, which triggers the CI to run again. Only when it passes does the merge button light up.

This combination of local pre-commit hooks and server-side CI with branch protection creates a robust system. The local hooks provide fast feedback to the developer, preventing silly mistakes. The CI server acts as the impartial judge, ensuring every change is validated in a pristine environment. And the branch protection rule is the final gatekeeper, making it mechanically impossible for a regression to enter your main branch. You’ve replaced a process based on hope and discipline with one based on automation and guarantees.