glob-sort

A flexible file globbing utility that sorts results by numeric prefixes and custom ordering rules. Perfect for controlling test execution order in Cypress, Playwright, or any test framework.

Features

• Numeric prefix sorting: Automatically sorts folders and files with numeric prefixes (e.g., 01-, 02-)
• Custom sort order: Define ordering rules using strings or regex patterns
• Alphabetical fallback: Falls back to alphabetical sorting when no rules match
• Path-aware: Sorts intelligently at each folder level in the path hierarchy
• TypeScript support: Fully typed with TypeScript
• Zero dependencies: Uses Node.js native fs.promises.glob

Installation

npm install glob-sort

Requirements: Node.js 22+ (uses native fs.promises.glob)

Quick Start

import { sortedGlob } from 'glob-sort'

// With custom ordering rules
const sortedSpecs = await sortedGlob('cypress/tests/**/*.spec.ts', {
  sortOrder: ['setup', 'new', 'edit', 'delete', 'view'],
})

Usage

Example: Cypress

import { sortedGlob } from 'glob-sort'

const specs = await sortedGlob('cypress/tests/**/*.spec*', {
  sortOrder: [
    // run in this order (anything not matching will come after, alphabetically)
    'setup',              // Exact match (case-insensitive)
    /new(?!-special)/i,   // e.g. "new.spec" before "new-special.spec"
    'new',
    'edit',
    /^delete/i,           // starts with "delete"
    /^(?!.*history)/i,    // does not contain "history" (place last in each folder)
    'view',
  ],
})

Example Cypress Configuration

import { defineConfig } from 'cypress'
import { sortedGlobSync } from 'glob-sort'

export default defineConfig({
  e2e: {
    specPattern: sortedGlobSync('cypress/tests/**/*.spec*', {
      sortOrder: ['setup', 'new', 'edit', /^delete.*/, 'view'],
    }),
    // ...other config
  },
})

How It Works

The sorting algorithm applies three levels of ordering at each folder depth:

1. Numeric prefix priority: Folders/files starting with numbers (e.g., 01-, 02-) sort numerically first
2. Custom sort order: Matches against your sortOrder array in the order specified
   • String rules: Match case-insensitively if the string appears anywhere in the filename
   • Regex rules: Test against the filename using the provided pattern
3. Alphabetical fallback: Items that don't match any rules sort alphabetically

Detailed Example

Given this configuration:

const specs = sortedGlobSync('cypress/tests/**/*.spec.ts', {
  sortOrder: [
    'setup',
    'booking',
    'entree',
    'appetizer',
    'user',
    /^(?!.*history)/i,   // Exclude "history" (pushes to end)
    /new(?!-?special)/i, // "new" before "new-special"
    'new',
    'edit',
    'view',
    'print',
  ],
})

01-widget-cards/
    booking-calendar.spec.ts
    entrees.spec.ts
    setup.spec.ts
    upcoming-bookings.spec.tsx
02-table-pages/
    01-entree-dinner/
        entree-dinner-table.spec.ts
        entree-flavors-table.spec.tsx
    02-booking/
        bookings-history-table.spec.ts
        bookings-table.spec.tsx
    customers-table.spec.ts
    entree-lunch-table.spec.ts
    users-table.spec.ts
03-view-pages/
    print-booking.spec.ts
    print-entree-dinner.spec.ts
    setup.spec.ts
    view-appetizer-count.spec.ts
    view-appetizer-supplier.spec.ts
    view-booking.spec.ts
    view-entree-dinner.spec.ts
    view-entree-lunch.spec.ts
    view-user.spec.ts
04-forms/
    booking-form/
        clone-booking.spec.ts
        edit-booking.spec.ts
        new-booking.spec.ts
        new-special-booking.spec.ts
        setup.spec.ts
    entree-dinner/
        edit-entree-dinner.spec.ts
        new-entree-dinner.spec.ts
    entree-lunch/
        edit-entree-lunch.spec.ts
        new-entree-lunch.spec.ts
    user/
        edit-user.spec.ts
    cake-frosting-input.spec.ts
    cake-order-input.spec.ts
misc-components/
    booking-status.spec.ts
    layout.spec.ts
    site-info-button.spec.ts
    user-info-button.spec.ts

