0
# String Assertions
1

2
Comprehensive string-specific assertion methods for length, content, pattern matching, and case-insensitive comparisons.
3

4
## Capabilities
5

6
### String Subject Creation
7

8
```java { .api }
9
/**
10
 * Creates a StringSubject for asserting about String values.
11
 * @param actual the String under test
12
 */
13
public static StringSubject assertThat(String actual);
14
```
15

16
### Length Assertions
17

18
Methods for asserting about string length and emptiness.
19

20
```java { .api }
21
/**
22
 * Fails if the string does not have the given length.
23
 * @param expectedLength the expected length
24
 */
25
public void hasLength(int expectedLength);
26

27
/**
28
 * Fails if the string is not empty.
29
 */
30
public void isEmpty();
31

32
/**
33
 * Fails if the string is empty.
34
 */
35
public void isNotEmpty();
36
```
37

38
**Usage Examples:**
39

40
```java
41
assertThat("hello").hasLength(5);
42
assertThat("").isEmpty();
43
assertThat("non-empty").isNotEmpty();
44
```
45

46
### Content Assertions
47

48
Methods for asserting about string content and substrings.
49

50
```java { .api }
51
/**
52
 * Fails if the string does not contain the given sequence.
53
 * @param expectedSubstring the substring that should be present
54
 */
55
public void contains(CharSequence expectedSubstring);
56

57
/**
58
 * Fails if the string contains the given sequence.
59
 * @param unexpectedSubstring the substring that should not be present  
60
 */
61
public void doesNotContain(CharSequence unexpectedSubstring);
62

63
/**
64
 * Fails if the string does not start with the given string.
65
 * @param prefix the expected prefix
66
 */
67
public void startsWith(String prefix);
68

69
/**
70
 * Fails if the string does not end with the given string.
71
 * @param suffix the expected suffix
72
 */
73
public void endsWith(String suffix);
74
```
75

76
**Usage Examples:**
77

78
```java
79
assertThat("hello world").contains("world");
80
assertThat("hello world").doesNotContain("goodbye");
81
assertThat("prefix_suffix").startsWith("prefix");
82
assertThat("prefix_suffix").endsWith("suffix");
83
```
84

85
### Pattern Matching Assertions
86

87
Methods for regex pattern matching and validation.
88

89
```java { .api }
90
/**
91
 * Fails if the string does not match the given regular expression.
92
 * @param regex the regular expression that should match
93
 */
94
public void matches(String regex);
95

96
/**
97
 * Fails if the string does not match the given pattern.
98
 * @param pattern the Pattern that should match
99
 */
100
public void matches(Pattern pattern);
101

102
/**
103
 * Fails if the string matches the given regular expression.
104
 * @param regex the regular expression that should not match
105
 */
106
public void doesNotMatch(String regex);
107

108
/**
109
 * Fails if the string matches the given pattern.
110
 * @param pattern the Pattern that should not match
111
 */
112
public void doesNotMatch(Pattern pattern);
113

114
/**
115
 * Fails if the string does not contain a match for the given regular expression.
116
 * @param regex the regular expression that should have a match within the string
117
 */
118
public void containsMatch(String regex);
119

120
/**
121
 * Fails if the string does not contain a match for the given pattern.
122
 * @param pattern the Pattern that should have a match within the string
123
 */
124
public void containsMatch(Pattern pattern);
125

126
/**
127
 * Fails if the string contains a match for the given regular expression.
128
 * @param regex the regular expression that should not have a match within the string
129
 */
130
public void doesNotContainMatch(String regex);
131

132
/**
133
 * Fails if the string contains a match for the given pattern.
134
 * @param pattern the Pattern that should not have a match within the string
135
 */
136
public void doesNotContainMatch(Pattern pattern);
137
```
138

139
**Usage Examples:**
140

