Skip to content
Source
Sign inSign up
TanStack/form
Open History to see the last commit

serverValidate.spec.ts

606 lines16.9 KB

1import { describe, expect, it, vi } from 'vitest'
2import { z } from 'zod'
3import { InternalFormApi } from '../src/FormApi/FormApi.lib'
4import { InternalValidatorInstance } from '../src/ValidatorInstance.lib'
5import { installDevtoolsBridge } from '../src/devtoolsBridge.lib'
6import { validateServerValues } from '../src/internals'
7import { formOptions, initialServerFormState } from '../src'
8import type {
9 FormValidators,
10 ServerValidateFailure,
11 ServerValidateResult,
12 ServerValidateSuccess,
13} from '../src'
14​
15function expectServerValidateSuccess<
16 TFormData,
17 TFormValidators extends FormValidators<TFormData>,
18>(
19 result: ServerValidateResult<TFormData, TFormValidators>,
20): ServerValidateSuccess<TFormData, TFormValidators> {
21 expect(result.success).toBe(true)
22​
23 if (!result.success) {
24 throw new Error('Expected server validation to succeed')
25 }
26​
27 return result
29​
30function expectServerValidateFailure<
31 TFormData,
32 TFormValidators extends FormValidators<TFormData>,
33>(
34 result: ServerValidateResult<TFormData, TFormValidators>,
35): ServerValidateFailure<TFormData, TFormValidators> {
36 expect(result.success).toBe(false)
37​
38 if (result.success) {
39 throw new Error('Expected server validation to fail')
40 }
41​
42 return result
44​
45describe('server validation', () => {
46 it('runs validators explicitly configured for server validation only', async () => {
47 const changeValidator = vi.fn(() => 'Change error')
48 const serverValidator = vi.fn(() => 'Server error')
49 const options = formOptions({
50 defaultValues: { name: '' },
51 validators: [
52 {
53 run: changeValidator,
54 triggers: ['change'],
55 },
56 {
57 run: serverValidator,
58 triggers: ['server'],
59 },
60 ],
61 })
62​
63 expectServerValidateFailure(
64 await validateServerValues(options, { name: '' }),
65 )
66​
67 expect(changeValidator).not.toHaveBeenCalled()
68 expect(serverValidator).toHaveBeenCalledOnce()
69 })
70​
71 it('disposes every validator once when the server pipeline rejects', async () => {
72 const error = new Error('Pipeline failed')
73 const disposeSpy = vi.spyOn(InternalValidatorInstance.prototype, 'dispose')
74 const options = formOptions({
75 defaultValues: { name: '' },
76 validators: [
77 {
78 run: () => null,
79 get triggers(): ['server'] {
80 throw error
81 },
82 },
83 {
84 run: () => null,
85 triggers: ['server'],
86 },
87 ],
88 })
89​
90 try {
91 await expect(validateServerValues(options, { name: '' })).rejects.toBe(
92 error,
93 )
94 expect(disposeSpy).toHaveBeenCalledTimes(2)
95 expect(new Set(disposeSpy.mock.instances).size).toBe(2)
96 } finally {
97 disposeSpy.mockRestore()
98 }
99 })
100​
101 it('rethrows validator errors after disposing their instance once', async () => {
102 const error = new Error('Validator failed')
103 const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
104 const disposeSpy = vi.spyOn(InternalValidatorInstance.prototype, 'dispose')
105 const options = formOptions({
106 defaultValues: { name: '' },
107 validators: [
108 {
109 run: () => {
110 throw error
111 },
112 triggers: ['server'],
113 },
114 ],
115 })
116​
117 try {
118 await expect(validateServerValues(options, { name: '' })).rejects.toBe(
119 error,
120 )
121 expect(disposeSpy).toHaveBeenCalledOnce()
122 } finally {
123 disposeSpy.mockRestore()
124 consoleSpy.mockRestore()
125 }
126 })
127​
128 it('runs server-only validators during client submit by default', async () => {
129 const serverValidator = vi.fn(() => 'Server error')
130 const form = new InternalFormApi(
131 formOptions({
132 defaultValues: { name: '' },
133 validators: [
134 {
135 run: serverValidator,
136 triggers: ['server'],
137 },
138 ],
139 }),
140 )
141 const field = form._getOrCreateFieldApi({ name: 'name' })
142​
143 form.setFieldValue('name', 'Tony')
144 field.handleBlur()
145 await expect(form.validate('change')).resolves.toEqual([])
146 await expect(form.validate('blur')).resolves.toEqual([])
147 expect(serverValidator).not.toHaveBeenCalled()
148 await expect(form.validate('submit')).resolves.toEqual(['Server error'])
149 expect(serverValidator).toHaveBeenCalledOnce()
150 })
151​
152 it('skips server-only validators during client submit when skipOnSubmit is true', async () => {
153 const validator = vi.fn(() => 'Submit error')
154 const form = new InternalFormApi(
155 formOptions({
156 defaultValues: { name: '' },
157 validators: [
158 {
159 run: validator,
160 triggers: ['server'],
161 skipOnSubmit: true,
162 },
163 ],
164 }),
165 )
166​
167 await expect(form.validate('submit')).resolves.toEqual([])
168 expect(validator).not.toHaveBeenCalled()
169 })
170​
171 it('runs mixed server and client trigger validators in both contexts', async () => {
172 const calls: Array<{ event: string; hasFormApi: boolean }> = []
173 const validator = vi.fn(({ event, formApi }) => {
174 calls.push({ event, hasFormApi: formApi !== undefined })
175 return `${event} error`
176 })
177 const options = formOptions({
178 defaultValues: { name: '' },
179 validators: [
180 {
181 run: validator,
182 triggers: ['server', 'change'],
183 },
184 ],
185 })
186​
187 expectServerValidateFailure(
188 await validateServerValues(options, { name: '' }),
189 )
190​
191 const form = new InternalFormApi(options)
192 await expect(form.validate('change')).resolves.toEqual(['change error'])
193​
194 expect(calls).toEqual([
195 { event: 'server', hasFormApi: false },
196 { event: 'change', hasFormApi: true },
197 ])
198 })
199​
200 it('returns values and schema outputs when server validation succeeds', async () => {
201 const setOutput = vi.spyOn(InternalValidatorInstance.prototype, 'setOutput')
202 const options = formOptions({
203 defaultValues: { name: '' },
204 validators: [
205 {
206 run: z
207 .object({
208 name: z.string(),
209 })
210 .transform(({ name }) => ({ nameLength: name.length })),
211 triggers: ['server'],
212 },
213 ],
214 })
215​
216 try {
217 const result = expectServerValidateSuccess(
218 await validateServerValues(options, { name: 'Tony' }),
219 )
220​
221 expect(result.values).toEqual({ name: 'Tony' })
222 expect(result.validatorOutputs).toEqual([{ nameLength: 4 }])
223 expect(setOutput).not.toHaveBeenCalled()
224 } finally {
225 setOutput.mockRestore()
226 }
227 })
228​
229 it('aligns server schema outputs with all validator slots', async () => {
230 const options = formOptions({
231 defaultValues: { name: '' },
232 validators: [
233 {
234 run: z.object({ name: z.string() }),
235 triggers: ['change'],
236 },
237 {
238 run: () => null,
239 triggers: ['server'],
240 },
241 {
242 run: z
243 .object({ name: z.string() })
244 .transform(({ name }) => ({ nameLength: name.length })),
245 triggers: ['server'],
246 },
247 ],
248 })
249​
250 const result = expectServerValidateSuccess(
251 await validateServerValues(options, { name: 'Tony' }),
252 )
253​
254 expect(result.validatorOutputs).toEqual([
255 undefined,
256 undefined,
257 { nameLength: 4 },
258 ])
259 })
260​
261 it('returns a serializable server state when validation fails', async () => {
262 const options = formOptions({
263 defaultValues: { name: '' },
264 validators: [
265 {
266 run: () => ({
267 form: 'Form error',
268 fields: {
269 name: 'Name is required',
270 },
271 }),
272 triggers: ['server'],
273 },
274 ],
275 })
276​
277 const result = expectServerValidateFailure(
278 await validateServerValues(options, { name: '' }),
279 )
280​
281 expect(result.serverState).toMatchObject({
282 values: { name: '' },
283 submissionAttempts: 1,
284 })
285 expect(result.serverState.validationResults).toHaveLength(1)
286 expect(result.serverState.validationResults[0]).toMatchObject({
287 validatorIndex: 0,
288 result: {
289 form: 'Form error',
290 fields: {
291 name: 'Name is required',
292 },
293 },
294 })
295 })
296​
297 it('hydrates posted values and server errors into form state', async () => {
298 const options = formOptions({
299 defaultValues: { name: '', age: 0 },
300 validators: [
301 {
302 run: () => ({
303 form: 'Server form error',
304 fields: {
305 name: 'Server name error',
306 },
307 }),
308 triggers: ['server'],
309 },
310 ],
311 })
312​
313 const { serverState } = expectServerValidateFailure(
314 await validateServerValues(options, { name: '', age: 42 }),
315 )
316​
317 const form = new InternalFormApi({
318 ...options,
319 serverState,
320 } as never)
321 const field = form._getOrCreateFieldApi({ name: 'name' })
322​
323 expect(form.state.values).toEqual({ name: '', age: 42 })
324 expect(form.state.errors).toEqual([{ message: 'Server form error' }])
325 expect(field.errors).toEqual([{ message: 'Server name error' }])
326 expect(form.state.submissionAttempts).toBe(1)
327 expect(form.state.canSubmit).toBe(false)
328 })
329​
330 it('treats server state as an authoritative form snapshot', async () => {
331 const options = formOptions({
332 defaultValues: { name: '' },
333 validators: [
334 {
335 run: () => 'Client error',
336 triggers: ['change'],
337 },
338 {
339 run: () => ({
340 form: 'Server form error',
341 fields: {
342 name: 'Server name error',
343 },
344 }),
345 triggers: ['server'],
346 },
347 ],
348 })
349 const form = new InternalFormApi(options)
350 const field = form._getOrCreateFieldApi({ name: 'name' })
351​
352 form.setFieldValue('name', 'Client value', {
353 fieldApiOverride: field,
354 causeValidation: false,
355 })
356 await form.validate('change')
357​
358 expect(form.state.values).toEqual({ name: 'Client value' })
359 expect(form.state.isDirty).toBe(true)
360 expect(form.state.isTouched).toBe(true)
361 expect(form.state.errors).toEqual([{ message: 'Client error' }])
362​
363 const { serverState } = expectServerValidateFailure(
364 await validateServerValues(options, { name: 'Server value' }),
365 )
366​
367 form._update({
368 ...options,
369 serverState,
370 } as never)
371​
372 expect(form.state.values).toEqual({ name: 'Server value' })
373 expect(form.state.errors).toEqual([{ message: 'Server form error' }])
374 expect(form.state.isDirty).toBe(false)
375 expect(form.state.isTouched).toBe(false)
376 expect(form.state.submissionAttempts).toBe(1)
377 expect(field.errors).toEqual([{ message: 'Server name error' }])
378 expect(field.meta.isDirty).toBe(false)
379 expect(field.meta.isTouched).toBe(false)
380 expect(field.meta.isDefaultValue).toBe(true)
381 })
382​
383 it('treats empty server state as an authoritative reset', async () => {
384 const options = formOptions({
385 defaultValues: { name: '' },
386 validators: [
387 {
388 run: () => ({
389 fields: {
390 name: 'Server name error',
391 },
392 }),
393 triggers: ['server'],
394 },
395 ],
396 })
397​
398 const { serverState } = expectServerValidateFailure(
399 await validateServerValues(options, { name: 'Server value' }),
400 )
401​
402 const form = new InternalFormApi({
403 ...options,
404 serverState,
405 } as never)
406 const field = form._getOrCreateFieldApi({ name: 'name' })
407​
408 expect(form.state.values).toEqual({ name: 'Server value' })
409 expect(field.errors).toEqual([{ message: 'Server name error' }])
410​
411 field.handleChange('Client edit', { causeValidation: false })
412​
413 expect(form.state.values).toEqual({ name: 'Client edit' })
414 expect(form.state.isDirty).toBe(true)
415​
416 form._update({
417 ...options,
418 serverState: {
419 ...initialServerFormState,
420 },
421 } as never)
422​
423 expect(form.state.values).toEqual({ name: '' })
424 expect(form.state.errors).toEqual([])
425 expect(form.state.isDirty).toBe(false)
426 expect(form.state.isTouched).toBe(false)
427 expect(form.state.submissionAttempts).toBe(0)
428 expect(field.errors).toEqual([])
429 expect(field.meta.isDefaultValue).toBe(true)
430 })
431​
432 it('clears server errors on field events like submit errors', async () => {
433 const options = formOptions({
434 defaultValues: { name: '', email: '' },
435 validators: [
436 {
437 run: () => ({
438 form: 'Server form error',
439 fields: {
440 name: 'Server name error',
441 email: 'Server email error',
442 },
443 }),
444 triggers: ['server'],
445 },
446 ],
447 })
448​
449 const { serverState } = expectServerValidateFailure(
450 await validateServerValues(options, { name: '', email: '' }),
451 )
452​
453 const changeForm = new InternalFormApi({
454 ...options,
455 serverState,
456 } as never)
457 const changeNameField = changeForm._getOrCreateFieldApi({ name: 'name' })
458 const changeEmailField = changeForm._getOrCreateFieldApi({ name: 'email' })
459​
460 expect(changeForm.state.errors).toEqual([{ message: 'Server form error' }])
461 expect(changeNameField.errors).toEqual([{ message: 'Server name error' }])
462 expect(changeEmailField.errors).toEqual([{ message: 'Server email error' }])
463​
464 changeNameField.handleChange('Alice')
465​
466 expect(changeForm.state.errors).toEqual([])
467 expect(changeNameField.errors).toEqual([])
468 expect(changeEmailField.errors).toEqual([{ message: 'Server email error' }])
469​
470 const blurForm = new InternalFormApi({
471 ...options,
472 serverState,
473 } as never)
474 const blurNameField = blurForm._getOrCreateFieldApi({ name: 'name' })
475 const blurEmailField = blurForm._getOrCreateFieldApi({ name: 'email' })
476​
477 blurNameField.handleBlur()
478​
479 expect(blurForm.state.errors).toEqual([])
480 expect(blurNameField.errors).toEqual([])
481 expect(blurEmailField.errors).toEqual([{ message: 'Server email error' }])
482 })
483​
484 it('clears stale server errors when a new server state arrives', async () => {
485 const options = formOptions({
486 defaultValues: { name: '' },
487 validators: [
488 {
489 run: () => ({
490 fields: {
491 name: 'Server name error',
492 },
493 }),
494 triggers: ['server'],
495 },
496 ],
497 })
498​
499 const { serverState } = expectServerValidateFailure(
500 await validateServerValues(options, { name: '' }),
501 )
502​
503 const form = new InternalFormApi({
504 ...options,
505 serverState,
506 } as never)
507 const field = form._getOrCreateFieldApi({ name: 'name' })
508​
509 expect(field.errors).toEqual([{ message: 'Server name error' }])
510​
511 form._update({
512 ...options,
513 serverState: {
514 ...initialServerFormState,
515 values: { name: 'Tony' },
516 },
517 } as never)
518​
519 expect(form.state.values).toEqual({ name: 'Tony' })
520 expect(field.errors).toEqual([])
521 expect(form.state.errors).toEqual([])
522 expect(form.state.canSubmit).toBe(true)
523 })
524​
525 it('does not rerun server validators during client form hydration', () => {
526 const serverValidator = vi.fn(() => 'Server name error')
527 const options = formOptions({
528 defaultValues: { name: '' },
529 validators: [
530 {
531 run: serverValidator,
532 triggers: ['server'],
533 },
534 ],
535 serverState: {
536 values: { name: '' },
537 validationResults: [
538 {
539 validatorIndex: 0,
540 result: 'Server name error',
541 output: null,
542 },
543 ],
544 submissionAttempts: 1,
545 },
546 })
547​
548 const form = new InternalFormApi(options)
549​
550 expect(serverValidator).not.toHaveBeenCalled()
551 expect(form.state.errors).toEqual([{ message: 'Server name error' }])
552 })
553​
554 it('does not restore serialized schema output during hydration', () => {
555 const options = formOptions({
556 defaultValues: { name: '' },
557 validators: [
558 {
559 run: z.object({ name: z.string() }).transform(() => undefined),
560 triggers: ['server'],
561 },
562 ],
563 serverState: {
564 values: { name: 'Tony' },
565 validationResults: [
566 {
567 validatorIndex: 0,
568 result: null,
569 output: undefined,
570 hasOutput: true,
571 },
572 ],
573 submissionAttempts: 1,
574 },
575 })
576​
577 const form = new InternalFormApi(options)
578​
579 expect(form._validatorInstances?.[0]?.hasOutput).toBe(false)
580 expect(form._validatorInstances?.[0]?.output).toBeUndefined()
581 })
582​
583 it('notifies Devtools when server state directly resets field meta', () => {
584 const options = formOptions({ defaultValues: { name: '' } })
585 const form = new InternalFormApi(options)
586 const field = form._getOrCreateFieldApi({ name: 'name' })
587 field.handleChange('client value')
588 const updateField = vi.fn()
589 const uninstallBridge = installDevtoolsBridge({ updateField })
590​
591 try {
592 form._update({
593 ...options,
594 serverState: {
595 ...initialServerFormState,
596 values: { name: 'server value' },
597 },
598 } as never)
599​
600 expect(field.meta.isDirty).toBe(false)
601 expect(updateField).toHaveBeenCalledWith(field)
602 } finally {
603 uninstallBridge()
604 }
605 })
606})