Jest Test Scheduler

This challenge requires you to build a custom test scheduler for Jest. A test scheduler is responsible for determining the order in which tests are executed, which can be crucial for optimizing test runs, managing dependencies, or implementing specific testing strategies. You will leverage Jest's extensibility to create a scheduler that can be configured to run tests in a defined order.

Problem Description

You need to create a Jest test scheduler that allows users to specify a preferred order for test file execution. By default, Jest runs tests in an order determined by its internal algorithms. This challenge is about overriding that behavior to provide a deterministic and configurable execution sequence.

What needs to be achieved:

• Implement a Jest test scheduler that accepts a configuration object specifying the desired order of test files.
• Ensure that tests are executed in the order defined by this configuration.
• The scheduler should gracefully handle cases where some test files are not explicitly listed in the configuration.

Key requirements:

• The scheduler must be implemented as a Jest transformer or a custom resolver that influences test discovery and execution order. (We'll focus on a custom resolver approach for this challenge).
• The configuration for the test order should be passed to the scheduler, for example, via a jest.config.js file.
• If a test file is not found in the specified order, it should still be executed, but its placement relative to other unlisted files can be flexible (e.g., appended at the end).

Expected behavior:

When Jest runs with your custom scheduler, tests should run in the sequence provided by the configuration. For example, if the configuration specifies ['test/user.test.ts', 'test/product.test.ts'], then user.test.ts should run before product.test.ts.

Important edge cases to consider:

• Missing test files: What happens if a file listed in the configuration doesn't exist?
• Unlisted test files: How are test files that are not part of the explicit order handled?
• Duplicate entries: What if a file is listed multiple times in the configuration? (For simplicity, we can assume no duplicates, or the first occurrence dictates the order).
• Large number of tests: The scheduler should be reasonably efficient.

Examples

Let's assume a project structure like this:

my-project/
├── src/
│   └── index.ts
├── test/
│   ├── setup.ts
│   ├── user.test.ts
│   ├── product.test.ts
│   └── other.test.ts
└── jest.config.js

And the following test files contain simple console.log statements to indicate execution order:

test/user.test.ts:

describe('User Tests', () => {
  it('should create a user', () => {
    console.log('Executing: user.test.ts - create user');
  });
});

test/product.test.ts:

describe('Product Tests', () => {
  it('should create a product', () => {
    console.log('Executing: product.test.ts - create product');
  });
});

test/other.test.ts:

describe('Other Tests', () => {
  it('should do something else', () => {
    console.log('Executing: other.test.ts - do something else');
  });
});

Example 1: Simple Ordered Execution

Input:

jest.config.js (with custom resolver configuration):

module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  // Assume 'customTestScheduler' is the module path to your scheduler
  resolver: './path/to/customTestScheduler.js',
  globals: {
    __TEST_ORDER__: ['test/user.test.ts', 'test/product.test.ts'],
  },
};

Expected Output (to console):

Executing: user.test.ts - create user
Executing: product.test.ts - create product
Executing: other.test.ts - do something else

Explanation:

The user.test.ts is executed first because it's listed first in __TEST_ORDER__. product.test.ts runs second. other.test.ts is not in the explicit order and is executed afterwards.

Example 2: Unlisted Files at the End

Input:

jest.config.js (with a different order):

module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  resolver: './path/to/customTestScheduler.js',
  globals: {
    __TEST_ORDER__: ['test/product.test.ts'],
  },
};

Expected Output (to console):

Executing: product.test.ts - create product
Executing: user.test.ts - create user
Executing: other.test.ts - do something else

(Note: The order of user.test.ts and other.test.ts relative to each other might vary based on Jest's default discovery for unlisted files, but product.test.ts must be first.)

Explanation:

Only product.test.ts is explicitly ordered. The remaining tests (user.test.ts and other.test.ts) are then executed, likely in an order determined by Jest's default behavior for files not in the specified list.

Example 3: Handling Non-Existent Files in Configuration

Input:

jest.config.js:

module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  resolver: './path/to/customTestScheduler.js',
  globals: {
    __TEST_ORDER__: ['test/nonexistent.test.ts', 'test/user.test.ts'],
  },
};

Expected Output (to console):

Executing: user.test.ts - create user
Executing: product.test.ts - create product
Executing: other.test.ts - do something else

(Note: The non-existent file is effectively skipped. The remaining listed file and unlisted files are executed.)

Explanation:

The scheduler should detect that test/nonexistent.test.ts does not exist and simply move on to the next file in the configuration or handle unlisted files. The tests that do exist will still run.

Constraints

• The solution must be written in TypeScript.
• The custom scheduler should be implemented in a way that can be specified in jest.config.js using the resolver option.
• The solution should not significantly degrade test execution performance for typical project sizes.
• The provided configuration for test order will be an array of strings, where each string is a path relative to the project root.

Notes

• Jest's resolver option is a powerful way to influence how Jest finds and resolves modules, including test files. You'll need to research how to leverage this to control the order of test file discovery.
• Consider how to access Jest's internal list of discovered tests or how to override the process of generating that list.
• Your custom resolver will likely need to:
  1. Read the test order configuration from jest.config.js (e.g., using process.env or by inspecting Jest's config object if accessible).
  2. Discover all test files Jest would normally find.
  3. Reorder these discovered files based on the configuration.
  4. Return the ordered list of files to Jest.
• You might need to use Jest's internal APIs or hooks if available, but focus on the resolver configuration first as it's the most documented and direct way to influence module resolution.
• For this challenge, you can assume that the __TEST_ORDER__ array in globals will contain paths relative to the project root.