feat: support custom test sequencer

[9aoy]

Motivation

Rstest currently determines test execution order internally. Some projects need deterministic or project-specific scheduling beyond the built-in behavior, for example:

• run recently failed tests first to shorten feedback loops;
• prioritize faster or more critical test files;
• shard or group tests according to custom metadata;
• keep compatibility with existing Jest/Vitest migration workflows that already rely on custom sequencing.

Supporting a custom test sequencer would make Rstest more flexible for large repositories and advanced CI workflows.

Proposal

Add a user-facing configuration option that lets users provide a custom test sequencer module.

Possible API shape:

// rstest.config.ts
export default defineConfig({
  sequence: {
    sequencer: './test-sequencer.ts',
  },
});

The sequencer module could export a class or function that receives discovered test files and returns them in the desired order:

export default class CustomSequencer {
  sort(files: TestFile[]): TestFile[] | Promise<TestFile[]> {
    return files.sort((a, b) => a.path.localeCompare(b.path));
  }
}

Exact naming and shape can follow existing Rstest configuration conventions.

Requirements

• Allow users to configure a custom sequencer from the top-level sequence config in rstest.config.*.
• Load ESM/TypeScript config-compatible sequencer modules consistently with other user-provided modules.
• Provide type definitions for the sequencer API.
• Preserve current default ordering when no custom sequencer is configured.
• Surface clear errors when the configured sequencer cannot be loaded or returns invalid data.
• Ensure the feature works with parallel execution and, if applicable, browser mode.
• Document the sequence.sequencer option and expected sequencer contract.

Test coverage

• Unit tests for default behavior and custom sorting.
• Error cases for invalid module path/export/return value.
• Integration or e2e coverage for using a custom sequencer from config.

Prior art

Jest exposes testSequencer for similar use cases. Rstest does not need to match Jest exactly, but supporting a comparable extension point would help migration and large-monorepo workflows.