01-widget-cards/
+-  setup.spec.tsx
+-  booking-calendar.spec.ts
+-  upcoming-bookings.spec.tsx
+-  entrees.spec.ts
02-table-pages/
    01-entree-dinner/
        entree-dinner-table.spec.ts
        entree-flavors-table.spec.tsx
    02-booking/
+-      bookings-table.spec.tsx
+-      bookings-history-table.spec.ts
+-  entree-lunch-table.spec.ts
+-  users-table.spec.ts
+-  customers-table.spec.ts
03-view-pages/
+-  setup.spec.tsx
+-  view-booking.spec.ts
+-  print-booking.spec.ts
+-  view-entree-dinner.spec.ts
+-  view-entree-lunch.spec.ts
+-  print-entree-dinner.spec.ts
+-  view-appetizer-count.spec.ts
+-  view-appetizer-supplier.spec.ts
    view-user.spec.ts
04-forms/
    booking-form/
+-      setup.spec.tsx
+-      new-booking.spec.ts
+-      new-special-booking.spec.ts
+-      edit-booking.spec.ts
+-      clone-booking.spec.ts
    entree-dinner/
+-      new-entree-dinner.spec.ts
+-      edit-entree-dinner.spec.ts
    entree-lunch/
+-      new-entree-lunch.spec.ts
+-      edit-entree-lunch.spec.ts
    user/
        edit-user.spec.ts
    cake-frosting-input.spec.ts
    cake-order-input.spec.ts
misc-components/
    booking-status.spec.ts
+-  user-info-button.spec.ts
+-  layout.spec.ts
+-  site-info-button.spec.ts

01-widget-cards/setup.spec.ts
01-widget-cards/booking-calendar.spec.ts
01-widget-cards/upcoming-bookings.spec.tsx
01-widget-cards/entrees.spec.ts
02-table-pages/01-entree-dinner/entree-dinner-table.spec.ts
02-table-pages/01-entree-dinner/entree-flavors-table.spec.tsx
02-table-pages/02-booking/bookings-table.spec.tsx
02-table-pages/02-booking/bookings-history-table.spec.ts
02-table-pages/entree-lunch-table.spec.ts
02-table-pages/users-table.spec.ts
02-table-pages/customers-table.spec.ts
03-view-pages/setup.spec.ts
03-view-pages/view-booking.spec.ts
03-view-pages/print-booking.spec.ts
03-view-pages/view-entree-dinner.spec.ts
03-view-pages/view-entree-lunch.spec.ts
03-view-pages/print-entree-dinner.spec.ts
03-view-pages/view-appetizer-count.spec.ts
03-view-pages/view-appetizer-supplier.spec.ts
03-view-pages/view-user.spec.ts
04-forms/booking-form/setup.spec.ts
04-forms/booking-form/new-booking.spec.ts
04-forms/booking-form/new-special-booking.spec.ts
04-forms/booking-form/edit-booking.spec.ts
04-forms/booking-form/clone-booking.spec.ts
04-forms/entree-dinner/new-entree-dinner.spec.ts
04-forms/entree-dinner/edit-entree-dinner.spec.ts
04-forms/entree-lunch/new-entree-lunch.spec.ts
04-forms/entree-lunch/edit-entree-lunch.spec.ts
04-forms/user/edit-user.spec.ts
04-forms/cake-frosting-input.spec.ts
04-forms/cake-order-input.spec.ts
misc-components/booking-status.spec.ts
misc-components/user-info-button.spec.ts
misc-components/layout.spec.ts
misc-components/site-info-button.spec.ts

API

sortedGlob(pattern, options?)

Returns a Promise that resolves to an array of sorted file paths.

sortedGlobSync(pattern, options?)

Returns an array of sorted file paths.

Parameters

• pattern (string): Glob pattern to match files (e.g., 'cypress/tests**/*.spec.ts*')
• options (object, optional): Extends all Node.js glob options with:
  • sortOrder (Array<string | RegExp>, optional): Custom ordering rules. Strings match case-insensitively via inclusion; RegExp patterns test against path segments.

Returns

Promise<string[]>: Array of sorted file paths

License

MIT