141
```java
142
import java.util.regex.Pattern;
143

144
// Full string matching
145
assertThat("abc123").matches("\\w+\\d+");
146
assertThat("abc123").matches(Pattern.compile("\\w+\\d+"));
147
assertThat("abc").doesNotMatch("\\d+");
148

149
// Substring matching
150
assertThat("hello123world").containsMatch("\\d+");
151
assertThat("hello world").doesNotContainMatch("\\d+");
152

153
// Email validation example
154
assertThat("user@example.com").matches("\\w+@\\w+\\.\\w+");
155
```
156

157
### Case-Insensitive Assertions
158

159
Methods for case-insensitive string comparisons.
160

161
```java { .api }
162
/**
163
 * Returns a CaseInsensitiveStringComparison for case-insensitive assertions.
164
 */
165
public CaseInsensitiveStringComparison ignoringCase();
166

167
/**
168
 * Nested class providing case-insensitive string comparison methods.
169
 */
170
public static class CaseInsensitiveStringComparison {
171
    /**
172
     * Fails if the string is not equal to the given string, ignoring case differences.
173
     * @param expected the expected string value (case-insensitive)
174
     */
175
    public void isEqualTo(String expected);
176
    
177
    /**
178
     * Fails if the string is equal to the given string, ignoring case differences.
179
     * @param unexpected the string value that should not match (case-insensitive)
180
     */
181
    public void isNotEqualTo(String unexpected);
182
    
183
    /**
184
     * Fails if the string does not contain the given sequence, ignoring case differences.
185
     * @param expectedSubstring the substring that should be present (case-insensitive)
186
     */
187
    public void contains(CharSequence expectedSubstring);
188
    
189
    /**
190
     * Fails if the string contains the given sequence, ignoring case differences.
191
     * @param unexpectedSubstring the substring that should not be present (case-insensitive)
192
     */
193
    public void doesNotContain(CharSequence unexpectedSubstring);
194
}
195
```
196

197
**Usage Examples:**
198

199
```java
200
assertThat("Hello World").ignoringCase().isEqualTo("hello world");
201
assertThat("Hello World").ignoringCase().isNotEqualTo("goodbye world");
202
assertThat("Hello World").ignoringCase().contains("HELLO");
203
assertThat("Hello World").ignoringCase().doesNotContain("GOODBYE");
204
```
205

206
### Advanced String Validation Examples
207

208
Common patterns for string validation in testing scenarios:
209

210
```java
211
// URL validation
212
assertThat(url).startsWith("https://");
213
assertThat(url).containsMatch("^https?://[\\w.-]+\\.[a-zA-Z]{2,}");
214

215
// File path validation  
216
assertThat(filePath).endsWith(".java");
217
assertThat(filePath).contains("/src/main/");
218

219
// Multi-line text validation
220
String multiLineText = "Line 1\nLine 2\nLine 3";
221
assertThat(multiLineText).containsMatch("Line \\d");
222
assertThat(multiLineText).contains("Line 2");
223

224
// JSON-like string validation
225
String jsonLike = "{\"name\":\"John\",\"age\":30}";
226
assertThat(jsonLike).startsWith("{");
227
assertThat(jsonLike).endsWith("}");
228
assertThat(jsonLike).containsMatch("\"\\w+\":");
229

230
// Case-insensitive configuration values
231
String configValue = "TrUe";
232
assertThat(configValue).ignoringCase().isEqualTo("true");
233
```
234

235
## Types
236

237
```java { .api }
238
/**
239
 * Subject class for making assertions about String values.
240
 */
241
public class StringSubject extends Subject {
242
    /**
243
     * Constructor for StringSubject.
244
     * @param metadata failure metadata for context
245
     * @param actual the String under test
246
     */
247
    protected StringSubject(FailureMetadata metadata, String actual);
248
}
249

250
/**
251
 * Provides case-insensitive string comparison methods.
252
 */
253
public static class CaseInsensitiveStringComparison {
254
    // Methods documented above
255
}
256
```