0
# Pattern Testing
1

2
Direct pattern testing without creating persistent matcher functions. Useful for one-off matching operations and advanced pattern validation.
3

4
## Capabilities
5

6
### Test Method
7

8
Test input string against a regex with detailed matching information.
9

10
```javascript { .api }
11
/**
12
 * Test input with the given regex
13
 * @param {string} input - String to test
14
 * @param {RegExp} regex - Regular expression to test against  
15
 * @param {object} options - Configuration options
16
 * @param {object} context - Additional context with glob and posix info
17
 * @returns {object} Object with matching info
18
 */
19
picomatch.test(input, regex, options, { glob, posix });
20

21
interface TestResult {
22
  isMatch: boolean;
23
  match: RegExpExecArray | null;
24
  output: string;
25
}
26
```
27

28
**Usage Examples:**
29

30
```javascript
31
const picomatch = require('picomatch');
32

33
// Test with compiled regex
34
const regex = picomatch.makeRe('*.js');
35
const result = picomatch.test('file.js', regex);
36
console.log(result.isMatch); // => true
37
console.log(result.match);   // => ['file.js', ...]
38
console.log(result.output);  // => 'file.js'
39

40
// Test with context information
41
const testResult = picomatch.test('src/app.js', /^(?:src\/[^/]*?\.js)$/, {}, {
42
  glob: 'src/*.js',
43
  posix: true
44
});
45
console.log(testResult.isMatch); // => true
46

47
// Test with options
48
const formatResult = picomatch.test('src\\app.js', regex, {
49
  format: (path) => path.replace(/\\/g, '/')
50
});
51
```
52

53
### IsMatch Method
54

55
Quick boolean test for pattern matching without detailed result information.
56

57
```javascript { .api }
58
/**
59
 * Returns true if any of the given patterns match the string
60
 * @param {string} str - String to test
61
 * @param {string|string[]} patterns - Glob pattern(s) to test
62
 * @param {object} options - Configuration options
63
 * @returns {boolean} True if any patterns match
64
 */
65
picomatch.isMatch(str, patterns, options);
66
```
67

68
**Usage Examples:**
69

70
```javascript
71
// Single pattern test
72
console.log(picomatch.isMatch('file.js', '*.js'));     // => true
73
console.log(picomatch.isMatch('file.txt', '*.js'));    // => false
74

75
// Multiple patterns - returns true if ANY match
76
console.log(picomatch.isMatch('app.ts', ['*.js', '*.ts'])); // => true
77

78
// With options
79
console.log(picomatch.isMatch('FILE.JS', '*.js', { nocase: true })); // => true
80

81
// Complex patterns
82
console.log(picomatch.isMatch('src/utils/helper.js', 'src/**/*.js')); // => true
83
console.log(picomatch.isMatch('test/app.spec.js', '**/*.spec.js'));   // => true
84

85
// Negation patterns
86
console.log(picomatch.isMatch('src/app.js', '!test/**')); // => true
87
console.log(picomatch.isMatch('test/app.js', '!test/**')); // => false
88
```
89

90
### MatchBase Method
91

92
Match the basename of a filepath against a pattern or regex.
93

94
```javascript { .api }
95
/**
96
 * Match the basename of a filepath
97
 * @param {string} input - Filepath to test
98
 * @param {RegExp|string} glob - Glob pattern or regex
99
 * @param {object} options - Configuration options
100
 * @returns {boolean} True if basename matches
101
 */
102
picomatch.matchBase(input, glob, options);
103
```
104

105
**Usage Examples:**
106

107
```javascript
108
// Match basename only
109
console.log(picomatch.matchBase('path/to/file.js', '*.js'));     // => true
110
console.log(picomatch.matchBase('deeply/nested/app.ts', '*.ts')); // => true
111

112
// Using regex
113
const jsRegex = /\.js$/;
114
console.log(picomatch.matchBase('src/utils/helper.js', jsRegex)); // => true
115

116
// With options
117
console.log(picomatch.matchBase('FILE.JS', '*.js', { nocase: true })); // => true
118

119
// Complex basename matching
120
console.log(picomatch.matchBase('component.test.js', '*.test.js')); // => true
121
console.log(picomatch.matchBase('utils/component.test.js', '*.test.js')); // => true
122
```
123

124
### Pattern Validation
125

126
Validate patterns and handle edge cases.
127

128
**Usage Examples:**
129

130
```javascript
131
// Error handling for invalid patterns
132
try {
133
  picomatch.isMatch('file.js', '');  // Throws TypeError
134
} catch (error) {
135
  console.log(error.message); // => 'Expected pattern to be a non-empty string'
136
}
137

138
try {
139
  picomatch.isMatch('file.js', null); // Throws TypeError
140
} catch (error) {
141
  console.log(error.message); // => 'Expected pattern to be a non-empty string'
142
}
143

144
// Valid empty string input
145
console.log(picomatch.isMatch('', '*')); // => false
146

147
// Testing with various input types
148
console.log(picomatch.isMatch('123', '*'));     // => true
149
console.log(picomatch.isMatch('', ''));         // => false (empty pattern throws)
150
```
151

152
## Advanced Testing Patterns
153

154
**Globstar Patterns:**
155

156
```javascript
157
// Recursive directory matching
158
console.log(picomatch.isMatch('src/deep/nested/file.js', 'src/**/*.js')); // => true
159
console.log(picomatch.isMatch('src/file.js', 'src/**/*.js'));             // => true
160

161
// Globstar boundaries
162
console.log(picomatch.isMatch('src/file.js', '**/file.js'));       // => true
163
console.log(picomatch.isMatch('deep/path/file.js', '**/file.js')); // => true
164
```
165

166
**Extended Glob Patterns:**
167

168
```javascript
169
// Extglob patterns (advanced)
170
console.log(picomatch.isMatch('file.js', '*.+(js|ts)'));        // => true
171
console.log(picomatch.isMatch('file.coffee', '*.+(js|ts)'));    // => false
172

173
// Negation extglobs
174
console.log(picomatch.isMatch('file.txt', '*.!(js|ts)'));       // => true
175
console.log(picomatch.isMatch('file.js', '*.!(js|ts)'));        // => false
176
```
177

178
**Brace Expansion:**
179

180
```javascript
181
// Brace patterns
182
console.log(picomatch.isMatch('file.js', '*.{js,ts,json}'));     // => true
183
console.log(picomatch.isMatch('config.json', '*.{js,ts,json}')); // => true
184

185
// Numeric braces
186
console.log(picomatch.isMatch('file1.js', 'file{1..3}.js'));     // => true
187
console.log(picomatch.isMatch('file4.js', 'file{1..3}.js'));     // => false
188
```