Documentation Source Text

Hex Artifact Content
Login

Artifact 9abec80f169ba78ec2860ff3cee9e8b3f41d8ce6cc53bfbf9ed4a6e11595226d:


0000: 3c 74 69 74 6c 65 3e 48 6f 77 20 53 51 4c 69 74  <title>How SQLit
0010: 65 20 49 73 20 54 65 73 74 65 64 3c 2f 74 69 74  e Is Tested</tit
0020: 6c 65 3e 0a 3c 74 63 6c 3e 68 64 5f 6b 65 79 77  le>.<tcl>hd_keyw
0030: 6f 72 64 73 20 74 65 73 74 69 6e 67 20 2a 74 65  ords testing *te
0040: 73 74 65 64 20 7b 74 65 73 74 20 73 75 69 74 65  sted {test suite
0050: 7d 3c 2f 74 63 6c 3e 0a 0a 3c 74 61 62 6c 65 5f  }</tcl>..<table_
0060: 6f 66 5f 63 6f 6e 74 65 6e 74 73 3e 0a 0a 3c 74  of_contents>..<t
0070: 63 6c 3e 0a 23 20 54 68 69 73 20 64 6f 63 75 6d  cl>.# This docum
0080: 65 6e 74 20 63 6f 6e 74 61 69 6e 73 20 6d 61 6e  ent contains man
0090: 79 20 73 69 7a 65 20 73 74 61 74 69 73 74 69 63  y size statistic
00a0: 73 20 61 62 6f 75 74 20 53 51 4c 69 74 65 2c 20  s about SQLite, 
00b0: 73 74 61 74 69 73 74 69 63 73 0a 23 20 74 68 61  statistics.# tha
00c0: 74 20 63 68 61 6e 67 65 20 66 72 65 71 75 65 6e  t change frequen
00d0: 74 6c 79 2e 20 20 57 65 20 77 61 6e 74 20 74 68  tly.  We want th
00e0: 65 20 64 6f 63 75 6d 65 6e 74 20 74 6f 20 62 65  e document to be
00f0: 20 75 70 2d 74 6f 2d 64 61 74 65 2e 20 20 54 6f   up-to-date.  To
0100: 0a 23 20 66 61 63 69 6c 69 74 61 74 65 20 74 68  .# facilitate th
0110: 61 74 2c 20 61 6c 6c 20 74 68 65 20 73 69 7a 65  at, all the size
0120: 20 76 61 6c 75 65 73 20 61 72 65 20 64 65 66 69   values are defi
0130: 6e 65 64 20 62 79 20 76 61 72 69 61 62 6c 65 73  ned by variables
0140: 20 68 65 72 65 0a 23 20 77 68 69 63 68 20 61 72   here.# which ar
0150: 65 20 74 68 65 6e 20 75 73 65 64 20 61 73 20 6e  e then used as n
0160: 65 65 64 65 64 20 74 68 72 6f 75 67 68 20 74 68  eeded through th
0170: 65 20 64 6f 63 75 6d 65 6e 74 2e 0a 23 0a 23 20  e document..#.# 
0180: 4e 4f 54 45 3a 20 20 41 6c 73 6f 20 75 70 64 61  NOTE:  Also upda
0190: 74 65 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e  te the version n
01a0: 75 6d 62 65 72 20 69 6e 20 74 68 65 20 74 65 78  umber in the tex
01b0: 74 21 21 21 0a 23 0a 0a 23 20 73 6c 6f 63 20 73  t!!!.#..# sloc s
01c0: 71 6c 69 74 65 33 2e 63 0a 73 65 74 20 73 74 61  qlite3.c.set sta
01d0: 74 28 63 6f 72 65 53 4c 4f 43 29 20 20 20 31 32  t(coreSLOC)   12
01e0: 38 39 30 36 20 20 3b 23 20 4e 6f 6e 2d 63 6f 6d  8906  ;# Non-com
01f0: 6d 65 6e 74 20 6c 69 6e 65 73 20 6f 66 20 61 6d  ment lines of am
0200: 61 6c 67 61 6d 61 74 69 6f 6e 20 63 6f 64 65 20  algamation code 
0210: 0a 23 20 73 6c 6f 63 20 74 65 73 74 2a 2e 63 0a  .# sloc test*.c.
0220: 73 65 74 20 73 74 61 74 28 74 63 6c 63 53 4c 4f  set stat(tclcSLO
0230: 43 29 20 20 20 20 32 36 30 38 38 20 20 3b 23 20  C)    26088  ;# 
0240: 4e 6f 6e 2d 63 6f 6d 6d 65 6e 74 20 6c 69 6e 65  Non-comment line
0250: 73 20 6f 66 20 74 65 73 74 20 43 20 63 6f 64 65  s of test C code
0260: 0a 23 20 6c 73 20 74 65 73 74 2a 2e 63 20 74 63  .# ls test*.c tc
0270: 6c 73 71 6c 69 74 65 2e 63 20 7c 20 77 63 0a 73  lsqlite.c | wc.s
0280: 65 74 20 73 74 61 74 28 74 63 6c 63 4e 66 69 6c  et stat(tclcNfil
0290: 65 29 20 20 20 20 20 20 34 38 20 20 3b 23 20 4e  e)      48  ;# N
02a0: 75 6d 62 65 72 20 6f 66 20 66 69 6c 65 73 20 6f  umber of files o
02b0: 66 20 54 43 4c 20 43 20 74 65 73 74 63 6f 64 65  f TCL C testcode
02c0: 20 2b 20 74 63 6c 73 71 6c 69 74 65 2e 63 0a 23   + tclsqlite.c.#
02d0: 20 6c 73 20 2d 6c 20 74 65 73 74 2a 2e 63 20 74   ls -l test*.c t
02e0: 63 6c 73 71 6c 69 74 65 2e 63 20 7c 20 61 77 6b  clsqlite.c | awk
02f0: 20 27 7b 73 75 6d 2b 3d 24 35 7d 45 4e 44 7b 70   '{sum+=$5}END{p
0300: 72 69 6e 74 20 73 75 6d 7d 27 0a 73 65 74 20 73  rint sum}'.set s
0310: 74 61 74 28 74 63 6c 63 4e 42 79 74 65 29 20 31  tat(tclcNByte) 1
0320: 32 31 32 32 33 34 20 20 3b 23 20 4e 75 6d 62 65  212234  ;# Numbe
0330: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 54 43  r of bytes of TC
0340: 4c 20 43 20 74 65 73 74 63 6f 64 65 20 2b 20 74  L C testcode + t
0350: 63 6c 73 71 6c 69 74 65 2e 63 0a 23 20 73 6c 6f  clsqlite.c.# slo
0360: 63 20 60 66 69 6e 64 20 2e 20 2d 6e 61 6d 65 20  c `find . -name 
0370: 27 2a 2e 74 65 73 74 27 20 2d 70 72 69 6e 74 60  '*.test' -print`
0380: 20 74 65 73 74 2f 2a 2e 74 63 6c 0a 73 65 74 20   test/*.tcl.set 
0390: 73 74 61 74 28 74 63 6c 73 53 4c 4f 43 29 20 20  stat(tclsSLOC)  
03a0: 20 34 36 32 36 38 36 20 20 3b 23 20 4e 6f 6e 2d   462686  ;# Non-
03b0: 63 6f 6d 6d 65 6e 74 20 6c 69 6e 65 73 20 6f 66  comment lines of
03c0: 20 54 43 4c 20 74 65 73 74 20 73 63 72 69 70 74   TCL test script
03d0: 0a 23 20 6c 73 20 60 66 69 6e 64 20 2e 20 2d 6e  .# ls `find . -n
03e0: 61 6d 65 20 27 2a 2e 74 65 73 74 27 20 2d 70 72  ame '*.test' -pr
03f0: 69 6e 74 60 20 74 65 73 74 2f 2a 2e 74 63 6c 20  int` test/*.tcl 
0400: 7c 20 77 63 0a 73 65 74 20 73 74 61 74 28 74 63  | wc.set stat(tc
0410: 6c 73 4e 46 69 6c 65 29 20 20 20 20 31 33 30 37  lsNFile)    1307
0420: 20 20 3b 23 20 4e 75 6d 62 65 72 20 6f 66 20 66    ;# Number of f
0430: 69 6c 65 73 20 6f 66 20 54 43 4c 20 74 65 73 74  iles of TCL test
0440: 20 73 63 72 69 70 74 0a 23 20 77 63 20 60 66 69   script.# wc `fi
0450: 6e 64 20 2e 20 2d 6e 61 6d 65 20 27 2a 2e 74 65  nd . -name '*.te
0460: 73 74 27 20 2d 70 72 69 6e 74 60 20 74 65 73 74  st' -print` test
0470: 2f 2a 2e 74 63 6c 0a 73 65 74 20 73 74 61 74 28  /*.tcl.set stat(
0480: 74 63 6c 73 4e 42 79 74 65 29 20 31 36 32 31 34  tclsNByte) 16214
0490: 34 37 32 20 3b 23 20 4e 75 6d 62 65 72 20 6f 66  472 ;# Number of
04a0: 20 62 79 74 65 73 20 6f 66 20 54 43 4c 20 74 65   bytes of TCL te
04b0: 73 74 20 73 63 72 69 70 74 0a 23 20 63 61 74 20  st script.# cat 
04c0: 60 66 69 6e 64 20 2e 20 2d 6e 61 6d 65 20 27 2a  `find . -name '*
04d0: 2e 74 65 73 74 27 20 2d 70 72 69 6e 74 60 20 7c  .test' -print` |
04e0: 20 65 67 72 65 70 20 27 64 6f 5b 5f 61 2d 7a 5d   egrep 'do[_a-z]
04f0: 2a 5f 74 65 73 74 27 20 7c 20 77 63 0a 73 65 74  *_test' | wc.set
0500: 20 73 74 61 74 28 74 63 6c 4e 54 65 73 74 29 20   stat(tclNTest) 
0510: 20 20 20 34 30 38 37 30 20 20 3b 23 20 4e 75 6d     40870  ;# Num
0520: 62 65 72 20 6f 66 20 74 65 73 74 20 63 61 73 65  ber of test case
0530: 73 20 69 6e 20 74 68 65 20 54 43 4c 20 74 65 73  s in the TCL tes
0540: 74 20 73 75 69 74 65 0a 73 65 74 20 73 74 61 74  t suite.set stat
0550: 28 74 63 6c 4e 45 76 61 6c 29 20 20 32 35 31 34  (tclNEval)  2514
0560: 31 32 35 20 20 3b 23 20 4e 75 6d 62 65 72 20 6f  125  ;# Number o
0570: 66 20 74 65 73 74 20 63 61 73 65 20 65 76 61 6c  f test case eval
0580: 75 61 74 69 6f 6e 73 20 28 66 75 6c 6c 74 65 73  uations (fulltes
0590: 74 29 0a 23 20 67 72 65 70 20 66 75 7a 7a 20 64  t).# grep fuzz d
05a0: 65 76 69 63 65 5f 6f 6e 65 2f 74 65 73 74 2d 6f  evice_one/test-o
05b0: 75 74 2e 74 78 74 20 7c 20 77 63 0a 73 65 74 20  ut.txt | wc.set 
05c0: 73 74 61 74 28 6e 53 71 6c 46 75 7a 7a 29 20 20  stat(nSqlFuzz)  
05d0: 20 31 31 31 32 36 38 20 20 3b 23 20 4e 75 6d 62   111268  ;# Numb
05e0: 65 72 20 6f 66 20 53 51 4c 20 66 75 7a 7a 20 74  er of SQL fuzz t
05f0: 65 73 74 73 0a 73 65 74 20 73 74 61 74 28 76 71  ests.set stat(vq
0600: 4e 45 76 61 6c 29 20 20 20 20 31 34 32 35 39 37  NEval)    142597
0610: 20 20 3b 23 20 4e 75 6d 62 65 72 20 6f 66 20 74    ;# Number of t
0620: 65 73 74 20 65 76 61 6c 75 61 74 69 6f 6e 73 20  est evaluations 
0630: 66 6f 72 20 76 65 72 79 71 75 69 63 6b 2e 74 65  for veryquick.te
0640: 73 74 0a 23 20 20 73 65 74 20 73 74 61 74 28 76  st.#  set stat(v
0650: 71 53 74 6d 74 43 6f 76 29 20 20 20 39 37 2e 32  qStmtCov)   97.2
0660: 33 20 20 3b 23 20 76 65 72 79 71 75 69 63 6b 20  3  ;# veryquick 
0670: 73 74 61 74 65 6d 65 6e 74 20 63 6f 76 65 72 61  statement covera
0680: 67 65 0a 23 20 20 73 65 74 20 73 74 61 74 28 76  ge.#  set stat(v
0690: 71 42 72 43 6f 76 29 20 20 20 20 20 39 32 2e 35  qBrCov)     92.5
06a0: 37 20 20 3b 23 20 76 65 72 79 71 75 69 63 6b 20  7  ;# veryquick 
06b0: 62 72 61 6e 63 68 20 63 6f 76 65 72 61 67 65 0a  branch coverage.
06c0: 23 20 20 73 65 74 20 73 74 61 74 28 61 6c 6c 53  #  set stat(allS
06d0: 74 6d 74 43 6f 76 29 20 20 39 39 2e 35 30 20 20  tmtCov)  99.50  
06e0: 3b 23 20 61 6c 6c 2e 74 65 73 74 20 73 74 61 74  ;# all.test stat
06f0: 65 6d 65 6e 74 20 63 6f 76 65 72 61 67 65 0a 23  ement coverage.#
0700: 20 20 73 65 74 20 73 74 61 74 28 61 6c 6c 42 72    set stat(allBr
0710: 43 6f 76 29 20 20 20 20 39 37 2e 34 31 20 20 3b  Cov)    97.41  ;
0720: 23 20 61 6c 6c 2e 74 65 73 74 20 63 6f 6e 64 69  # all.test condi
0730: 74 69 6f 6e 2f 64 65 63 69 73 69 6f 6e 20 63 6f  tion/decision co
0740: 76 65 72 61 67 65 0a 23 20 74 63 6c 73 68 20 6d  verage.# tclsh m
0750: 6b 74 68 33 2e 74 63 6c 20 63 66 67 2f 2a 2e 63  kth3.tcl cfg/*.c
0760: 66 67 20 2a 2f 2a 2e 74 65 73 74 20 3e 74 68 33  fg */*.test >th3
0770: 2e 63 3b 20 73 6c 6f 63 20 74 68 33 2e 63 0a 73  .c; sloc th3.c.s
0780: 65 74 20 73 74 61 74 28 74 68 33 53 4c 4f 43 29  et stat(th3SLOC)
0790: 20 20 20 20 37 39 32 33 33 38 20 20 3b 23 20 4e      792338  ;# N
07a0: 6f 6e 2d 63 6f 6d 6d 65 6e 74 20 6c 69 6e 65 73  on-comment lines
07b0: 20 69 6e 20 66 75 6c 6c 20 74 68 33 2e 63 0a 23   in full th3.c.#
07c0: 20 6c 73 20 2d 6c 20 74 68 33 2e 63 0a 73 65 74   ls -l th3.c.set
07d0: 20 73 74 61 74 28 74 68 33 4e 42 79 74 65 29 20   stat(th3NByte) 
07e0: 35 37 39 32 37 35 34 31 20 20 3b 23 20 4e 75 6d  57927541  ;# Num
07f0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
0800: 66 75 6c 6c 20 74 68 33 2e 63 0a 23 20 67 72 65  full th3.c.# gre
0810: 70 20 74 68 33 74 65 73 74 43 68 65 63 6b 20 2a  p th3testCheck *
0820: 2f 2a 2e 74 65 73 74 20 7c 77 63 0a 23 20 67 72  /*.test |wc.# gr
0830: 65 70 20 27 5e 2d 2d 72 65 73 75 6c 74 27 20 2a  ep '^--result' *
0840: 2f 2a 2e 74 65 73 74 20 7c 20 77 63 0a 23 20 67  /*.test | wc.# g
0850: 72 65 70 20 27 5e 2d 2d 67 6c 6f 62 27 20 2a 2f  rep '^--glob' */
0860: 2a 2e 74 65 73 74 20 7c 20 77 63 0a 23 20 67 72  *.test | wc.# gr
0870: 65 70 20 27 5e 2d 2d 6e 6f 74 67 6c 6f 62 27 20  ep '^--notglob' 
0880: 2a 2f 2a 2e 74 65 73 74 20 7c 20 77 63 0a 23 20  */*.test | wc.# 
0890: 67 72 65 70 20 27 5e 2d 2d 65 71 70 27 20 2a 2f  grep '^--eqp' */
08a0: 2a 2e 74 65 73 74 20 7c 20 77 63 0a 73 65 74 20  *.test | wc.set 
08b0: 73 74 61 74 28 74 68 33 4e 54 65 73 74 29 20 20  stat(th3NTest)  
08c0: 20 20 20 20 34 33 30 34 39 20 20 3b 23 20 4e 75      43049  ;# Nu
08d0: 6d 62 65 72 20 6f 66 20 74 65 73 74 20 63 61 73  mber of test cas
08e0: 65 73 0a 23 20 66 72 6f 6d 20 6f 75 74 70 75 74  es.# from output
08f0: 20 6f 66 20 61 20 6d 69 6e 2e 72 63 20 74 65 73   of a min.rc tes
0900: 74 20 72 75 6e 2e 0a 73 65 74 20 73 74 61 74 28  t run..set stat(
0910: 74 68 33 4e 45 43 6f 76 29 20 20 20 20 31 36 31  th3NECov)    161
0920: 34 33 39 30 20 20 3b 23 20 4e 75 6d 62 65 72 20  4390  ;# Number 
0930: 6f 66 20 74 65 73 74 20 63 61 73 65 20 65 76 61  of test case eva
0940: 6c 73 20 66 6f 72 20 63 6f 76 65 72 61 67 65 0a  ls for coverage.
0950: 23 73 65 74 20 73 74 61 74 28 74 68 33 4e 45 54  #set stat(th3NET
0960: 65 73 74 29 20 20 37 32 34 37 30 35 35 20 20 3b  est)  7247055  ;
0970: 23 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 73 74  # Number of test
0980: 20 63 61 73 65 20 65 76 61 6c 75 61 74 69 6f 6e   case evaluation
0990: 73 0a 23 73 65 74 20 73 74 61 74 28 74 68 33 4e  s.#set stat(th3N
09a0: 45 45 78 74 29 20 35 38 39 31 37 35 34 38 33 20  EExt) 589175483 
09b0: 20 3b 23 20 4e 75 6d 62 65 72 20 6f 66 20 74 65   ;# Number of te
09c0: 73 74 20 63 61 73 65 20 65 76 61 6c 73 20 65 78  st case evals ex
09d0: 74 65 6e 64 65 64 0a 23 73 65 74 20 73 74 61 74  tended.#set stat
09e0: 28 74 68 33 4e 45 52 65 6c 29 20 32 35 30 30 30  (th3NERel) 25000
09f0: 30 30 30 30 30 20 3b 23 20 4e 75 6d 62 65 72 20  00000 ;# Number 
0a00: 6f 66 20 74 65 73 74 20 63 61 73 65 20 65 76 61  of test case eva
0a10: 6c 73 20 72 65 6c 65 61 73 65 0a 73 65 74 20 73  ls release.set s
0a20: 74 61 74 28 74 68 33 53 74 6d 74 43 6f 76 29 20  tat(th3StmtCov) 
0a30: 31 30 30 2e 30 30 20 20 3b 23 20 54 48 33 20 73  100.00  ;# TH3 s
0a40: 74 61 74 65 6d 65 6e 74 20 63 6f 76 65 72 61 67  tatement coverag
0a50: 65 0a 73 65 74 20 73 74 61 74 28 74 68 33 42 72  e.set stat(th3Br
0a60: 43 6f 76 29 20 20 20 31 30 30 2e 30 30 20 20 3b  Cov)   100.00  ;
0a70: 23 20 54 48 33 20 62 72 61 6e 63 68 20 63 6f 76  # TH3 branch cov
0a80: 65 72 61 67 65 0a 23 20 77 63 20 60 66 69 6e 64  erage.# wc `find
0a90: 20 2e 20 2d 6e 61 6d 65 20 27 2a 2e 74 65 73 74   . -name '*.test
0aa0: 27 60 20 7c 20 61 77 6b 20 27 7b 78 2b 3d 24 31  '` | awk '{x+=$1
0ab0: 7d 45 4e 44 7b 70 72 69 6e 74 20 78 7d 27 0a 73  }END{print x}'.s
0ac0: 65 74 20 73 74 61 74 28 73 6c 74 73 53 4c 4f 43  et stat(sltsSLOC
0ad0: 29 20 20 39 30 34 38 39 34 39 34 20 3b 23 20 4e  )  90489494 ;# N
0ae0: 6f 6e 2d 63 6f 6d 6d 65 6e 74 20 6c 69 6e 65 73  on-comment lines
0af0: 20 6f 66 20 53 4c 54 20 74 65 73 74 20 73 63 72   of SLT test scr
0b00: 69 70 74 0a 23 20 6c 73 20 2d 6c 20 60 66 69 6e  ipt.# ls -l `fin
0b10: 64 20 2e 20 2d 6e 61 6d 65 20 27 2a 2e 74 65 73  d . -name '*.tes
0b20: 74 27 60 20 7c 20 61 77 6b 20 27 7b 73 75 6d 2b  t'` | awk '{sum+
0b30: 3d 24 35 7d 45 4e 44 7b 70 72 69 6e 74 20 73 75  =$5}END{print su
0b40: 6d 7d 27 0a 73 65 74 20 73 74 61 74 28 73 6c 74  m}'.set stat(slt
0b50: 73 4e 42 79 74 65 29 20 31 31 31 36 38 30 30 33  sNByte) 11168003
0b60: 30 38 20 3b 23 20 42 79 74 65 73 20 6f 66 20 53  08 ;# Bytes of S
0b70: 4c 54 20 74 65 73 74 20 73 63 72 69 70 74 0a 23  LT test script.#
0b80: 20 66 69 6e 64 20 2e 20 2d 6e 61 6d 65 20 27 2a   find . -name '*
0b90: 2e 74 65 73 74 27 20 7c 20 77 63 0a 73 65 74 20  .test' | wc.set 
0ba0: 73 74 61 74 28 73 6c 74 73 4e 46 69 6c 65 29 20  stat(sltsNFile) 
0bb0: 20 20 20 20 20 20 20 36 32 32 20 3b 23 20 46 69         622 ;# Fi
0bc0: 6c 65 73 20 6f 66 20 53 4c 54 20 74 65 73 74 20  les of SLT test 
0bd0: 73 63 72 69 70 74 0a 23 20 73 6c 6f 63 20 6d 64  script.# sloc md
0be0: 35 2e 63 20 73 6c 74 5f 2a 2e 63 20 73 71 6c 6c  5.c slt_*.c sqll
0bf0: 6f 67 69 63 74 65 73 74 2e 63 0a 73 65 74 20 73  ogictest.c.set s
0c00: 74 61 74 28 73 6c 74 63 53 4c 4f 43 29 20 20 20  tat(sltcSLOC)   
0c10: 20 20 20 20 20 31 34 30 34 20 3b 23 20 4e 6f 6e       1404 ;# Non
0c20: 2d 63 6f 6d 6d 65 6e 74 20 6c 69 6e 65 73 20 6f  -comment lines o
0c30: 66 20 53 4c 54 20 43 20 63 6f 64 65 0a 23 20 67  f SLT C code.# g
0c40: 72 65 70 20 27 5e 71 75 65 72 79 27 20 60 66 6f  rep '^query' `fo
0c50: 73 73 69 6c 20 6c 73 20 7c 20 61 77 6b 20 27 2f  ssil ls | awk '/
0c60: 5c 2e 74 65 73 74 24 2f 7b 70 72 69 6e 74 20 24  \.test$/{print $
0c70: 32 7d 27 60 20 7c 20 77 63 0a 73 65 74 20 73 74  2}'` | wc.set st
0c80: 61 74 28 73 6c 74 4e 54 65 73 74 29 20 20 20 20  at(sltNTest)    
0c90: 20 37 31 39 35 33 34 32 20 3b 23 20 4e 75 6d 62   7195342 ;# Numb
0ca0: 65 72 20 6f 66 20 74 65 73 74 20 63 61 73 65 73  er of test cases
0cb0: 20 69 6e 20 53 4c 54 0a 23 20 67 72 65 70 20 27   in SLT.# grep '
0cc0: 65 72 72 6f 72 73 20 6f 75 74 20 6f 66 27 20 61  errors out of' a
0cd0: 6c 6c 2d 6f 75 74 2e 74 78 74 20 7c 20 61 77 6b  ll-out.txt | awk
0ce0: 20 27 7b 78 2b 3d 24 35 7d 45 4e 44 7b 70 72 69   '{x+=$5}END{pri
0cf0: 6e 74 20 78 7d 27 0a 73 65 74 20 73 74 61 74 28  nt x}'.set stat(
0d00: 73 6c 74 4e 52 75 6e 29 20 20 20 20 20 31 31 38  sltNRun)     118
0d10: 37 39 37 35 38 20 3b 23 20 4e 75 6d 62 65 72 20  79758 ;# Number 
0d20: 6f 66 20 74 65 73 74 73 20 72 75 6e 20 69 6e 20  of tests run in 
0d30: 53 4c 54 0a 23 20 67 72 65 70 20 27 61 73 73 65  SLT.# grep 'asse
0d40: 72 74 28 27 20 73 71 6c 69 74 65 33 2e 63 20 7c  rt(' sqlite3.c |
0d50: 20 77 63 0a 73 65 74 20 73 74 61 74 28 6e 41 73   wc.set stat(nAs
0d60: 73 65 72 74 29 20 20 20 20 20 20 20 20 20 35 34  sert)         54
0d70: 31 35 20 3b 23 20 4e 75 6d 62 65 72 20 6f 66 20  15 ;# Number of 
0d80: 61 73 73 65 72 74 20 73 74 61 74 65 6d 65 6e 74  assert statement
0d90: 73 0a 23 20 67 72 65 70 20 27 74 65 73 74 63 61  s.# grep 'testca
0da0: 73 65 28 27 20 73 71 6c 69 74 65 33 2e 63 20 7c  se(' sqlite3.c |
0db0: 20 67 72 65 70 20 2d 76 20 64 65 66 69 6e 65 20   grep -v define 
0dc0: 7c 20 77 63 0a 73 65 74 20 73 74 61 74 28 6e 54  | wc.set stat(nT
0dd0: 65 73 74 63 61 73 65 29 20 20 20 20 20 20 20 20  estcase)        
0de0: 38 37 38 20 3b 23 20 4e 75 6d 62 65 72 20 6f 66  878 ;# Number of
0df0: 20 74 65 73 74 63 61 73 65 20 73 74 61 74 65 6d   testcase statem
0e00: 65 6e 74 73 0a 0a 73 65 74 20 73 74 61 74 28 74  ents..set stat(t
0e10: 6f 74 61 6c 53 4c 4f 43 29 20 5b 65 78 70 72 20  otalSLOC) [expr 
0e20: 7b 24 73 74 61 74 28 74 63 6c 63 53 4c 4f 43 29  {$stat(tclcSLOC)
0e30: 2b 24 73 74 61 74 28 74 63 6c 73 53 4c 4f 43 29  +$stat(tclsSLOC)
0e40: 2b 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  +.              
0e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 24 73 74               $st
0e60: 61 74 28 74 68 33 53 4c 4f 43 29 2b 24 73 74 61  at(th3SLOC)+$sta
0e70: 74 28 73 6c 74 63 53 4c 4f 43 29 2b 24 73 74 61  t(sltcSLOC)+$sta
0e80: 74 28 73 6c 74 73 53 4c 4f 43 29 7d 5d 0a 0a 70  t(sltsSLOC)}]..p
0e90: 72 6f 63 20 47 42 20 7b 65 78 70 72 7d 20 7b 0a  roc GB {expr} {.
0ea0: 20 20 73 65 74 20 6e 20 5b 75 70 6c 65 76 65 6c    set n [uplevel
0eb0: 20 23 30 20 65 78 70 72 20 24 65 78 70 72 5d 0a   #0 expr $expr].
0ec0: 20 20 68 64 5f 70 75 74 73 20 5b 66 6f 72 6d 61    hd_puts [forma
0ed0: 74 20 25 2e 32 66 20 5b 65 78 70 72 20 7b 24 6e  t %.2f [expr {$n
0ee0: 2f 28 31 30 30 30 2e 30 2a 31 30 30 30 2e 30 2a  /(1000.0*1000.0*
0ef0: 31 30 30 30 2e 30 29 7d 5d 5d 0a 7d 20 20 0a 70  1000.0)}]].}  .p
0f00: 72 6f 63 20 4d 69 42 20 7b 65 78 70 72 7d 20 7b  roc MiB {expr} {
0f10: 0a 20 20 73 65 74 20 6e 20 5b 75 70 6c 65 76 65  .  set n [upleve
0f20: 6c 20 23 30 20 65 78 70 72 20 24 65 78 70 72 5d  l #0 expr $expr]
0f30: 0a 20 20 68 64 5f 70 75 74 73 20 5b 66 6f 72 6d  .  hd_puts [form
0f40: 61 74 20 25 2e 31 66 20 5b 65 78 70 72 20 7b 24  at %.1f [expr {$
0f50: 6e 2f 28 31 30 32 34 2e 30 2a 31 30 32 34 2e 30  n/(1024.0*1024.0
0f60: 29 7d 5d 5d 0a 7d 20 20 0a 70 72 6f 63 20 4d 42  )}]].}  .proc MB
0f70: 20 7b 65 78 70 72 7d 20 7b 0a 20 20 73 65 74 20   {expr} {.  set 
0f80: 6e 20 5b 75 70 6c 65 76 65 6c 20 23 30 20 65 78  n [uplevel #0 ex
0f90: 70 72 20 24 65 78 70 72 5d 0a 20 20 68 64 5f 70  pr $expr].  hd_p
0fa0: 75 74 73 20 5b 66 6f 72 6d 61 74 20 25 2e 31 66  uts [format %.1f
0fb0: 20 5b 65 78 70 72 20 7b 24 6e 2f 28 31 30 30 30   [expr {$n/(1000
0fc0: 2e 30 2a 31 30 30 30 2e 30 29 7d 5d 5d 0a 7d 20  .0*1000.0)}]].} 
0fd0: 20 0a 70 72 6f 63 20 4b 69 42 20 7b 65 78 70 72   .proc KiB {expr
0fe0: 7d 20 7b 0a 20 20 73 65 74 20 6e 20 5b 75 70 6c  } {.  set n [upl
0ff0: 65 76 65 6c 20 23 30 20 65 78 70 72 20 24 65 78  evel #0 expr $ex
1000: 70 72 5d 0a 20 20 68 64 5f 70 75 74 73 20 5b 66  pr].  hd_puts [f
1010: 6f 72 6d 61 74 20 25 2e 31 66 20 5b 65 78 70 72  ormat %.1f [expr
1020: 20 7b 24 6e 2f 28 31 30 32 34 2e 30 29 7d 5d 5d   {$n/(1024.0)}]]
1030: 0a 7d 20 20 0a 70 72 6f 63 20 4b 42 20 7b 65 78  .}  .proc KB {ex
1040: 70 72 7d 20 7b 0a 20 20 73 65 74 20 6e 20 5b 75  pr} {.  set n [u
1050: 70 6c 65 76 65 6c 20 23 30 20 65 78 70 72 20 24  plevel #0 expr $
1060: 65 78 70 72 5d 0a 20 20 68 64 5f 70 75 74 73 20  expr].  hd_puts 
1070: 5b 66 6f 72 6d 61 74 20 25 2e 31 66 20 5b 65 78  [format %.1f [ex
1080: 70 72 20 7b 24 6e 2f 28 31 30 30 30 2e 30 29 7d  pr {$n/(1000.0)}
1090: 5d 5d 0a 7d 0a 70 72 6f 63 20 4e 20 7b 65 78 70  ]].}.proc N {exp
10a0: 72 7d 20 7b 0a 20 20 68 64 5f 70 75 74 73 20 5b  r} {.  hd_puts [
10b0: 75 70 6c 65 76 65 6c 20 23 30 20 65 78 70 72 20  uplevel #0 expr 
10c0: 24 65 78 70 72 5d 0a 7d 0a 70 72 6f 63 20 76 65  $expr].}.proc ve
10d0: 72 73 69 6f 6e 20 7b 7d 20 7b 0a 20 20 68 64 5f  rsion {} {.  hd_
10e0: 70 75 74 73 20 24 3a 3a 73 74 61 74 28 76 65 72  puts $::stat(ver
10f0: 73 69 6f 6e 29 0a 7d 0a 0a 3c 2f 74 63 6c 3e 0a  sion).}..</tcl>.
1100: 0a 3c 68 31 3e 49 6e 74 72 6f 64 75 63 74 69 6f  .<h1>Introductio
1110: 6e 3c 2f 68 31 3e 0a 0a 3c 70 3e 54 68 65 20 72  n</h1>..<p>The r
1120: 65 6c 69 61 62 69 6c 69 74 79 20 61 6e 64 20 72  eliability and r
1130: 6f 62 75 73 74 6e 65 73 73 20 6f 66 20 53 51 4c  obustness of SQL
1140: 69 74 65 20 69 73 20 61 63 68 69 65 76 65 64 20  ite is achieved 
1150: 69 6e 20 70 61 72 74 0a 62 79 20 74 68 6f 72 6f  in part.by thoro
1160: 75 67 68 20 61 6e 64 20 63 61 72 65 66 75 6c 20  ugh and careful 
1170: 74 65 73 74 69 6e 67 2e 3c 2f 70 3e 0a 0a 3c 70  testing.</p>..<p
1180: 3e 41 73 20 6f 66 20 5b 76 65 72 73 69 6f 6e 20  >As of [version 
1190: 33 2e 32 33 2e 30 5d 20 28 5b 64 61 74 65 6f 66  3.23.0] ([dateof
11a0: 3a 33 2e 32 33 2e 30 5d 29 2c 0a 74 68 65 20 53  :3.23.0]),.the S
11b0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 63 6f  QLite library co
11c0: 6e 73 69 73 74 73 20 6f 66 20 61 70 70 72 6f 78  nsists of approx
11d0: 69 6d 61 74 65 6c 79 0a 3c 74 63 6c 3e 4b 42 20  imately.<tcl>KB 
11e0: 7b 24 73 74 61 74 28 63 6f 72 65 53 4c 4f 43 29  {$stat(coreSLOC)
11f0: 7d 3c 2f 74 63 6c 3e 20 4b 53 4c 4f 43 20 6f 66  }</tcl> KSLOC of
1200: 20 43 20 63 6f 64 65 2e 0a 28 4b 53 4c 4f 43 20   C code..(KSLOC 
1210: 6d 65 61 6e 73 20 74 68 6f 75 73 61 6e 64 73 20  means thousands 
1220: 6f 66 20 22 53 6f 75 72 63 65 20 4c 69 6e 65 73  of "Source Lines
1230: 20 4f 66 20 43 6f 64 65 22 20 6f 72 2c 20 69 6e   Of Code" or, in
1240: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 6c 69   other words,.li
1250: 6e 65 73 20 6f 66 20 63 6f 64 65 20 65 78 63 6c  nes of code excl
1260: 75 64 69 6e 67 20 62 6c 61 6e 6b 20 6c 69 6e 65  uding blank line
1270: 73 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 2e 29  s and comments.)
1280: 0a 42 79 20 63 6f 6d 70 61 72 69 73 6f 6e 2c 20  .By comparison, 
1290: 74 68 65 20 70 72 6f 6a 65 63 74 20 68 61 73 0a  the project has.
12a0: 3c 74 63 6c 3e 0a 68 64 5f 70 75 74 73 20 22 5b  <tcl>.hd_puts "[
12b0: 65 78 70 72 20 7b 69 6e 74 28 24 73 74 61 74 28  expr {int($stat(
12c0: 74 6f 74 61 6c 53 4c 4f 43 29 2f 24 73 74 61 74  totalSLOC)/$stat
12d0: 28 63 6f 72 65 53 4c 4f 43 29 29 7d 5d 20 74 69  (coreSLOC))}] ti
12e0: 6d 65 73 20 61 73 20 6d 75 63 68 22 0a 3c 2f 74  mes as much".</t
12f0: 63 6c 3e 0a 74 65 73 74 20 63 6f 64 65 20 61 6e  cl>.test code an
1300: 64 20 74 65 73 74 20 73 63 72 69 70 74 73 20 2d  d test scripts -
1310: 20 0a 3c 74 63 6c 3e 4b 42 20 7b 24 73 74 61 74   .<tcl>KB {$stat
1320: 28 74 6f 74 61 6c 53 4c 4f 43 29 7d 3c 2f 74 63  (totalSLOC)}</tc
1330: 6c 3e 20 4b 53 4c 4f 43 2e 3c 2f 70 3e 0a 0a 3c  l> KSLOC.</p>..<
1340: 68 32 3e 45 78 65 63 75 74 69 76 65 20 53 75 6d  h2>Executive Sum
1350: 6d 61 72 79 3c 2f 68 32 3e 0a 0a 3c 75 6c 3e 0a  mary</h2>..<ul>.
1360: 3c 6c 69 3e 20 54 68 72 65 65 20 69 6e 64 65 70  <li> Three indep
1370: 65 6e 64 65 6e 74 6c 79 20 64 65 76 65 6c 6f 70  endently develop
1380: 65 64 20 74 65 73 74 20 68 61 72 6e 65 73 73 65  ed test harnesse
1390: 73 0a 3c 6c 69 3e 20 31 30 30 25 20 62 72 61 6e  s.<li> 100% bran
13a0: 63 68 20 74 65 73 74 20 63 6f 76 65 72 61 67 65  ch test coverage
13b0: 20 69 6e 20 61 6e 20 61 73 2d 64 65 70 6c 6f 79   in an as-deploy
13c0: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
13d0: 0a 3c 6c 69 3e 20 4d 69 6c 6c 69 6f 6e 73 20 61  .<li> Millions a
13e0: 6e 64 20 6d 69 6c 6c 69 6f 6e 73 20 6f 66 20 74  nd millions of t
13f0: 65 73 74 20 63 61 73 65 73 0a 3c 6c 69 3e 20 4f  est cases.<li> O
1400: 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 74 65 73  ut-of-memory tes
1410: 74 73 0a 3c 6c 69 3e 20 49 2f 4f 20 65 72 72 6f  ts.<li> I/O erro
1420: 72 20 74 65 73 74 73 0a 3c 6c 69 3e 20 43 72 61  r tests.<li> Cra
1430: 73 68 20 61 6e 64 20 70 6f 77 65 72 20 6c 6f 73  sh and power los
1440: 73 20 74 65 73 74 73 0a 3c 6c 69 3e 20 46 75 7a  s tests.<li> Fuz
1450: 7a 20 74 65 73 74 73 0a 3c 6c 69 3e 20 42 6f 75  z tests.<li> Bou
1460: 6e 64 61 72 79 20 76 61 6c 75 65 20 74 65 73 74  ndary value test
1470: 73 0a 3c 6c 69 3e 20 44 69 73 61 62 6c 65 64 20  s.<li> Disabled 
1480: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 74 65 73  optimization tes
1490: 74 73 0a 3c 6c 69 3e 20 52 65 67 72 65 73 73 69  ts.<li> Regressi
14a0: 6f 6e 20 74 65 73 74 73 0a 3c 6c 69 3e 20 4d 61  on tests.<li> Ma
14b0: 6c 66 6f 72 6d 65 64 20 64 61 74 61 62 61 73 65  lformed database
14c0: 20 74 65 73 74 73 0a 3c 6c 69 3e 20 45 78 74 65   tests.<li> Exte
14d0: 6e 73 69 76 65 20 75 73 65 20 6f 66 20 61 73 73  nsive use of ass
14e0: 65 72 74 28 29 20 61 6e 64 20 72 75 6e 2d 74 69  ert() and run-ti
14f0: 6d 65 20 63 68 65 63 6b 73 0a 3c 6c 69 3e 20 56  me checks.<li> V
1500: 61 6c 67 72 69 6e 64 20 61 6e 61 6c 79 73 69 73  algrind analysis
1510: 0a 3c 6c 69 3e 20 55 6e 64 65 66 69 6e 65 64 20  .<li> Undefined 
1520: 62 65 68 61 76 69 6f 72 20 63 68 65 63 6b 73 0a  behavior checks.
1530: 3c 6c 69 3e 20 43 68 65 63 6b 6c 69 73 74 73 0a  <li> Checklists.
1540: 3c 2f 75 6c 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66  </ul>..<tcl>hd_f
1550: 72 61 67 6d 65 6e 74 20 7b 68 61 72 6e 65 73 73  ragment {harness
1560: 65 73 7d 20 7b 74 65 73 74 20 68 61 72 6e 65 73  es} {test harnes
1570: 73 7d 20 7b 74 68 72 65 65 20 74 65 73 74 20 68  s} {three test h
1580: 61 72 6e 65 73 73 65 73 7d 3c 2f 74 63 6c 3e 0a  arnesses}</tcl>.
1590: 3c 68 31 3e 54 65 73 74 20 48 61 72 6e 65 73 73  <h1>Test Harness
15a0: 65 73 3c 2f 68 31 3e 0a 0a 3c 70 3e 54 68 65 72  es</h1>..<p>Ther
15b0: 65 20 61 72 65 20 74 68 72 65 65 20 69 6e 64 65  e are three inde
15c0: 70 65 6e 64 65 6e 74 20 74 65 73 74 20 68 61 72  pendent test har
15d0: 6e 65 73 73 65 73 20 75 73 65 64 20 66 6f 72 20  nesses used for 
15e0: 74 65 73 74 69 6e 67 20 74 68 65 20 0a 63 6f 72  testing the .cor
15f0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
1600: 2e 0a 45 61 63 68 20 74 65 73 74 20 68 61 72 6e  ..Each test harn
1610: 65 73 73 20 69 73 20 64 65 73 69 67 6e 65 64 2c  ess is designed,
1620: 20 6d 61 69 6e 74 61 69 6e 65 64 2c 20 61 6e 64   maintained, and
1630: 20 6d 61 6e 61 67 65 64 20 73 65 70 61 72 61 74   managed separat
1640: 65 6c 79 0a 66 72 6f 6d 20 74 68 65 20 6f 74 68  ely.from the oth
1650: 65 72 73 2e 0a 3c 2f 70 3e 0a 0a 3c 6f 6c 3e 0a  ers..</p>..<ol>.
1660: 3c 6c 69 3e 3c 70 3e 0a 3c 74 63 6c 3e 68 64 5f  <li><p>.<tcl>hd_
1670: 66 72 61 67 6d 65 6e 74 20 74 63 6c 20 7b 54 43  fragment tcl {TC
1680: 4c 20 74 65 73 74 20 73 75 69 74 65 7d 3c 2f 74  L test suite}</t
1690: 63 6c 3e 0a 54 68 65 20 3c 62 3e 54 43 4c 20 54  cl>.The <b>TCL T
16a0: 65 73 74 73 3c 2f 62 3e 20 61 72 65 20 74 68 65  ests</b> are the
16b0: 20 6f 6c 64 65 73 74 20 73 65 74 20 6f 66 20 74   oldest set of t
16c0: 65 73 74 73 20 66 6f 72 20 53 51 4c 69 74 65 2e  ests for SQLite.
16d0: 20 20 0a 54 68 65 79 20 61 72 65 20 63 6f 6e 74    .They are cont
16e0: 61 69 6e 65 64 20 69 6e 20 74 68 65 20 73 61 6d  ained in the sam
16f0: 65 20 73 6f 75 72 63 65 20 74 72 65 65 20 61 73  e source tree as
1700: 20 74 68 65 0a 53 51 4c 69 74 65 20 63 6f 72 65   the.SQLite core
1710: 20 61 6e 64 20 6c 69 6b 65 20 74 68 65 20 53 51   and like the SQ
1720: 4c 69 74 65 20 63 6f 72 65 20 61 72 65 20 69 6e  Lite core are in
1730: 20 74 68 65 20 70 75 62 6c 69 63 20 64 6f 6d 61   the public doma
1740: 69 6e 2e 20 20 54 68 65 0a 54 43 4c 20 74 65 73  in.  The.TCL tes
1750: 74 73 20 61 72 65 20 74 68 65 20 70 72 69 6d 61  ts are the prima
1760: 72 79 20 74 65 73 74 73 20 75 73 65 64 20 64 75  ry tests used du
1770: 72 69 6e 67 20 64 65 76 65 6c 6f 70 6d 65 6e 74  ring development
1780: 2e 0a 54 68 65 20 54 43 4c 20 74 65 73 74 73 20  ..The TCL tests 
1790: 61 72 65 20 77 72 69 74 74 65 6e 20 75 73 69 6e  are written usin
17a0: 67 20 74 68 65 20 0a 5b 68 74 74 70 3a 2f 2f 77  g the .[http://w
17b0: 77 77 2e 74 63 6c 2d 6c 61 6e 67 2e 6f 72 67 2f  ww.tcl-lang.org/
17c0: 20 7c 20 54 43 4c 20 73 63 72 69 70 74 69 6e 67   | TCL scripting
17d0: 20 6c 61 6e 67 75 61 67 65 5d 2e 0a 54 68 65 20   language]..The 
17e0: 54 43 4c 20 74 65 73 74 20 68 61 72 6e 65 73 73  TCL test harness
17f0: 20 69 74 73 65 6c 66 20 63 6f 6e 73 69 73 74 73   itself consists
1800: 20 6f 66 20 3c 74 63 6c 3e 4b 42 20 7b 24 73 74   of <tcl>KB {$st
1810: 61 74 28 74 63 6c 63 53 4c 4f 43 29 7d 3c 2f 74  at(tclcSLOC)}</t
1820: 63 6c 3e 20 4b 53 4c 4f 43 20 0a 6f 66 20 43 20  cl> KSLOC .of C 
1830: 63 6f 64 65 20 75 73 65 64 20 74 6f 20 63 72 65  code used to cre
1840: 61 74 65 20 74 68 65 20 54 43 4c 20 69 6e 74 65  ate the TCL inte
1850: 72 66 61 63 65 2e 20 20 54 68 65 20 74 65 73 74  rface.  The test
1860: 20 73 63 72 69 70 74 73 20 61 72 65 20 63 6f 6e   scripts are con
1870: 74 61 69 6e 65 64 0a 69 6e 20 3c 74 63 6c 3e 4e  tained.in <tcl>N
1880: 20 7b 24 73 74 61 74 28 74 63 6c 73 4e 46 69 6c   {$stat(tclsNFil
1890: 65 29 7d 3c 2f 74 63 6c 3e 20 66 69 6c 65 73 20  e)}</tcl> files 
18a0: 74 6f 74 61 6c 69 6e 67 20 0a 3c 74 63 6c 3e 4d  totaling .<tcl>M
18b0: 69 42 20 7b 24 73 74 61 74 28 74 63 6c 73 4e 42  iB {$stat(tclsNB
18c0: 79 74 65 29 7d 3c 2f 74 63 6c 3e 4d 42 20 69 6e  yte)}</tcl>MB in
18d0: 20 73 69 7a 65 2e 20 20 54 68 65 72 65 20 61 72   size.  There ar
18e0: 65 0a 3c 74 63 6c 3e 4e 20 7b 24 73 74 61 74 28  e.<tcl>N {$stat(
18f0: 74 63 6c 4e 54 65 73 74 29 7d 3c 2f 74 63 6c 3e  tclNTest)}</tcl>
1900: 20 64 69 73 74 69 6e 63 74 20 74 65 73 74 20 63   distinct test c
1910: 61 73 65 73 2c 20 62 75 74 20 6d 61 6e 79 20 6f  ases, but many o
1920: 66 20 74 68 65 20 74 65 73 74 0a 63 61 73 65 73  f the test.cases
1930: 20 61 72 65 20 70 61 72 61 6d 65 74 65 72 69 7a   are parameteriz
1940: 65 64 20 61 6e 64 20 72 75 6e 20 6d 75 6c 74 69  ed and run multi
1950: 70 6c 65 20 74 69 6d 65 73 20 28 77 69 74 68 20  ple times (with 
1960: 64 69 66 66 65 72 65 6e 74 20 70 61 72 61 6d 65  different parame
1970: 74 65 72 73 29 0a 73 6f 20 74 68 61 74 20 6f 6e  ters).so that on
1980: 20 61 20 66 75 6c 6c 20 74 65 73 74 20 72 75 6e   a full test run
1990: 20 6d 69 6c 6c 69 6f 6e 73 20 6f 66 0a 73 65 70   millions of.sep
19a0: 61 72 61 74 65 20 74 65 73 74 73 20 61 72 65 20  arate tests are 
19b0: 70 65 72 66 6f 72 6d 65 64 2e 0a 3c 2f 70 3e 0a  performed..</p>.
19c0: 3c 2f 6c 69 3e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 54  </li>..<li><p>.T
19d0: 68 65 20 3c 62 3e 5b 54 48 33 5d 3c 2f 62 3e 20  he <b>[TH3]</b> 
19e0: 74 65 73 74 20 68 61 72 6e 65 73 73 20 69 73 20  test harness is 
19f0: 61 20 73 65 74 20 6f 66 20 70 72 6f 70 72 69 65  a set of proprie
1a00: 74 61 72 79 20 74 65 73 74 73 2c 20 77 72 69 74  tary tests, writ
1a10: 74 65 6e 20 69 6e 0a 43 20 74 68 61 74 20 70 72  ten in.C that pr
1a20: 6f 76 69 64 65 20 31 30 30 25 20 62 72 61 6e 63  ovide 100% branc
1a30: 68 20 74 65 73 74 20 63 6f 76 65 72 61 67 65 20  h test coverage 
1a40: 0a 28 61 6e 64 20 5b 4d 43 2f 44 43 7c 31 30 30  .(and [MC/DC|100
1a50: 25 20 4d 43 2f 44 43 20 74 65 73 74 20 63 6f 76  % MC/DC test cov
1a60: 65 72 61 67 65 5d 29 20 74 6f 0a 74 68 65 20 63  erage]) to.the c
1a70: 6f 72 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  ore SQLite libra
1a80: 72 79 2e 20 20 54 68 65 20 54 48 33 20 74 65 73  ry.  The TH3 tes
1a90: 74 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  ts are designed 
1aa0: 74 6f 20 72 75 6e 0a 6f 6e 20 65 6d 62 65 64 64  to run.on embedd
1ab0: 65 64 20 61 6e 64 20 73 70 65 63 69 61 6c 69 7a  ed and specializ
1ac0: 65 64 20 70 6c 61 74 66 6f 72 6d 73 20 74 68 61  ed platforms tha
1ad0: 74 20 77 6f 75 6c 64 20 6e 6f 74 20 65 61 73 69  t would not easi
1ae0: 6c 79 20 73 75 70 70 6f 72 74 0a 54 43 4c 20 6f  ly support.TCL o
1af0: 72 20 6f 74 68 65 72 20 77 6f 72 6b 73 74 61 74  r other workstat
1b00: 69 6f 6e 20 73 65 72 76 69 63 65 73 2e 20 20 54  ion services.  T
1b10: 48 33 20 74 65 73 74 73 20 75 73 65 20 6f 6e 6c  H3 tests use onl
1b20: 79 20 74 68 65 20 70 75 62 6c 69 73 68 65 64 20  y the published 
1b30: 0a 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63  .SQLite interfac
1b40: 65 73 2e 20 54 48 33 20 63 6f 6e 73 69 73 74 73  es. TH3 consists
1b50: 20 6f 66 20 61 62 6f 75 74 0a 3c 74 63 6c 3e 4d   of about.<tcl>M
1b60: 42 20 7b 24 73 74 61 74 28 74 68 33 4e 42 79 74  B {$stat(th3NByt
1b70: 65 29 7d 3c 2f 74 63 6c 3e 20 4d 42 20 6f 72 20  e)}</tcl> MB or 
1b80: 3c 74 63 6c 3e 4b 42 20 7b 24 73 74 61 74 28 74  <tcl>KB {$stat(t
1b90: 68 33 53 4c 4f 43 29 7d 3c 2f 74 63 6c 3e 20 4b  h3SLOC)}</tcl> K
1ba0: 53 4c 4f 43 0a 6f 66 20 43 20 63 6f 64 65 20 69  SLOC.of C code i
1bb0: 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 3c 74 63 6c  mplementing <tcl
1bc0: 3e 4e 20 7b 24 73 74 61 74 28 74 68 33 4e 54 65  >N {$stat(th3NTe
1bd0: 73 74 29 7d 3c 2f 74 63 6c 3e 20 64 69 73 74 69  st)}</tcl> disti
1be0: 6e 63 74 20 74 65 73 74 20 63 61 73 65 73 2e 0a  nct test cases..
1bf0: 54 48 33 20 74 65 73 74 73 20 61 72 65 20 68 65  TH3 tests are he
1c00: 61 76 69 6c 79 20 70 61 72 61 6d 65 74 65 72 69  avily parameteri
1c10: 7a 65 64 2c 20 74 68 6f 75 67 68 2c 20 73 6f 20  zed, though, so 
1c20: 61 20 66 75 6c 6c 2d 63 6f 76 65 72 61 67 65 20  a full-coverage 
1c30: 74 65 73 74 20 72 75 6e 73 0a 61 62 6f 75 74 20  test runs.about 
1c40: 3c 74 63 6c 3e 4d 42 20 7b 24 73 74 61 74 28 74  <tcl>MB {$stat(t
1c50: 68 33 4e 45 43 6f 76 29 7d 3c 2f 74 63 6c 3e 20  h3NECov)}</tcl> 
1c60: 6d 69 6c 6c 69 6f 6e 20 64 69 66 66 65 72 65 6e  million differen
1c70: 74 20 74 65 73 74 0a 69 6e 73 74 61 6e 63 65 73  t test.instances
1c80: 2e 20 20 54 68 65 20 63 61 73 65 73 20 74 68 61  .  The cases tha
1c90: 74 20 70 72 6f 76 69 64 65 20 31 30 30 25 20 62  t provide 100% b
1ca0: 72 61 6e 63 68 20 74 65 73 74 20 63 6f 76 65 72  ranch test cover
1cb0: 61 67 65 20 63 6f 6e 73 74 69 74 75 74 65 0a 61  age constitute.a
1cc0: 20 73 75 62 73 65 74 20 6f 66 20 74 68 65 20 74   subset of the t
1cd0: 6f 74 61 6c 20 54 48 33 20 74 65 73 74 20 73 75  otal TH3 test su
1ce0: 69 74 65 2e 20 20 41 20 73 6f 61 6b 20 74 65 73  ite.  A soak tes
1cf0: 74 0a 70 72 69 6f 72 20 74 6f 20 72 65 6c 65 61  t.prior to relea
1d00: 73 65 20 64 6f 65 73 20 68 75 6e 64 72 65 64 73  se does hundreds
1d10: 20 6f 66 20 6d 69 6c 6c 69 6f 6e 73 20 6f 66 20   of millions of 
1d20: 74 65 73 74 73 2e 0a 41 64 64 69 74 69 6f 6e 61  tests..Additiona
1d30: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6f 6e  l information on
1d40: 20 54 48 33 20 69 73 20 5b 54 48 33 20 7c 20 61   TH3 is [TH3 | a
1d50: 76 61 69 6c 61 62 6c 65 20 73 65 70 61 72 61 74  vailable separat
1d60: 65 6c 79 5d 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 0a  ely].</p></li>..
1d70: 3c 6c 69 3e 3c 70 3e 0a 3c 74 63 6c 3e 68 64 5f  <li><p>.<tcl>hd_
1d80: 66 72 61 67 6d 65 6e 74 20 73 6c 74 20 7b 53 4c  fragment slt {SL
1d90: 54 7d 20 7b 53 51 4c 20 4c 6f 67 69 63 20 54 65  T} {SQL Logic Te
1da0: 73 74 73 7d 3c 2f 74 63 6c 3e 0a 54 68 65 20 3c  sts}</tcl>.The <
1db0: 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77  a href="http://w
1dc0: 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 73 71  ww.sqlite.org/sq
1dd0: 6c 6c 6f 67 69 63 74 65 73 74 22 3e 3c 62 3e 53  llogictest"><b>S
1de0: 51 4c 20 4c 6f 67 69 63 20 54 65 73 74 3c 2f 62  QL Logic Test</b
1df0: 3e 3c 2f 61 3e 0a 6f 72 20 53 4c 54 20 74 65 73  ></a>.or SLT tes
1e00: 74 20 68 61 72 6e 65 73 73 20 69 73 20 75 73 65  t harness is use
1e10: 64 20 74 6f 20 72 75 6e 20 68 75 67 65 20 6e 75  d to run huge nu
1e20: 6d 62 65 72 73 0a 6f 66 20 53 51 4c 20 73 74 61  mbers.of SQL sta
1e30: 74 65 6d 65 6e 74 73 20 61 67 61 69 6e 73 74 20  tements against 
1e40: 62 6f 74 68 20 53 51 4c 69 74 65 20 61 6e 64 20  both SQLite and 
1e50: 73 65 76 65 72 61 6c 20 6f 74 68 65 72 20 53 51  several other SQ
1e60: 4c 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  L database engin
1e70: 65 73 0a 61 6e 64 20 76 65 72 69 66 79 20 74 68  es.and verify th
1e80: 61 74 20 74 68 65 79 20 61 6c 6c 20 67 65 74 20  at they all get 
1e90: 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 73  the same answers
1ea0: 2e 20 20 53 4c 54 20 63 75 72 72 65 6e 74 6c 79  .  SLT currently
1eb0: 20 63 6f 6d 70 61 72 65 73 0a 53 51 4c 69 74 65   compares.SQLite
1ec0: 20 61 67 61 69 6e 73 74 20 50 6f 73 74 67 72 65   against Postgre
1ed0: 53 51 4c 2c 20 4d 79 53 51 4c 2c 20 4d 69 63 72  SQL, MySQL, Micr
1ee0: 6f 73 6f 66 74 20 53 51 4c 20 53 65 72 76 65 72  osoft SQL Server
1ef0: 2c 20 61 6e 64 20 4f 72 61 63 6c 65 20 31 30 67  , and Oracle 10g
1f00: 2e 0a 53 4c 54 20 72 75 6e 73 20 3c 74 63 6c 3e  ..SLT runs <tcl>
1f10: 4d 42 20 7b 24 73 74 61 74 28 73 6c 74 4e 54 65  MB {$stat(sltNTe
1f20: 73 74 29 7d 3c 2f 74 63 6c 3e 20 6d 69 6c 6c 69  st)}</tcl> milli
1f30: 6f 6e 20 71 75 65 72 69 65 73 20 63 6f 6d 70 72  on queries compr
1f40: 69 73 69 6e 67 0a 3c 74 63 6c 3e 47 42 20 7b 24  ising.<tcl>GB {$
1f50: 73 74 61 74 28 73 6c 74 73 4e 42 79 74 65 29 7d  stat(sltsNByte)}
1f60: 3c 2f 74 63 6c 3e 47 42 20 6f 66 20 74 65 73 74  </tcl>GB of test
1f70: 20 64 61 74 61 2e 0a 3c 2f 70 3e 3c 2f 6c 69 3e   data..</p></li>
1f80: 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 49 6e 20 61 64  .</ol>..<p>In ad
1f90: 64 69 74 69 6f 6e 20 74 6f 20 74 68 65 20 74 68  dition to the th
1fa0: 72 65 65 20 6d 61 6a 6f 72 20 74 65 73 74 20 68  ree major test h
1fb0: 61 72 6e 65 73 73 65 73 2c 20 74 68 65 72 65 20  arnesses, there 
1fc0: 73 65 76 65 72 61 6c 20 6f 74 68 65 72 0a 73 6d  several other.sm
1fd0: 61 6c 6c 20 70 72 6f 67 72 61 6d 73 20 74 68 61  all programs tha
1fe0: 74 20 69 6d 70 6c 65 6d 65 6e 74 20 73 70 65 63  t implement spec
1ff0: 69 61 6c 69 7a 65 64 20 74 65 73 74 73 2e 0a 3c  ialized tests..<
2000: 6f 6c 3e 0a 3c 6c 69 20 76 61 6c 75 65 3d 22 34  ol>.<li value="4
2010: 22 3e 54 68 65 20 22 73 70 65 65 64 74 65 73 74  ">The "speedtest
2020: 31 2e 63 22 20 70 72 6f 67 72 61 6d 20 0a 65 73  1.c" program .es
2030: 74 69 6d 61 74 65 73 20 74 68 65 20 70 65 72 66  timates the perf
2040: 6f 72 6d 61 6e 63 65 20 6f 66 20 53 51 4c 69 74  ormance of SQLit
2050: 65 20 75 6e 64 65 72 20 61 20 74 79 70 69 63 61  e under a typica
2060: 6c 20 77 6f 72 6b 6c 6f 61 64 2e 20 20 0a 3c 6c  l workload.  .<l
2070: 69 3e 54 68 65 20 22 6d 70 74 65 73 74 65 72 2e  i>The "mptester.
2080: 63 22 20 70 72 6f 67 72 61 6d 20 69 73 20 61 20  c" program is a 
2090: 73 74 72 65 73 73 20 74 65 73 74 20 66 6f 72 20  stress test for 
20a0: 6d 75 6c 74 69 70 6c 65 20 70 72 6f 63 65 73 73  multiple process
20b0: 65 73 20 0a 63 6f 6e 63 75 72 72 65 6e 74 6c 79  es .concurrently
20c0: 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
20d0: 74 69 6e 67 20 61 20 73 69 6e 67 6c 65 20 64 61  ting a single da
20e0: 74 61 62 61 73 65 2e 0a 3c 6c 69 3e 54 68 65 20  tabase..<li>The 
20f0: 22 74 68 72 65 61 64 74 65 73 74 33 2e 63 22 20  "threadtest3.c" 
2100: 70 72 6f 67 72 61 6d 20 69 73 20 61 20 73 74 72  program is a str
2110: 65 73 73 20 74 65 73 74 20 66 6f 72 20 6d 75 6c  ess test for mul
2120: 74 69 70 6c 65 20 74 68 72 65 61 64 73 20 75 73  tiple threads us
2130: 69 6e 67 0a 53 51 4c 69 74 65 20 73 69 6d 75 6c  ing.SQLite simul
2140: 74 61 6e 65 6f 75 73 6c 79 2e 20 20 0a 3c 6c 69  taneously.  .<li
2150: 3e 54 68 65 20 22 66 75 7a 7a 65 72 73 68 65 6c  >The "fuzzershel
2160: 6c 2e 63 22 20 70 72 6f 67 72 61 6d 20 69 73 20  l.c" program is 
2170: 75 73 65 64 20 74 6f 0a 72 75 6e 20 73 6f 6d 65  used to.run some
2180: 20 3c 61 20 68 72 65 66 3d 22 23 66 75 7a 7a 74   <a href="#fuzzt
2190: 65 73 74 69 6e 67 22 3e 66 75 7a 7a 20 74 65 73  esting">fuzz tes
21a0: 74 73 3c 2f 61 3e 2e 0a 3c 2f 6f 6c 3e 0a 3c 2f  ts</a>..</ol>.</
21b0: 70 3e 0a 0a 3c 70 3e 41 6c 6c 20 6f 66 20 74 68  p>..<p>All of th
21c0: 65 20 74 65 73 74 73 20 61 62 6f 76 65 20 6d 75  e tests above mu
21d0: 73 74 20 72 75 6e 20 73 75 63 63 65 73 73 66 75  st run successfu
21e0: 6c 6c 79 2c 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  lly, on multiple
21f0: 20 70 6c 61 74 66 6f 72 6d 73 0a 61 6e 64 20 75   platforms.and u
2200: 6e 64 65 72 20 6d 75 6c 74 69 70 6c 65 20 63 6f  nder multiple co
2210: 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 66 69  mpile-time confi
2220: 67 75 72 61 74 69 6f 6e 73 2c 0a 62 65 66 6f 72  gurations,.befor
2230: 65 20 65 61 63 68 20 72 65 6c 65 61 73 65 20 6f  e each release o
2240: 66 20 53 51 4c 69 74 65 2e 3c 2f 70 3e 0a 0a 3c  f SQLite.</p>..<
2250: 70 3e 50 72 69 6f 72 20 74 6f 20 65 61 63 68 20  p>Prior to each 
2260: 63 68 65 63 6b 2d 69 6e 20 74 6f 20 74 68 65 20  check-in to the 
2270: 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72  SQLite source tr
2280: 65 65 2c 20 64 65 76 65 6c 6f 70 65 72 73 0a 74  ee, developers.t
2290: 79 70 69 63 61 6c 6c 79 20 72 75 6e 20 61 20 73  ypically run a s
22a0: 75 62 73 65 74 20 28 63 61 6c 6c 65 64 20 22 76  ubset (called "v
22b0: 65 72 79 71 75 69 63 6b 22 29 20 6f 66 20 74 68  eryquick") of th
22c0: 65 20 54 63 6c 20 74 65 73 74 73 0a 63 6f 6e 73  e Tcl tests.cons
22d0: 69 73 74 69 6e 67 20 6f 66 20 61 62 6f 75 74 20  isting of about 
22e0: 0a 3c 74 63 6c 3e 4b 42 20 7b 24 73 74 61 74 28  .<tcl>KB {$stat(
22f0: 76 71 4e 45 76 61 6c 29 7d 3c 2f 74 63 6c 3e 20  vqNEval)}</tcl> 
2300: 74 68 6f 75 73 61 6e 64 20 74 65 73 74 20 63 61  thousand test ca
2310: 73 65 73 2e 0a 54 68 65 20 76 65 72 79 71 75 69  ses..The veryqui
2320: 63 6b 20 74 65 73 74 73 20 69 6e 63 6c 75 64 65  ck tests include
2330: 20 6d 6f 73 74 20 74 65 73 74 73 20 6f 74 68 65   most tests othe
2340: 72 20 74 68 61 6e 20 74 68 65 20 61 6e 6f 6d 61  r than the anoma
2350: 6c 79 2c 20 66 75 7a 7a 2c 20 61 6e 64 20 0a 73  ly, fuzz, and .s
2360: 6f 61 6b 20 74 65 73 74 73 2e 20 20 54 68 65 20  oak tests.  The 
2370: 69 64 65 61 20 62 65 68 69 6e 64 20 74 68 65 20  idea behind the 
2380: 76 65 72 79 71 75 69 63 6b 20 74 65 73 74 73 20  veryquick tests 
2390: 61 72 65 20 74 68 61 74 20 74 68 65 79 20 61 72  are that they ar
23a0: 65 0a 73 75 66 66 69 63 69 65 6e 74 20 74 6f 20  e.sufficient to 
23b0: 63 61 74 63 68 20 6d 6f 73 74 20 65 72 72 6f 72  catch most error
23c0: 73 2c 20 62 75 74 20 61 6c 73 6f 20 72 75 6e 20  s, but also run 
23d0: 69 6e 20 6f 6e 6c 79 20 61 20 66 65 77 20 6d 69  in only a few mi
23e0: 6e 75 74 65 73 0a 69 6e 73 74 65 61 64 20 6f 66  nutes.instead of
23f0: 20 61 20 66 65 77 20 68 6f 75 72 73 2e 3c 2f 70   a few hours.</p
2400: 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  >..<tcl>hd_fragm
2410: 65 6e 74 20 61 6e 6f 6d 6f 6c 79 3c 2f 74 63 6c  ent anomoly</tcl
2420: 3e 0a 3c 68 31 3e 41 6e 6f 6d 61 6c 79 20 54 65  >.<h1>Anomaly Te
2430: 73 74 69 6e 67 3c 2f 68 31 3e 0a 0a 3c 70 3e 41  sting</h1>..<p>A
2440: 6e 6f 6d 61 6c 79 20 74 65 73 74 73 20 61 72 65  nomaly tests are
2450: 20 74 65 73 74 73 20 64 65 73 69 67 6e 65 64 20   tests designed 
2460: 74 6f 20 76 65 72 69 66 79 20 74 68 65 20 63 6f  to verify the co
2470: 72 72 65 63 74 20 62 65 68 61 76 69 6f 72 0a 6f  rrect behavior.o
2480: 66 20 53 51 4c 69 74 65 20 77 68 65 6e 20 73 6f  f SQLite when so
2490: 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
24a0: 6e 67 2e 20 20 49 74 20 69 73 20 28 72 65 6c 61  ng.  It is (rela
24b0: 74 69 76 65 6c 79 29 20 65 61 73 79 20 74 6f 20  tively) easy to 
24c0: 62 75 69 6c 64 0a 61 6e 20 53 51 4c 20 64 61 74  build.an SQL dat
24d0: 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 68 61  abase engine tha
24e0: 74 20 62 65 68 61 76 65 73 20 63 6f 72 72 65 63  t behaves correc
24f0: 74 6c 79 20 6f 6e 20 77 65 6c 6c 2d 66 6f 72 6d  tly on well-form
2500: 65 64 20 69 6e 70 75 74 73 0a 6f 6e 20 61 20 66  ed inputs.on a f
2510: 75 6c 6c 79 20 66 75 6e 63 74 69 6f 6e 61 6c 20  ully functional 
2520: 63 6f 6d 70 75 74 65 72 2e 20 20 49 74 20 69 73  computer.  It is
2530: 20 6d 6f 72 65 20 64 69 66 66 69 63 75 6c 74 20   more difficult 
2540: 74 6f 20 62 75 69 6c 64 20 61 20 73 79 73 74 65  to build a syste
2550: 6d 0a 74 68 61 74 20 72 65 73 70 6f 6e 64 73 20  m.that responds 
2560: 73 61 6e 65 6c 79 20 74 6f 20 69 6e 76 61 6c 69  sanely to invali
2570: 64 20 69 6e 70 75 74 73 20 61 6e 64 20 63 6f 6e  d inputs and con
2580: 74 69 6e 75 65 73 20 74 6f 20 66 75 6e 63 74 69  tinues to functi
2590: 6f 6e 20 66 6f 6c 6c 6f 77 69 6e 67 0a 73 79 73  on following.sys
25a0: 74 65 6d 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 73  tem malfunctions
25b0: 2e 20 20 54 68 65 20 61 6e 6f 6d 61 6c 79 20 74  .  The anomaly t
25c0: 65 73 74 73 20 61 72 65 20 64 65 73 69 67 6e 65  ests are designe
25d0: 64 20 74 6f 20 76 65 72 69 66 79 20 74 68 65 20  d to verify the 
25e0: 6c 61 74 74 65 72 0a 62 65 68 61 76 69 6f 72 2e  latter.behavior.
25f0: 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72  </p>..<tcl>hd_fr
2600: 61 67 6d 65 6e 74 20 6f 6f 6d 74 65 73 74 69 6e  agment oomtestin
2610: 67 3c 2f 74 63 6c 3e 0a 3c 68 32 3e 4f 75 74 2d  g</tcl>.<h2>Out-
2620: 4f 66 2d 4d 65 6d 6f 72 79 20 54 65 73 74 69 6e  Of-Memory Testin
2630: 67 3c 2f 68 32 3e 0a 0a 3c 70 3e 53 51 4c 69 74  g</h2>..<p>SQLit
2640: 65 2c 20 6c 69 6b 65 20 61 6c 6c 20 53 51 4c 20  e, like all SQL 
2650: 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 73  database engines
2660: 2c 20 6d 61 6b 65 73 20 65 78 74 65 6e 73 69 76  , makes extensiv
2670: 65 20 75 73 65 20 6f 66 0a 6d 61 6c 6c 6f 63 28  e use of.malloc(
2680: 29 20 20 28 53 65 65 20 74 68 65 20 73 65 70 61  )  (See the sepa
2690: 72 61 74 65 20 72 65 70 6f 72 74 20 6f 6e 0a 5b  rate report on.[
26a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
26b0: 6e 20 7c 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  n | dynamic memo
26c0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e  ry allocation in
26d0: 20 53 51 4c 69 74 65 5d 20 66 6f 72 0a 61 64 64   SQLite] for.add
26e0: 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 2e 29  itional detail.)
26f0: 0a 4f 6e 20 73 65 72 76 65 72 73 20 61 6e 64 20  .On servers and 
2700: 77 6f 72 6b 73 74 61 74 69 6f 6e 73 2c 20 6d 61  workstations, ma
2710: 6c 6c 6f 63 28 29 20 6e 65 76 65 72 20 66 61 69  lloc() never fai
2720: 6c 73 20 69 6e 20 70 72 61 63 74 69 63 65 20 61  ls in practice a
2730: 6e 64 20 73 6f 20 63 6f 72 72 65 63 74 0a 68 61  nd so correct.ha
2740: 6e 64 6c 69 6e 67 20 6f 66 20 6f 75 74 2d 6f 66  ndling of out-of
2750: 2d 6d 65 6d 6f 72 79 20 28 4f 4f 4d 29 20 65 72  -memory (OOM) er
2760: 72 6f 72 73 20 69 73 20 6e 6f 74 20 70 61 72 74  rors is not part
2770: 69 63 75 6c 61 72 6c 79 20 69 6d 70 6f 72 74 61  icularly importa
2780: 6e 74 2e 0a 42 75 74 20 6f 6e 20 65 6d 62 65 64  nt..But on embed
2790: 64 65 64 20 64 65 76 69 63 65 73 2c 20 4f 4f 4d  ded devices, OOM
27a0: 20 65 72 72 6f 72 73 20 61 72 65 20 66 72 69 67   errors are frig
27b0: 68 74 65 6e 69 6e 67 6c 79 20 63 6f 6d 6d 6f 6e  hteningly common
27c0: 20 61 6e 64 20 73 69 6e 63 65 0a 53 51 4c 69 74   and since.SQLit
27d0: 65 20 69 73 20 66 72 65 71 75 65 6e 74 6c 79 20  e is frequently 
27e0: 75 73 65 64 20 6f 6e 20 65 6d 62 65 64 64 65 64  used on embedded
27f0: 20 64 65 76 69 63 65 73 2c 20 69 74 20 69 73 20   devices, it is 
2800: 69 6d 70 6f 72 74 61 6e 74 20 74 68 61 74 0a 53  important that.S
2810: 51 4c 69 74 65 20 62 65 20 61 62 6c 65 20 74 6f  QLite be able to
2820: 20 67 72 61 63 65 66 75 6c 6c 79 20 68 61 6e 64   gracefully hand
2830: 6c 65 20 4f 4f 4d 20 65 72 72 6f 72 73 2e 3c 2f  le OOM errors.</
2840: 70 3e 0a 0a 3c 70 3e 4f 4f 4d 20 74 65 73 74 69  p>..<p>OOM testi
2850: 6e 67 20 69 73 20 61 63 63 6f 6d 70 6c 69 73 68  ng is accomplish
2860: 65 64 20 62 79 20 73 69 6d 75 6c 61 74 69 6e 67  ed by simulating
2870: 20 4f 4f 4d 20 65 72 72 6f 72 73 2e 0a 53 51 4c   OOM errors..SQL
2880: 69 74 65 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  ite allows an ap
2890: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 73 75 62  plication to sub
28a0: 73 74 69 74 75 74 65 20 61 6e 20 61 6c 74 65 72  stitute an alter
28b0: 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 0a  native malloc().
28c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
28d0: 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
28e0: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
28f0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
2900: 2c 2e 2e 2e 29 0a 69 6e 74 65 72 66 61 63 65 2e  ,...).interface.
2910: 20 20 54 68 65 20 54 43 4c 20 61 6e 64 20 54 48    The TCL and TH
2920: 33 20 74 65 73 74 20 68 61 72 6e 65 73 73 65 73  3 test harnesses
2930: 20 61 72 65 20 62 6f 74 68 20 63 61 70 61 62 6c   are both capabl
2940: 65 20 6f 66 0a 69 6e 73 65 72 74 69 6e 67 20 61  e of.inserting a
2950: 20 6d 6f 64 69 66 69 65 64 20 76 65 72 73 69 6f   modified versio
2960: 6e 20 6f 66 20 6d 61 6c 6c 6f 63 28 29 20 74 68  n of malloc() th
2970: 61 74 20 63 61 6e 20 62 65 20 72 69 67 67 65 64  at can be rigged
2980: 20 74 6f 20 66 61 69 6c 20 0a 61 66 74 65 72 20   to fail .after 
2990: 61 20 63 65 72 74 61 69 6e 20 6e 75 6d 62 65 72  a certain number
29a0: 20 6f 66 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e   of allocations.
29b0: 20 20 54 68 65 73 65 20 69 6e 73 74 72 75 6d 65    These instrume
29c0: 6e 74 65 64 20 6d 61 6c 6c 6f 63 73 0a 63 61 6e  nted mallocs.can
29d0: 20 62 65 20 73 65 74 20 74 6f 20 66 61 69 6c 20   be set to fail 
29e0: 6f 6e 6c 79 20 6f 6e 63 65 20 61 6e 64 20 74 68  only once and th
29f0: 65 6e 20 73 74 61 72 74 20 77 6f 72 6b 69 6e 67  en start working
2a00: 20 61 67 61 69 6e 2c 20 6f 72 20 74 6f 0a 63 6f   again, or to.co
2a10: 6e 74 69 6e 75 65 20 66 61 69 6c 69 6e 67 20 61  ntinue failing a
2a20: 66 74 65 72 20 74 68 65 20 66 69 72 73 74 20 66  fter the first f
2a30: 61 69 6c 75 72 65 2e 20 20 4f 4f 4d 20 74 65 73  ailure.  OOM tes
2a40: 74 73 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 61  ts are done in a
2a50: 0a 6c 6f 6f 70 2e 20 20 4f 6e 20 74 68 65 20 66  .loop.  On the f
2a60: 69 72 73 74 20 69 74 65 72 61 74 69 6f 6e 20 6f  irst iteration o
2a70: 66 20 74 68 65 20 6c 6f 6f 70 2c 20 74 68 65 20  f the loop, the 
2a80: 69 6e 73 74 72 75 6d 65 6e 74 65 64 20 6d 61 6c  instrumented mal
2a90: 6c 6f 63 0a 69 73 20 72 69 67 67 65 64 20 74 6f  loc.is rigged to
2aa0: 20 66 61 69 6c 20 6f 6e 20 74 68 65 20 66 69 72   fail on the fir
2ab0: 73 74 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20  st allocation.  
2ac0: 54 68 65 6e 20 73 6f 6d 65 20 53 51 4c 69 74 65  Then some SQLite
2ad0: 20 6f 70 65 72 61 74 69 6f 6e 0a 69 73 20 63 61   operation.is ca
2ae0: 72 72 69 65 64 20 6f 75 74 20 61 6e 64 20 63 68  rried out and ch
2af0: 65 63 6b 73 20 61 72 65 20 64 6f 6e 65 20 74 6f  ecks are done to
2b00: 20 6d 61 6b 65 20 73 75 72 65 20 53 51 4c 69 74   make sure SQLit
2b10: 65 20 68 61 6e 64 6c 65 64 20 74 68 65 0a 4f 4f  e handled the.OO
2b20: 4d 20 65 72 72 6f 72 20 63 6f 72 72 65 63 74 6c  M error correctl
2b30: 79 2e 20 20 54 68 65 6e 20 74 68 65 20 74 69 6d  y.  Then the tim
2b40: 65 2d 74 6f 2d 66 61 69 6c 75 72 65 20 63 6f 75  e-to-failure cou
2b50: 6e 74 65 72 0a 6f 6e 20 74 68 65 20 69 6e 73 74  nter.on the inst
2b60: 72 75 6d 65 6e 74 65 64 20 6d 61 6c 6c 6f 63 20  rumented malloc 
2b70: 69 73 20 69 6e 63 72 65 61 73 65 64 20 62 79 20  is increased by 
2b80: 6f 6e 65 20 61 6e 64 20 74 68 65 20 74 65 73 74  one and the test
2b90: 20 69 73 0a 72 65 70 65 61 74 65 64 2e 20 20 54   is.repeated.  T
2ba0: 68 65 20 6c 6f 6f 70 20 63 6f 6e 74 69 6e 75 65  he loop continue
2bb0: 73 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 74 69  s until the enti
2bc0: 72 65 20 6f 70 65 72 61 74 69 6f 6e 20 72 75 6e  re operation run
2bd0: 73 20 74 6f 0a 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to.completion 
2be0: 77 69 74 68 6f 75 74 20 65 76 65 72 20 65 6e 63  without ever enc
2bf0: 6f 75 6e 74 65 72 69 6e 67 20 61 20 73 69 6d 75  ountering a simu
2c00: 6c 61 74 65 64 20 4f 4f 4d 20 66 61 69 6c 75 72  lated OOM failur
2c10: 65 2e 0a 54 65 73 74 73 20 6c 69 6b 65 20 74 68  e..Tests like th
2c20: 69 73 20 61 72 65 20 72 75 6e 20 74 77 69 63 65  is are run twice
2c30: 2c 20 6f 6e 63 65 20 77 69 74 68 20 74 68 65 20  , once with the 
2c40: 69 6e 73 74 72 75 6d 65 6e 74 65 64 20 6d 61 6c  instrumented mal
2c50: 6c 6f 63 0a 73 65 74 20 74 6f 20 66 61 69 6c 20  loc.set to fail 
2c60: 6f 6e 6c 79 20 6f 6e 63 65 2c 20 61 6e 64 20 61  only once, and a
2c70: 67 61 69 6e 20 77 69 74 68 20 74 68 65 20 69 6e  gain with the in
2c80: 73 74 72 75 6d 65 6e 74 65 64 20 6d 61 6c 6c 6f  strumented mallo
2c90: 63 20 73 65 74 0a 74 6f 20 66 61 69 6c 20 63 6f  c set.to fail co
2ca0: 6e 74 69 6e 75 6f 75 73 6c 79 20 61 66 74 65 72  ntinuously after
2cb0: 20 74 68 65 20 66 69 72 73 74 20 66 61 69 6c 75   the first failu
2cc0: 72 65 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64  re.</p>..<tcl>hd
2cd0: 5f 66 72 61 67 6d 65 6e 74 20 69 6f 65 72 72 74  _fragment ioerrt
2ce0: 65 73 74 69 6e 67 3c 2f 74 63 6c 3e 0a 3c 68 32  esting</tcl>.<h2
2cf0: 3e 49 2f 4f 20 45 72 72 6f 72 20 54 65 73 74 69  >I/O Error Testi
2d00: 6e 67 3c 2f 68 32 3e 0a 0a 3c 70 3e 49 2f 4f 20  ng</h2>..<p>I/O 
2d10: 65 72 72 6f 72 20 74 65 73 74 69 6e 67 20 73 65  error testing se
2d20: 65 6b 73 20 74 6f 20 76 65 72 69 66 79 20 74 68  eks to verify th
2d30: 61 74 20 53 51 4c 69 74 65 20 72 65 73 70 6f 6e  at SQLite respon
2d40: 64 73 20 73 61 6e 65 6c 79 0a 74 6f 20 66 61 69  ds sanely.to fai
2d50: 6c 65 64 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  led I/O operatio
2d60: 6e 73 2e 20 20 49 2f 4f 20 65 72 72 6f 72 73 20  ns.  I/O errors 
2d70: 6d 69 67 68 74 20 72 65 73 75 6c 74 20 66 72 6f  might result fro
2d80: 6d 20 61 20 66 75 6c 6c 20 64 69 73 6b 20 64 72  m a full disk dr
2d90: 69 76 65 2c 0a 6d 61 6c 66 75 6e 63 74 69 6f 6e  ive,.malfunction
2da0: 69 6e 67 20 64 69 73 6b 20 68 61 72 64 77 61 72  ing disk hardwar
2db0: 65 2c 20 6e 65 74 77 6f 72 6b 20 6f 75 74 61 67  e, network outag
2dc0: 65 73 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20  es when using a 
2dd0: 6e 65 74 77 6f 72 6b 0a 66 69 6c 65 20 73 79 73  network.file sys
2de0: 74 65 6d 2c 20 73 79 73 74 65 6d 20 63 6f 6e 66  tem, system conf
2df0: 69 67 75 72 61 74 69 6f 6e 20 6f 72 20 70 65 72  iguration or per
2e00: 6d 69 73 73 69 6f 6e 20 63 68 61 6e 67 65 73 20  mission changes 
2e10: 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
2e20: 65 20 0a 6d 69 64 64 6c 65 20 6f 66 20 61 6e 20  e .middle of an 
2e30: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 2c 20 6f  SQL operation, o
2e40: 72 20 6f 74 68 65 72 20 68 61 72 64 77 61 72 65  r other hardware
2e50: 20 6f 72 20 6f 70 65 72 61 74 69 6e 67 20 73 79   or operating sy
2e60: 73 74 65 6d 20 0a 6d 61 6c 66 75 6e 63 74 69 6f  stem .malfunctio
2e70: 6e 73 2e 20 20 57 68 61 74 65 76 65 72 20 74 68  ns.  Whatever th
2e80: 65 20 63 61 75 73 65 2c 20 69 74 20 69 73 20 69  e cause, it is i
2e90: 6d 70 6f 72 74 61 6e 74 20 74 68 61 74 20 53 51  mportant that SQ
2ea0: 4c 69 74 65 20 62 65 20 61 62 6c 65 0a 74 6f 20  Lite be able.to 
2eb0: 72 65 73 70 6f 6e 64 20 63 6f 72 72 65 63 74 6c  respond correctl
2ec0: 79 20 74 6f 20 74 68 65 73 65 20 65 72 72 6f 72  y to these error
2ed0: 73 20 61 6e 64 20 49 2f 4f 20 65 72 72 6f 72 20  s and I/O error 
2ee0: 74 65 73 74 69 6e 67 20 73 65 65 6b 73 20 74 6f  testing seeks to
2ef0: 0a 76 65 72 69 66 79 20 74 68 61 74 20 69 74 20  .verify that it 
2f00: 64 6f 65 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e 49 2f  does.</p>..<p>I/
2f10: 4f 20 65 72 72 6f 72 20 74 65 73 74 69 6e 67 20  O error testing 
2f20: 69 73 20 73 69 6d 69 6c 61 72 20 69 6e 20 63 6f  is similar in co
2f30: 6e 63 65 70 74 20 74 6f 20 4f 4f 4d 20 74 65 73  ncept to OOM tes
2f40: 74 69 6e 67 3b 20 49 2f 4f 20 65 72 72 6f 72 73  ting; I/O errors
2f50: 0a 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 61  .are simulated a
2f60: 6e 64 20 63 68 65 63 6b 73 20 61 72 65 20 6d 61  nd checks are ma
2f70: 64 65 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  de to verify tha
2f80: 74 20 53 51 4c 69 74 65 20 72 65 73 70 6f 6e 64  t SQLite respond
2f90: 73 0a 63 6f 72 72 65 63 74 6c 79 20 74 6f 20 74  s.correctly to t
2fa0: 68 65 20 73 69 6d 75 6c 61 74 65 64 20 65 72 72  he simulated err
2fb0: 6f 72 73 2e 20 20 49 2f 4f 20 65 72 72 6f 72 73  ors.  I/O errors
2fc0: 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 69   are simulated i
2fd0: 6e 20 62 6f 74 68 0a 74 68 65 20 54 43 4c 20 61  n both.the TCL a
2fe0: 6e 64 20 54 48 33 20 74 65 73 74 20 68 61 72 6e  nd TH3 test harn
2ff0: 65 73 73 65 73 20 62 79 20 69 6e 73 65 72 74 69  esses by inserti
3000: 6e 67 20 61 20 6e 65 77 0a 5b 73 71 6c 69 74 65  ng a new.[sqlite
3010: 33 5f 76 66 73 20 7c 20 56 69 72 74 75 61 6c 20  3_vfs | Virtual 
3020: 46 69 6c 65 20 53 79 73 74 65 6d 20 6f 62 6a 65  File System obje
3030: 63 74 5d 20 74 68 61 74 20 69 73 20 73 70 65 63  ct] that is spec
3040: 69 61 6c 6c 79 20 72 69 67 67 65 64 0a 74 6f 20  ially rigged.to 
3050: 73 69 6d 75 6c 61 74 65 20 61 6e 20 49 2f 4f 20  simulate an I/O 
3060: 65 72 72 6f 72 20 61 66 74 65 72 20 61 20 73 65  error after a se
3070: 74 20 6e 75 6d 62 65 72 20 6f 66 20 49 2f 4f 20  t number of I/O 
3080: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 41 73 20 77  operations..As w
3090: 69 74 68 20 4f 4f 4d 20 65 72 72 6f 72 20 74 65  ith OOM error te
30a0: 73 74 69 6e 67 2c 20 74 68 65 20 49 2f 4f 20 65  sting, the I/O e
30b0: 72 72 6f 72 20 73 69 6d 75 6c 61 74 6f 72 73 20  rror simulators 
30c0: 63 61 6e 20 62 65 20 73 65 74 20 74 6f 0a 66 61  can be set to.fa
30d0: 69 6c 20 6a 75 73 74 20 6f 6e 63 65 2c 20 6f 72  il just once, or
30e0: 20 74 6f 20 66 61 69 6c 20 63 6f 6e 74 69 6e 75   to fail continu
30f0: 6f 75 73 6c 79 20 61 66 74 65 72 20 74 68 65 20  ously after the 
3100: 66 69 72 73 74 20 66 61 69 6c 75 72 65 2e 0a 54  first failure..T
3110: 65 73 74 73 20 61 72 65 20 72 75 6e 20 69 6e 20  ests are run in 
3120: 61 20 6c 6f 6f 70 2c 20 73 6c 6f 77 6c 79 20 69  a loop, slowly i
3130: 6e 63 72 65 61 73 69 6e 67 20 74 68 65 20 70 6f  ncreasing the po
3140: 69 6e 74 20 6f 66 20 66 61 69 6c 75 72 65 20 75  int of failure u
3150: 6e 74 69 6c 0a 74 68 65 20 74 65 73 74 20 63 61  ntil.the test ca
3160: 73 65 20 72 75 6e 73 20 74 6f 20 63 6f 6d 70 6c  se runs to compl
3170: 65 74 69 6f 6e 20 77 69 74 68 6f 75 74 20 65 72  etion without er
3180: 72 6f 72 2e 20 20 54 68 65 20 6c 6f 6f 70 20 69  ror.  The loop i
3190: 73 20 72 75 6e 20 74 77 69 63 65 2c 0a 6f 6e 63  s run twice,.onc
31a0: 65 20 77 69 74 68 20 74 68 65 20 49 2f 4f 20 65  e with the I/O e
31b0: 72 72 6f 72 20 73 69 6d 75 6c 61 74 6f 72 20 73  rror simulator s
31c0: 65 74 20 74 6f 20 73 69 6d 75 6c 61 74 65 20 6f  et to simulate o
31d0: 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 66 61 69  nly a single fai
31e0: 6c 75 72 65 0a 61 6e 64 20 61 20 73 65 63 6f 6e  lure.and a secon
31f0: 64 20 74 69 6d 65 20 77 69 74 68 20 69 74 20 73  d time with it s
3200: 65 74 20 74 6f 20 66 61 69 6c 20 61 6c 6c 20 49  et to fail all I
3210: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 66  /O operations af
3220: 74 65 72 20 74 68 65 20 66 69 72 73 74 0a 66 61  ter the first.fa
3230: 69 6c 75 72 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e 49  ilure.</p>..<p>I
3240: 6e 20 49 2f 4f 20 65 72 72 6f 72 20 74 65 73 74  n I/O error test
3250: 73 2c 20 61 66 74 65 72 20 74 68 65 20 49 2f 4f  s, after the I/O
3260: 20 65 72 72 6f 72 20 73 69 6d 75 6c 61 74 69 6f   error simulatio
3270: 6e 20 66 61 69 6c 75 72 65 20 6d 65 63 68 61 6e  n failure mechan
3280: 69 73 6d 0a 69 73 20 64 69 73 61 62 6c 65 64 2c  ism.is disabled,
3290: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
32a0: 20 65 78 61 6d 69 6e 65 64 20 75 73 69 6e 67 0a   examined using.
32b0: 5b 50 52 41 47 4d 41 20 69 6e 74 65 67 72 69 74  [PRAGMA integrit
32c0: 79 5f 63 68 65 63 6b 5d 20 74 6f 20 6d 61 6b 65  y_check] to make
32d0: 20 73 75 72 65 20 74 68 61 74 20 74 68 65 20 49   sure that the I
32e0: 2f 4f 20 65 72 72 6f 72 20 68 61 73 20 6e 6f 74  /O error has not
32f0: 0a 69 6e 74 72 6f 64 75 63 65 64 20 64 61 74 61  .introduced data
3300: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
3310: 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72  </p>..<tcl>hd_fr
3320: 61 67 6d 65 6e 74 20 63 72 61 73 68 74 65 73 74  agment crashtest
3330: 69 6e 67 3c 2f 74 63 6c 3e 0a 3c 68 32 3e 43 72  ing</tcl>.<h2>Cr
3340: 61 73 68 20 54 65 73 74 69 6e 67 3c 2f 68 32 3e  ash Testing</h2>
3350: 0a 0a 3c 70 3e 43 72 61 73 68 20 74 65 73 74 69  ..<p>Crash testi
3360: 6e 67 20 73 65 65 6b 73 20 74 6f 20 64 65 6d 6f  ng seeks to demo
3370: 6e 73 74 72 61 74 65 20 74 68 61 74 20 61 6e 20  nstrate that an 
3380: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
3390: 77 69 6c 6c 20 6e 6f 74 0a 67 6f 20 63 6f 72 72  will not.go corr
33a0: 75 70 74 20 69 66 20 74 68 65 20 61 70 70 6c 69  upt if the appli
33b0: 63 61 74 69 6f 6e 20 6f 72 20 6f 70 65 72 61 74  cation or operat
33c0: 69 6e 67 20 73 79 73 74 65 6d 20 63 72 61 73 68  ing system crash
33d0: 65 73 20 6f 72 20 69 66 20 74 68 65 72 65 0a 69  es or if there.i
33e0: 73 20 61 20 70 6f 77 65 72 20 66 61 69 6c 75 72  s a power failur
33f0: 65 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  e in the middle 
3400: 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 75 70  of a database up
3410: 64 61 74 65 2e 20 20 41 20 73 65 70 61 72 61 74  date.  A separat
3420: 65 0a 77 68 69 74 65 2d 70 61 70 65 72 20 74 69  e.white-paper ti
3430: 74 6c 65 64 0a 3c 61 20 68 72 65 66 3d 22 61 74  tled.<a href="at
3440: 6f 6d 69 63 63 6f 6d 6d 69 74 2e 68 74 6d 6c 22  omiccommit.html"
3450: 3e 41 74 6f 6d 69 63 20 43 6f 6d 6d 69 74 20 69  >Atomic Commit i
3460: 6e 20 53 51 4c 69 74 65 3c 2f 61 3e 20 64 65 73  n SQLite</a> des
3470: 63 72 69 62 65 73 20 74 68 65 0a 64 65 66 65 6e  cribes the.defen
3480: 73 69 76 65 20 6d 65 61 73 75 72 65 20 53 51 4c  sive measure SQL
3490: 69 74 65 20 74 61 6b 65 73 20 74 6f 20 70 72 65  ite takes to pre
34a0: 76 65 6e 74 20 64 61 74 61 62 61 73 65 20 63 6f  vent database co
34b0: 72 72 75 70 74 69 6f 6e 20 66 6f 6c 6c 6f 77 69  rruption followi
34c0: 6e 67 0a 61 20 63 72 61 73 68 2e 20 20 43 72 61  ng.a crash.  Cra
34d0: 73 68 20 74 65 73 74 73 20 73 74 72 69 76 65 20  sh tests strive 
34e0: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 74  to verify that t
34f0: 68 6f 73 65 20 64 65 66 65 6e 73 69 76 65 20 6d  hose defensive m
3500: 65 61 73 75 72 65 73 0a 61 72 65 20 77 6f 72 6b  easures.are work
3510: 69 6e 67 20 63 6f 72 72 65 63 74 6c 79 2e 3c 2f  ing correctly.</
3520: 70 3e 0a 0a 3c 70 3e 49 74 20 69 73 20 69 6d 70  p>..<p>It is imp
3530: 72 61 63 74 69 63 61 6c 20 74 6f 20 64 6f 20 63  ractical to do c
3540: 72 61 73 68 20 74 65 73 74 69 6e 67 20 75 73 69  rash testing usi
3550: 6e 67 20 72 65 61 6c 20 70 6f 77 65 72 20 66 61  ng real power fa
3560: 69 6c 75 72 65 73 2c 20 6f 66 0a 63 6f 75 72 73  ilures, of.cours
3570: 65 2c 20 61 6e 64 20 73 6f 20 63 72 61 73 68 20  e, and so crash 
3580: 74 65 73 74 69 6e 67 20 69 73 20 64 6f 6e 65 20  testing is done 
3590: 69 6e 20 73 69 6d 75 6c 61 74 69 6f 6e 2e 20 20  in simulation.  
35a0: 41 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 5b  An alternative.[
35b0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 69  sqlite3_vfs | Vi
35c0: 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65  rtual File Syste
35d0: 6d 5d 20 69 73 20 69 6e 73 65 72 74 65 64 20 74  m] is inserted t
35e0: 68 61 74 20 61 6c 6c 6f 77 73 20 74 68 65 20 74  hat allows the t
35f0: 65 73 74 0a 68 61 72 6e 65 73 73 20 74 6f 20 73  est.harness to s
3600: 69 6d 75 6c 61 74 65 20 74 68 65 20 73 74 61 74  imulate the stat
3610: 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
3620: 65 20 66 69 6c 65 20 66 6f 6c 6c 6f 77 69 6e 67  e file following
3630: 20 61 20 63 72 61 73 68 2e 3c 2f 70 3e 0a 0a 3c   a crash.</p>..<
3640: 70 3e 49 6e 20 74 68 65 20 54 43 4c 20 74 65 73  p>In the TCL tes
3650: 74 20 68 61 72 6e 65 73 73 2c 20 74 68 65 20 63  t harness, the c
3660: 72 61 73 68 20 73 69 6d 75 6c 61 74 69 6f 6e 20  rash simulation 
3670: 69 73 20 64 6f 6e 65 20 69 6e 20 61 20 73 65 70  is done in a sep
3680: 61 72 61 74 65 0a 70 72 6f 63 65 73 73 2e 20 20  arate.process.  
3690: 54 68 65 20 6d 61 69 6e 20 74 65 73 74 69 6e 67  The main testing
36a0: 20 70 72 6f 63 65 73 73 20 73 70 61 77 6e 73 20   process spawns 
36b0: 61 20 63 68 69 6c 64 20 70 72 6f 63 65 73 73 20  a child process 
36c0: 77 68 69 63 68 20 72 75 6e 73 0a 73 6f 6d 65 20  which runs.some 
36d0: 53 51 4c 69 74 65 20 6f 70 65 72 61 74 69 6f 6e  SQLite operation
36e0: 20 61 6e 64 20 72 61 6e 64 6f 6d 6c 79 20 63 72   and randomly cr
36f0: 61 73 68 65 73 20 73 6f 6d 65 77 68 65 72 65 20  ashes somewhere 
3700: 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
3710: 0a 61 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  .a write operati
3720: 6f 6e 2e 20 20 41 20 73 70 65 63 69 61 6c 20 5b  on.  A special [
3730: 56 46 53 5d 20 72 61 6e 64 6f 6d 6c 79 20 72 65  VFS] randomly re
3740: 6f 72 64 65 72 73 20 61 6e 64 20 63 6f 72 72 75  orders and corru
3750: 70 74 73 0a 74 68 65 20 75 6e 73 79 6e 63 68 72  pts.the unsynchr
3760: 6f 6e 69 7a 65 64 0a 77 72 69 74 65 20 6f 70 65  onized.write ope
3770: 72 61 74 69 6f 6e 73 20 74 6f 20 73 69 6d 75 6c  rations to simul
3780: 61 74 65 20 74 68 65 20 65 66 66 65 63 74 20 6f  ate the effect o
3790: 66 20 62 75 66 66 65 72 65 64 20 66 69 6c 65 73  f buffered files
37a0: 79 73 74 65 6d 73 2e 20 20 41 66 74 65 72 0a 74  ystems.  After.t
37b0: 68 65 20 63 68 69 6c 64 20 64 69 65 73 2c 20 74  he child dies, t
37c0: 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65 73 74  he original test
37d0: 20 70 72 6f 63 65 73 73 20 6f 70 65 6e 73 20 61   process opens a
37e0: 6e 64 20 72 65 61 64 73 20 74 68 65 20 74 65 73  nd reads the tes
37f0: 74 0a 64 61 74 61 62 61 73 65 20 61 6e 64 20 76  t.database and v
3800: 65 72 69 66 69 65 73 20 74 68 61 74 20 74 68 65  erifies that the
3810: 20 63 68 61 6e 67 65 73 20 61 74 74 65 6d 70 74   changes attempt
3820: 65 64 20 62 79 20 74 68 65 20 63 68 69 6c 64 20  ed by the child 
3830: 65 69 74 68 65 72 0a 63 6f 6d 70 6c 65 74 65 64  either.completed
3840: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72   successfully or
3850: 20 65 6c 73 65 20 77 65 72 65 20 63 6f 6d 70 6c   else were compl
3860: 65 74 65 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  etely rolled bac
3870: 6b 2e 20 20 54 68 65 0a 5b 69 6e 74 65 67 72 69  k.  The.[integri
3880: 74 79 5f 63 68 65 63 6b 5d 20 5b 50 52 41 47 4d  ty_check] [PRAGM
3890: 41 5d 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  A] is used to ma
38a0: 6b 65 20 73 75 72 65 20 6e 6f 20 64 61 74 61 62  ke sure no datab
38b0: 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 0a 6f  ase corruption.o
38c0: 63 63 75 72 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54  ccurs.</p>..<p>T
38d0: 68 65 20 54 48 33 20 74 65 73 74 20 68 61 72 6e  he TH3 test harn
38e0: 65 73 73 20 6e 65 65 64 73 20 74 6f 20 72 75 6e  ess needs to run
38f0: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
3900: 74 65 6d 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  tems that do not
3910: 0a 6e 65 63 65 73 73 61 72 69 6c 79 20 68 61 76  .necessarily hav
3920: 65 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  e the ability to
3930: 20 73 70 61 77 6e 20 63 68 69 6c 64 20 70 72 6f   spawn child pro
3940: 63 65 73 73 65 73 2c 20 73 6f 20 69 74 20 75 73  cesses, so it us
3950: 65 73 0a 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 20  es.an in-memory 
3960: 5b 56 46 53 5d 20 74 6f 20 73 69 6d 75 6c 61 74  [VFS] to simulat
3970: 65 20 63 72 61 73 68 65 73 2e 20 20 54 68 65 20  e crashes.  The 
3980: 69 6e 2d 6d 65 6d 6f 72 79 20 5b 56 46 53 5d 20  in-memory [VFS] 
3990: 63 61 6e 20 62 65 20 72 69 67 67 65 64 0a 74 6f  can be rigged.to
39a0: 20 6d 61 6b 65 20 61 20 73 6e 61 70 73 68 6f 74   make a snapshot
39b0: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 66   of the entire f
39c0: 69 6c 65 73 79 73 74 65 6d 20 61 66 74 65 72 20  ilesystem after 
39d0: 61 20 73 65 74 20 6e 75 6d 62 65 72 20 6f 66 20  a set number of 
39e0: 49 2f 4f 0a 6f 70 65 72 61 74 69 6f 6e 73 2e 20  I/O.operations. 
39f0: 20 43 72 61 73 68 20 74 65 73 74 73 20 72 75 6e   Crash tests run
3a00: 20 69 6e 20 61 20 6c 6f 6f 70 2e 20 20 4f 6e 20   in a loop.  On 
3a10: 65 61 63 68 20 69 74 65 72 61 74 69 6f 6e 20 6f  each iteration o
3a20: 66 20 74 68 65 20 6c 6f 6f 70 2c 0a 74 68 65 20  f the loop,.the 
3a30: 70 6f 69 6e 74 20 61 74 20 77 68 69 63 68 20 61  point at which a
3a40: 20 73 6e 61 70 73 68 6f 74 20 69 73 20 6d 61 64   snapshot is mad
3a50: 65 20 69 73 20 61 64 76 61 6e 63 65 64 20 75 6e  e is advanced un
3a60: 74 69 6c 20 74 68 65 20 53 51 4c 69 74 65 0a 6f  til the SQLite.o
3a70: 70 65 72 61 74 69 6f 6e 73 20 62 65 69 6e 67 20  perations being 
3a80: 74 65 73 74 65 64 20 72 75 6e 20 74 6f 20 63 6f  tested run to co
3a90: 6d 70 6c 65 74 69 6f 6e 20 77 69 74 68 6f 75 74  mpletion without
3aa0: 20 65 76 65 72 20 68 69 74 74 69 6e 67 20 61 0a   ever hitting a.
3ab0: 73 6e 61 70 73 68 6f 74 2e 20 20 57 69 74 68 69  snapshot.  Withi
3ac0: 6e 20 74 68 65 20 6c 6f 6f 70 2c 20 61 66 74 65  n the loop, afte
3ad0: 72 20 74 68 65 20 53 51 4c 69 74 65 20 6f 70 65  r the SQLite ope
3ae0: 72 61 74 69 6f 6e 20 75 6e 64 65 72 20 74 65 73  ration under tes
3af0: 74 20 68 61 73 0a 63 6f 6d 70 6c 65 74 65 64 2c  t has.completed,
3b00: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 20   the filesystem 
3b10: 69 73 20 72 65 76 65 72 74 65 64 20 74 6f 20 74  is reverted to t
3b20: 68 65 20 73 6e 61 70 73 68 6f 74 20 61 6e 64 20  he snapshot and 
3b30: 72 61 6e 64 6f 6d 20 66 69 6c 65 0a 64 61 6d 61  random file.dama
3b40: 67 65 20 69 73 20 69 6e 74 72 6f 64 75 63 65 64  ge is introduced
3b50: 20 74 68 61 74 20 69 73 20 63 68 61 72 61 63 74   that is charact
3b60: 65 72 69 73 74 69 63 20 6f 66 20 74 68 65 20 6b  eristic of the k
3b70: 69 6e 64 73 20 6f 66 20 64 61 6d 61 67 65 0a 6f  inds of damage.o
3b80: 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 73 65  ne expects to se
3b90: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 70 6f  e following a po
3ba0: 77 65 72 20 6c 6f 73 73 2e 20 20 54 68 65 6e 20  wer loss.  Then 
3bb0: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
3bc0: 6f 70 65 6e 65 64 0a 61 6e 64 20 63 68 65 63 6b  opened.and check
3bd0: 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 65 6e  s are made to en
3be0: 73 75 72 65 20 74 68 61 74 20 69 74 20 69 73 20  sure that it is 
3bf0: 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 61 6e 64 20  well-formed and 
3c00: 74 68 61 74 20 74 68 65 0a 74 72 61 6e 73 61 63  that the.transac
3c10: 74 69 6f 6e 20 65 69 74 68 65 72 20 72 61 6e 20  tion either ran 
3c20: 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72  to completion or
3c30: 20 77 61 73 20 63 6f 6d 70 6c 65 74 65 6c 79 20   was completely 
3c40: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 54 68 65  rolled back..The
3c50: 20 69 6e 74 65 72 69 6f 72 20 6f 66 20 74 68 65   interior of the
3c60: 20 6c 6f 6f 70 20 69 73 20 72 65 70 65 61 74 65   loop is repeate
3c70: 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
3c80: 20 66 6f 72 20 65 61 63 68 0a 73 6e 61 70 73 68   for each.snapsh
3c90: 6f 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ot with differen
3ca0: 74 20 72 61 6e 64 6f 6d 20 64 61 6d 61 67 65 20  t random damage 
3cb0: 65 61 63 68 20 74 69 6d 65 2e 3c 2f 70 3e 0a 0a  each time.</p>..
3cc0: 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
3cd0: 20 6d 75 6c 74 69 66 61 69 6c 3c 2f 74 63 6c 3e   multifail</tcl>
3ce0: 0a 3c 68 32 3e 43 6f 6d 70 6f 75 6e 64 20 66 61  .<h2>Compound fa
3cf0: 69 6c 75 72 65 20 74 65 73 74 73 3c 2f 68 32 3e  ilure tests</h2>
3d00: 0a 0a 3c 70 3e 54 68 65 20 74 65 73 74 20 73 75  ..<p>The test su
3d10: 69 74 65 73 20 66 6f 72 20 53 51 4c 69 74 65 20  ites for SQLite 
3d20: 61 6c 73 6f 20 65 78 70 6c 6f 72 65 20 74 68 65  also explore the
3d30: 20 72 65 73 75 6c 74 20 6f 66 20 73 74 61 63 6b   result of stack
3d40: 69 6e 67 0a 6d 75 6c 74 69 70 6c 65 20 66 61 69  ing.multiple fai
3d50: 6c 75 72 65 73 2e 20 20 46 6f 72 20 65 78 61 6d  lures.  For exam
3d60: 70 6c 65 2c 20 74 65 73 74 73 20 61 72 65 20 72  ple, tests are r
3d70: 75 6e 20 74 6f 20 65 6e 73 75 72 65 20 63 6f 72  un to ensure cor
3d80: 72 65 63 74 20 62 65 68 61 76 69 6f 72 0a 77 68  rect behavior.wh
3d90: 65 6e 20 61 6e 20 49 2f 4f 20 65 72 72 6f 72 20  en an I/O error 
3da0: 6f 72 20 4f 4f 4d 20 66 61 75 6c 74 20 6f 63 63  or OOM fault occ
3db0: 75 72 73 20 77 68 69 6c 65 20 74 72 79 69 6e 67  urs while trying
3dc0: 20 74 6f 20 72 65 63 6f 76 65 72 20 66 72 6f 6d   to recover from
3dd0: 20 61 0a 70 72 69 6f 72 20 63 72 61 73 68 2e 0a   a.prior crash..
3de0: 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
3df0: 74 20 66 75 7a 7a 74 65 73 74 69 6e 67 20 7b 66  t fuzztesting {f
3e00: 75 7a 7a 20 74 65 73 74 69 6e 67 7d 20 7b 53 51  uzz testing} {SQ
3e10: 4c 20 66 75 7a 7a 69 6e 67 7d 3c 2f 74 63 6c 3e  L fuzzing}</tcl>
3e20: 0a 3c 68 31 3e 46 75 7a 7a 20 54 65 73 74 69 6e  .<h1>Fuzz Testin
3e30: 67 3c 2f 68 31 3e 0a 0a 3c 70 3e 5b 68 74 74 70  g</h1>..<p>[http
3e40: 3a 2f 2f 65 6e 2e 77 69 6b 69 70 65 64 69 61 2e  ://en.wikipedia.
3e50: 6f 72 67 2f 77 69 6b 69 2f 46 75 7a 7a 5f 74 65  org/wiki/Fuzz_te
3e60: 73 74 69 6e 67 20 7c 20 46 75 7a 7a 20 74 65 73  sting | Fuzz tes
3e70: 74 69 6e 67 5d 0a 73 65 65 6b 73 20 74 6f 20 65  ting].seeks to e
3e80: 73 74 61 62 6c 69 73 68 20 74 68 61 74 20 53 51  stablish that SQ
3e90: 4c 69 74 65 20 72 65 73 70 6f 6e 64 73 20 63 6f  Lite responds co
3ea0: 72 72 65 63 74 6c 79 20 74 6f 20 69 6e 76 61 6c  rrectly to inval
3eb0: 69 64 2c 20 6f 75 74 2d 6f 66 2d 72 61 6e 67 65  id, out-of-range
3ec0: 2c 0a 6f 72 20 6d 61 6c 66 6f 72 6d 65 64 20 69  ,.or malformed i
3ed0: 6e 70 75 74 73 2e 3c 2f 70 3e 0a 0a 3c 68 32 3e  nputs.</p>..<h2>
3ee0: 53 51 4c 20 46 75 7a 7a 3c 2f 68 32 3e 0a 0a 3c  SQL Fuzz</h2>..<
3ef0: 70 3e 53 51 4c 20 66 75 7a 7a 20 74 65 73 74 69  p>SQL fuzz testi
3f00: 6e 67 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 63  ng consists of c
3f10: 72 65 61 74 69 6e 67 20 73 79 6e 74 61 63 74 69  reating syntacti
3f20: 63 61 6c 6c 79 20 63 6f 72 72 65 63 74 20 79 65  cally correct ye
3f30: 74 0a 77 69 6c 64 6c 79 20 6e 6f 6e 73 65 6e 73  t.wildly nonsens
3f40: 69 63 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65  ical SQL stateme
3f50: 6e 74 73 20 61 6e 64 20 66 65 65 64 69 6e 67 20  nts and feeding 
3f60: 74 68 65 6d 20 74 6f 20 53 51 4c 69 74 65 20 74  them to SQLite t
3f70: 6f 20 73 65 65 0a 77 68 61 74 20 69 74 20 77 69  o see.what it wi
3f80: 6c 6c 20 64 6f 20 77 69 74 68 20 74 68 65 6d 2e  ll do with them.
3f90: 20 20 55 73 75 61 6c 6c 79 20 73 6f 6d 65 20 6b    Usually some k
3fa0: 69 6e 64 20 6f 66 20 65 72 72 6f 72 20 69 73 20  ind of error is 
3fb0: 72 65 74 75 72 6e 65 64 0a 28 73 75 63 68 20 61  returned.(such a
3fc0: 73 20 22 6e 6f 20 73 75 63 68 20 74 61 62 6c 65  s "no such table
3fd0: 22 29 2e 20 20 53 6f 6d 65 74 69 6d 65 73 2c 20  ").  Sometimes, 
3fe0: 70 75 72 65 6c 79 20 62 79 20 63 68 61 6e 63 65  purely by chance
3ff0: 2c 20 74 68 65 20 53 51 4c 0a 73 74 61 74 65 6d  , the SQL.statem
4000: 65 6e 74 20 61 6c 73 6f 20 68 61 70 70 65 6e 73  ent also happens
4010: 20 74 6f 20 62 65 20 73 65 6d 61 6e 74 69 63 61   to be semantica
4020: 6c 6c 79 20 63 6f 72 72 65 63 74 2e 20 20 49 6e  lly correct.  In
4030: 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
4040: 72 65 73 75 6c 74 69 6e 67 20 70 72 65 70 61 72  resulting prepar
4050: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
4060: 72 75 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  run to make sure
4070: 20 69 74 20 67 69 76 65 73 20 61 20 72 65 61 73   it gives a reas
4080: 6f 6e 61 62 6c 65 0a 72 65 73 75 6c 74 2e 3c 2f  onable.result.</
4090: 70 3e 0a 0a 3c 70 3e 54 68 65 20 53 51 4c 20 66  p>..<p>The SQL f
40a0: 75 7a 7a 20 67 65 6e 65 72 61 74 6f 72 20 74 65  uzz generator te
40b0: 73 74 73 20 61 72 65 20 70 61 72 74 20 6f 66 20  sts are part of 
40c0: 74 68 65 20 54 43 4c 20 74 65 73 74 20 73 75 69  the TCL test sui
40d0: 74 65 2e 0a 44 75 72 69 6e 67 20 61 20 66 75 6c  te..During a ful
40e0: 6c 20 74 65 73 74 20 72 75 6e 2c 20 61 62 6f 75  l test run, abou
40f0: 74 20 3c 74 63 6c 3e 4b 42 20 7b 24 73 74 61 74  t <tcl>KB {$stat
4100: 28 6e 53 71 6c 46 75 7a 7a 29 7d 3c 2f 74 63 6c  (nSqlFuzz)}</tcl
4110: 3e 20 0a 74 68 6f 75 73 61 6e 64 20 66 75 7a 7a  > .thousand fuzz
4120: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
4130: 61 72 65 0a 67 65 6e 65 72 61 74 65 64 20 61 6e  are.generated an
4140: 64 20 74 65 73 74 65 64 2e 3c 2f 70 3e 0a 0a 3c  d tested.</p>..<
4150: 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
4160: 61 66 6c 66 75 7a 7a 20 7b 41 6d 65 72 69 63 61  aflfuzz {America
4170: 6e 20 46 75 7a 7a 79 20 4c 6f 70 20 66 75 7a 7a  n Fuzzy Lop fuzz
4180: 65 72 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 53 51  er}</tcl>.<h3>SQ
4190: 4c 20 46 75 7a 7a 20 55 73 69 6e 67 20 54 68 65  L Fuzz Using The
41a0: 20 41 6d 65 72 69 63 61 6e 20 46 75 7a 7a 79 20   American Fuzzy 
41b0: 4c 6f 70 20 46 75 7a 7a 65 72 3c 2f 68 33 3e 0a  Lop Fuzzer</h3>.
41c0: 0a 3c 70 3e 54 68 65 20 3c 61 20 68 72 65 66 3d  .<p>The <a href=
41d0: 22 68 74 74 70 3a 2f 2f 6c 63 61 6d 74 75 66 2e  "http://lcamtuf.
41e0: 63 6f 72 65 64 75 6d 70 2e 63 78 2f 61 66 6c 2f  coredump.cx/afl/
41f0: 22 3e 41 6d 65 72 69 63 61 6e 20 46 75 7a 7a 79  ">American Fuzzy
4200: 20 4c 6f 70 3c 2f 61 3e 0a 6f 72 20 22 41 46 4c   Lop</a>.or "AFL
4210: 22 20 66 75 7a 7a 65 72 20 69 73 20 61 20 72 65  " fuzzer is a re
4220: 63 65 6e 74 20 28 63 69 72 63 61 20 32 30 31 34  cent (circa 2014
4230: 29 20 69 6e 6e 6f 76 61 74 69 6f 6e 20 66 72 6f  ) innovation fro
4240: 6d 20 4d 69 63 68 61 6c 20 5a 61 6c 65 77 73 6b  m Michal Zalewsk
4250: 69 2e 0a 55 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f  i..Unlike most o
4260: 74 68 65 72 20 66 75 7a 7a 65 72 73 20 74 68 61  ther fuzzers tha
4270: 74 20 62 6c 69 6e 64 6c 79 20 67 65 6e 65 72 61  t blindly genera
4280: 74 65 20 72 61 6e 64 6f 6d 20 69 6e 70 75 74 73  te random inputs
4290: 2c 20 74 68 65 20 41 46 4c 0a 66 75 7a 7a 65 72  , the AFL.fuzzer
42a0: 20 69 6e 73 74 72 75 6d 65 6e 74 73 20 74 68 65   instruments the
42b0: 20 70 72 6f 67 72 61 6d 20 62 65 69 6e 67 20 74   program being t
42c0: 65 73 74 65 64 20 28 62 79 20 6d 6f 64 69 66 79  ested (by modify
42d0: 69 6e 67 20 74 68 65 20 61 73 73 65 6d 62 6c 79  ing the assembly
42e0: 2d 6c 61 6e 67 75 61 67 65 0a 6f 75 74 70 75 74  -language.output
42f0: 20 66 72 6f 6d 20 74 68 65 20 43 20 63 6f 6d 70   from the C comp
4300: 69 6c 65 72 29 20 61 6e 64 20 75 73 65 73 20 74  iler) and uses t
4310: 68 61 74 20 69 6e 73 74 72 75 6d 65 6e 74 61 74  hat instrumentat
4320: 69 6f 6e 20 74 6f 20 64 65 74 65 63 74 20 77 68  ion to detect wh
4330: 65 6e 0a 61 6e 20 69 6e 70 75 74 20 63 61 75 73  en.an input caus
4340: 65 73 20 74 68 65 20 70 72 6f 67 72 61 6d 20 74  es the program t
4350: 6f 20 64 6f 20 73 6f 6d 65 74 68 69 6e 67 20 64  o do something d
4360: 69 66 66 65 72 65 6e 74 20 2d 20 74 6f 20 66 6f  ifferent - to fo
4370: 6c 6c 6f 77 0a 61 20 6e 65 77 20 63 6f 6e 74 72  llow.a new contr
4380: 6f 6c 20 70 61 74 68 20 6f 72 20 6c 6f 6f 70 20  ol path or loop 
4390: 61 20 64 69 66 66 65 72 65 6e 74 20 6e 75 6d 62  a different numb
43a0: 65 72 20 6f 66 20 74 69 6d 65 73 2e 20 20 49 6e  er of times.  In
43b0: 70 75 74 73 20 74 68 61 74 20 70 72 6f 76 6f 6b  puts that provok
43c0: 65 0a 6e 65 77 20 62 65 68 61 76 69 6f 72 20 61  e.new behavior a
43d0: 72 65 20 72 65 74 61 69 6e 65 64 20 61 6e 64 20  re retained and 
43e0: 66 75 72 74 68 65 72 20 6d 75 74 61 74 65 64 2e  further mutated.
43f0: 20 20 49 6e 20 74 68 69 73 20 77 61 79 2c 20 41    In this way, A
4400: 46 4c 20 69 73 20 61 62 6c 65 0a 74 6f 20 22 64  FL is able.to "d
4410: 69 73 63 6f 76 65 72 22 20 6e 65 77 20 62 65 68  iscover" new beh
4420: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 20 70 72  aviors of the pr
4430: 6f 67 72 61 6d 20 75 6e 64 65 72 20 74 65 73 74  ogram under test
4440: 2c 20 69 6e 63 6c 75 64 69 6e 67 20 62 65 68 61  , including beha
4450: 76 69 6f 72 73 0a 74 68 61 74 20 77 65 72 65 20  viors.that were 
4460: 6e 65 76 65 72 20 65 6e 76 69 73 69 6f 6e 65 64  never envisioned
4470: 20 62 79 20 74 68 65 20 64 65 73 69 67 6e 65 72   by the designer
4480: 73 2e 0a 0a 3c 70 3e 41 46 4c 20 68 61 73 20 70  s...<p>AFL has p
4490: 72 6f 76 65 6e 20 72 65 6d 61 72 6b 61 62 6c 79  roven remarkably
44a0: 20 61 64 65 70 74 20 61 74 20 66 69 6e 64 69 6e   adept at findin
44b0: 67 20 61 72 63 61 6e 65 20 62 75 67 73 20 69 6e  g arcane bugs in
44c0: 20 53 51 4c 69 74 65 2e 0a 4d 6f 73 74 20 6f 66   SQLite..Most of
44d0: 20 74 68 65 20 66 69 6e 64 69 6e 67 73 20 68 61   the findings ha
44e0: 76 65 20 62 65 65 6e 20 61 73 73 65 72 74 28 29  ve been assert()
44f0: 20 73 74 61 74 65 6d 65 6e 74 73 20 77 68 65 72   statements wher
4500: 65 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 61  e the conditiona
4510: 6c 0a 77 61 73 20 66 61 6c 73 65 20 75 6e 64 65  l.was false unde
4520: 72 20 6f 62 73 63 75 72 65 20 63 69 72 63 75 6d  r obscure circum
4530: 73 74 61 6e 63 65 73 2e 20 20 42 75 74 20 41 46  stances.  But AF
4540: 4c 20 68 61 73 20 61 6c 73 6f 20 66 6f 75 6e 64  L has also found
4550: 0a 61 20 66 61 69 72 20 6e 75 6d 62 65 72 20 6f  .a fair number o
4560: 66 20 63 72 61 73 68 20 62 75 67 73 20 69 6e 20  f crash bugs in 
4570: 53 51 4c 69 74 65 2c 20 61 6e 64 20 65 76 65 6e  SQLite, and even
4580: 20 61 20 66 65 77 20 63 61 73 65 73 20 77 68 65   a few cases whe
4590: 72 65 20 53 51 4c 69 74 65 20 0a 63 6f 6d 70 75  re SQLite .compu
45a0: 74 65 64 20 69 6e 63 6f 72 72 65 63 74 20 72 65  ted incorrect re
45b0: 73 75 6c 74 73 2e 0a 0a 3c 70 3e 42 65 63 61 75  sults...<p>Becau
45c0: 73 65 20 6f 66 20 69 74 73 20 70 61 73 74 20 73  se of its past s
45d0: 75 63 63 65 73 73 2c 20 41 46 4c 20 62 65 63 61  uccess, AFL beca
45e0: 6d 65 20 61 20 73 74 61 6e 64 61 72 64 20 70 61  me a standard pa
45f0: 72 74 20 6f 66 20 74 68 65 20 74 65 73 74 69 6e  rt of the testin
4600: 67 0a 73 74 72 61 74 65 67 79 20 66 6f 72 20 53  g.strategy for S
4610: 51 4c 69 74 65 20 62 65 67 69 6e 6e 69 6e 67 20  QLite beginning 
4620: 77 69 74 68 20 5b 76 65 72 73 69 6f 6e 20 33 2e  with [version 3.
4630: 38 2e 31 30 5d 20 28 5b 64 61 74 65 6f 66 3a 33  8.10] ([dateof:3
4640: 2e 38 2e 31 30 5d 29 2e 20 20 0a 42 6f 74 68 20  .8.10]).  .Both 
4650: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
4660: 6e 64 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  nd database file
4670: 73 20 61 72 65 20 66 75 7a 7a 65 64 2e 0a 42 69  s are fuzzed..Bi
4680: 6c 6c 69 6f 6e 73 20 61 6e 64 20 62 69 6c 6c 69  llions and billi
4690: 6f 6e 73 20 6f 66 20 6d 75 74 61 74 69 6f 6e 73  ons of mutations
46a0: 20 68 61 76 65 20 62 65 65 6e 20 74 72 69 65 64   have been tried
46b0: 2c 20 62 75 74 20 41 46 4c 27 73 20 0a 69 6e 73  , but AFL's .ins
46c0: 74 72 75 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73  trumentation has
46d0: 20 6e 61 72 72 6f 77 65 64 20 74 68 65 6d 20 64   narrowed them d
46e0: 6f 77 6e 20 74 6f 20 6c 65 73 73 20 74 68 61 6e  own to less than
46f0: 20 35 30 2c 30 30 30 20 74 65 73 74 20 63 61 73   50,000 test cas
4700: 65 73 20 74 68 61 74 0a 63 6f 76 65 72 20 61 6c  es that.cover al
4710: 6c 20 64 69 73 74 69 6e 63 74 20 62 65 68 61 76  l distinct behav
4720: 69 6f 72 73 2e 20 20 4e 65 77 6c 79 20 64 69 73  iors.  Newly dis
4730: 63 6f 76 65 72 65 64 20 74 65 73 74 20 63 61 73  covered test cas
4740: 65 73 20 61 72 65 20 70 65 72 69 6f 64 69 63 61  es are periodica
4750: 6c 6c 79 0a 63 61 70 74 75 72 65 64 20 61 6e 64  lly.captured and
4760: 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 5b 54   added to the [T
4770: 43 4c 20 74 65 73 74 20 73 75 69 74 65 5d 20 77  CL test suite] w
4780: 68 65 72 65 20 74 68 65 79 20 63 61 6e 20 62 65  here they can be
4790: 20 72 65 72 75 6e 20 75 73 69 6e 67 0a 74 68 65   rerun using.the
47a0: 20 22 6d 61 6b 65 20 66 75 7a 7a 74 65 73 74 22   "make fuzztest"
47b0: 20 6f 72 20 22 6d 61 6b 65 20 76 61 6c 67 72 69   or "make valgri
47c0: 6e 64 66 75 7a 7a 22 20 63 6f 6d 6d 61 6e 64 73  ndfuzz" commands
47d0: 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  ...<tcl>hd_fragm
47e0: 65 6e 74 20 6f 73 73 66 75 7a 7a 20 7b 4f 53 53  ent ossfuzz {OSS
47f0: 20 46 75 7a 7a 7d 3c 2f 74 63 6c 3e 0a 3c 68 33   Fuzz}</tcl>.<h3
4800: 3e 47 6f 6f 67 6c 65 20 4f 53 53 20 46 75 7a 7a  >Google OSS Fuzz
4810: 3c 2f 68 33 3e 0a 0a 3c 70 3e 42 65 67 69 6e 6e  </h3>..<p>Beginn
4820: 69 6e 67 20 69 6e 20 32 30 31 36 2c 20 61 20 74  ing in 2016, a t
4830: 65 61 6d 20 6f 66 20 65 6e 67 69 6e 65 65 72 73  eam of engineers
4840: 20 61 74 20 47 6f 6f 67 6c 65 20 73 74 61 72 74   at Google start
4850: 65 64 20 74 68 65 0a 5b 68 74 74 70 73 3a 2f 2f  ed the.[https://
4860: 67 69 74 68 75 62 2e 63 6f 6d 2f 67 6f 6f 67 6c  github.com/googl
4870: 65 2f 6f 73 73 2d 66 75 7a 7a 7c 4f 53 53 20 46  e/oss-fuzz|OSS F
4880: 75 7a 7a 5d 20 70 72 6f 6a 65 63 74 2e 20 20 0a  uzz] project.  .
4890: 4f 53 53 20 46 75 7a 7a 20 75 73 65 73 20 61 20  OSS Fuzz uses a 
48a0: 41 46 4c 2d 73 74 79 6c 65 20 67 75 69 64 65 64  AFL-style guided
48b0: 20 66 75 7a 7a 65 72 20 72 75 6e 6e 69 6e 67 20   fuzzer running 
48c0: 6f 6e 20 47 6f 6f 67 6c 65 27 73 20 69 6e 66 72  on Google's infr
48d0: 61 73 74 72 75 63 74 75 72 65 2e 0a 54 68 65 20  astructure..The 
48e0: 46 75 7a 7a 65 72 20 61 75 74 6f 6d 61 74 69 63  Fuzzer automatic
48f0: 61 6c 6c 79 20 64 6f 77 6e 6c 6f 61 64 73 20 74  ally downloads t
4900: 68 65 20 6c 61 74 65 73 74 20 63 68 65 63 6b 2d  he latest check-
4910: 69 6e 73 20 66 6f 72 20 70 61 72 74 69 63 69 70  ins for particip
4920: 61 74 69 6e 67 0a 70 72 6f 6a 65 63 74 73 2c 20  ating.projects, 
4930: 66 75 7a 7a 65 73 20 74 68 65 6d 2c 20 61 6e 64  fuzzes them, and
4940: 20 73 65 6e 64 73 20 65 6d 61 69 6c 20 74 6f 20   sends email to 
4950: 74 68 65 20 64 65 76 65 6c 6f 70 65 72 73 20 72  the developers r
4960: 65 70 6f 72 74 69 6e 67 20 61 6e 79 0a 70 72 6f  eporting any.pro
4970: 62 6c 65 6d 73 2e 20 20 57 68 65 6e 20 61 20 66  blems.  When a f
4980: 69 78 20 69 73 20 63 68 65 63 6b 65 64 20 69 6e  ix is checked in
4990: 2c 20 74 68 65 20 66 75 7a 7a 65 72 20 61 75 74  , the fuzzer aut
49a0: 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 74 65 63  omatically detec
49b0: 74 73 20 74 68 69 73 0a 61 6e 64 20 65 6d 61 69  ts this.and emai
49c0: 6c 73 20 61 20 63 6f 6e 66 69 72 6d 61 74 69 6f  ls a confirmatio
49d0: 6e 20 74 6f 20 74 68 65 20 64 65 76 65 6c 6f 70  n to the develop
49e0: 65 72 73 2e 0a 0a 3c 70 3e 53 51 4c 69 74 65 20  ers...<p>SQLite 
49f0: 69 73 20 6f 6e 65 20 6f 66 20 6d 61 6e 79 20 6f  is one of many o
4a00: 70 65 6e 2d 73 6f 75 72 63 65 20 70 72 6f 6a 65  pen-source proje
4a10: 63 74 73 20 74 68 61 74 20 4f 53 53 20 46 75 7a  cts that OSS Fuz
4a20: 7a 20 74 65 73 74 73 2e 20 54 68 65 0a 5b 68 74  z tests. The.[ht
4a30: 74 70 73 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65  tps://www.sqlite
4a40: 2e 6f 72 67 2f 73 72 63 2f 66 69 6c 65 2f 74 65  .org/src/file/te
4a50: 73 74 2f 6f 73 73 66 75 7a 7a 2e 63 7c 74 65 73  st/ossfuzz.c|tes
4a60: 74 2f 6f 73 73 66 75 7a 7a 2e 63 5d 20 73 6f 75  t/ossfuzz.c] sou
4a70: 72 63 65 20 66 69 6c 65 0a 69 6e 20 74 68 65 20  rce file.in the 
4a80: 53 51 4c 69 74 65 20 72 65 70 6f 73 69 74 6f 72  SQLite repositor
4a90: 79 20 69 73 20 53 51 4c 69 74 65 27 73 20 69 6e  y is SQLite's in
4aa0: 74 65 72 66 61 63 65 20 74 6f 20 4f 53 53 20 66  terface to OSS f
4ab0: 75 7a 7a 2e 0a 0a 3c 68 32 3e 4d 61 6c 66 6f 72  uzz...<h2>Malfor
4ac0: 6d 65 64 20 44 61 74 61 62 61 73 65 20 46 69 6c  med Database Fil
4ad0: 65 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65 72  es</h2>..<p>Ther
4ae0: 65 20 61 72 65 20 6e 75 6d 65 72 6f 75 73 20 74  e are numerous t
4af0: 65 73 74 20 63 61 73 65 73 20 74 68 61 74 20 76  est cases that v
4b00: 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
4b10: 65 20 69 73 20 61 62 6c 65 20 74 6f 0a 64 65 61  e is able to.dea
4b20: 6c 20 77 69 74 68 20 6d 61 6c 66 6f 72 6d 65 64  l with malformed
4b30: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e   database files.
4b40: 0a 54 68 65 73 65 20 74 65 73 74 73 20 66 69 72  .These tests fir
4b50: 73 74 20 62 75 69 6c 64 20 61 20 77 65 6c 6c 2d  st build a well-
4b60: 66 6f 72 6d 65 64 20 64 61 74 61 62 61 73 65 20  formed database 
4b70: 66 69 6c 65 2c 20 74 68 65 6e 20 61 64 64 0a 63  file, then add.c
4b80: 6f 72 72 75 70 74 69 6f 6e 20 62 79 20 63 68 61  orruption by cha
4b90: 6e 67 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72  nging one or mor
4ba0: 65 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  e bytes in the f
4bb0: 69 6c 65 20 62 79 20 73 6f 6d 65 20 6d 65 61 6e  ile by some mean
4bc0: 73 0a 6f 74 68 65 72 20 74 68 61 6e 20 53 51 4c  s.other than SQL
4bd0: 69 74 65 2e 20 20 54 68 65 6e 20 53 51 4c 69 74  ite.  Then SQLit
4be0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61  e is used to rea
4bf0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  d the database..
4c00: 49 6e 20 73 6f 6d 65 20 63 61 73 65 73 2c 20 74  In some cases, t
4c10: 68 65 20 62 79 74 65 73 20 63 68 61 6e 67 65 73  he bytes changes
4c20: 20 61 72 65 20 69 6e 20 74 68 65 20 6d 69 64 64   are in the midd
4c30: 6c 65 20 6f 66 20 64 61 74 61 2e 0a 54 68 69 73  le of data..This
4c40: 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 6e 74   causes the cont
4c50: 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
4c60: 61 73 65 20 74 6f 20 63 68 61 6e 67 65 20 77 68  ase to change wh
4c70: 69 6c 65 20 6b 65 65 70 69 6e 67 20 74 68 65 0a  ile keeping the.
4c80: 64 61 74 61 62 61 73 65 20 77 65 6c 6c 2d 66 6f  database well-fo
4c90: 72 6d 65 64 2e 0a 49 6e 20 6f 74 68 65 72 20 63  rmed..In other c
4ca0: 61 73 65 73 2c 20 75 6e 75 73 65 64 20 62 79 74  ases, unused byt
4cb0: 65 73 20 6f 66 20 74 68 65 20 66 69 6c 65 20 61  es of the file a
4cc0: 72 65 20 6d 6f 64 69 66 69 65 64 2c 20 77 68 69  re modified, whi
4cd0: 63 68 20 68 61 73 0a 6e 6f 20 65 66 66 65 63 74  ch has.no effect
4ce0: 20 6f 6e 20 74 68 65 20 69 6e 74 65 67 72 69 74   on the integrit
4cf0: 79 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  y of the databas
4d00: 65 2e 0a 54 68 65 20 69 6e 74 65 72 65 73 74 69  e..The interesti
4d10: 6e 67 20 63 61 73 65 73 20 61 72 65 20 77 68 65  ng cases are whe
4d20: 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 66  n bytes of the f
4d30: 69 6c 65 20 74 68 61 74 0a 64 65 66 69 6e 65 20  ile that.define 
4d40: 64 61 74 61 62 61 73 65 20 73 74 72 75 63 74 75  database structu
4d50: 72 65 20 67 65 74 20 63 68 61 6e 67 65 64 2e 20  re get changed. 
4d60: 20 54 68 65 20 6d 61 6c 66 6f 72 6d 65 64 20 64   The malformed d
4d70: 61 74 61 62 61 73 65 20 74 65 73 74 73 0a 76 65  atabase tests.ve
4d80: 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
4d90: 20 66 69 6e 64 73 20 74 68 65 20 66 69 6c 65 20   finds the file 
4da0: 66 6f 72 6d 61 74 20 65 72 72 6f 72 73 20 61 6e  format errors an
4db0: 64 20 72 65 70 6f 72 74 73 20 74 68 65 6d 0a 75  d reports them.u
4dc0: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
4dd0: 5f 43 4f 52 52 55 50 54 5d 20 72 65 74 75 72 6e  _CORRUPT] return
4de0: 20 63 6f 64 65 20 77 69 74 68 6f 75 74 20 6f 76   code without ov
4df0: 65 72 66 6c 6f 77 69 6e 67 0a 62 75 66 66 65 72  erflowing.buffer
4e00: 73 2c 20 64 65 72 65 66 65 72 65 6e 63 69 6e 67  s, dereferencing
4e10: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2c 20   NULL pointers, 
4e20: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 20 6f 74  or performing ot
4e30: 68 65 72 0a 75 6e 77 68 6f 6c 65 73 6f 6d 65 20  her.unwholesome 
4e40: 61 63 74 69 6f 6e 73 2e 3c 2f 70 3e 0a 0a 3c 68  actions.</p>..<h
4e50: 32 3e 42 6f 75 6e 64 61 72 79 20 56 61 6c 75 65  2>Boundary Value
4e60: 20 54 65 73 74 73 3c 2f 68 32 3e 0a 0a 3c 70 3e   Tests</h2>..<p>
4e70: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 63  SQLite defines c
4e80: 65 72 74 61 69 6e 20 5b 6c 69 6d 69 74 73 5d 20  ertain [limits] 
4e90: 6f 6e 20 69 74 73 20 6f 70 65 72 61 74 69 6f 6e  on its operation
4ea0: 2c 20 73 75 63 68 20 61 73 20 74 68 65 0a 6d 61  , such as the.ma
4eb0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
4ec0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
4ed0: 6c 65 2c 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  le, the maximum 
4ee0: 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 0a 53 51  length of an .SQ
4ef0: 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 20  L statement, or 
4f00: 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75  the maximum valu
4f10: 65 20 6f 66 20 61 6e 20 69 6e 74 65 67 65 72 2e  e of an integer.
4f20: 20 20 54 68 65 20 54 43 4c 20 61 6e 64 20 54 48    The TCL and TH
4f30: 33 20 74 65 73 74 0a 73 75 69 74 65 73 20 62 6f  3 test.suites bo
4f40: 74 68 20 63 6f 6e 74 61 69 6e 73 20 6e 75 6d 65  th contains nume
4f50: 72 6f 75 73 20 74 65 73 74 73 20 74 68 61 74 20  rous tests that 
4f60: 70 75 73 68 20 53 51 4c 69 74 65 20 72 69 67 68  push SQLite righ
4f70: 74 20 74 6f 20 74 68 65 20 65 64 67 65 0a 6f 66  t to the edge.of
4f80: 20 69 74 73 20 64 65 66 69 6e 65 64 20 6c 69 6d   its defined lim
4f90: 69 74 73 20 61 6e 64 20 76 65 72 69 66 79 20 74  its and verify t
4fa0: 68 61 74 20 69 74 20 70 65 72 66 6f 72 6d 73 20  hat it performs 
4fb0: 63 6f 72 72 65 63 74 6c 79 20 66 6f 72 0a 61 6c  correctly for.al
4fc0: 6c 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73  l allowed values
4fd0: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 74 65  .  Additional te
4fe0: 73 74 73 20 67 6f 20 62 65 79 6f 6e 64 20 74 68  sts go beyond th
4ff0: 65 20 64 65 66 69 6e 65 64 20 6c 69 6d 69 74 73  e defined limits
5000: 0a 61 6e 64 20 76 65 72 69 66 79 20 74 68 61 74  .and verify that
5010: 20 53 51 4c 69 74 65 20 63 6f 72 72 65 63 74 6c   SQLite correctl
5020: 79 20 72 65 74 75 72 6e 73 20 65 72 72 6f 72 73  y returns errors
5030: 2e 20 20 54 68 65 20 73 6f 75 72 63 65 20 63 6f  .  The source co
5040: 64 65 0a 63 6f 6e 74 61 69 6e 73 20 5b 74 65 73  de.contains [tes
5050: 74 63 61 73 65 20 6d 61 63 72 6f 73 5d 20 74 6f  tcase macros] to
5060: 20 76 65 72 69 66 79 20 74 68 61 74 20 62 6f 74   verify that bot
5070: 68 20 73 69 64 65 73 20 6f 66 20 65 61 63 68 20  h sides of each 
5080: 62 6f 75 6e 64 61 72 79 0a 68 61 76 65 20 62 65  boundary.have be
5090: 65 6e 20 74 65 73 74 65 64 2e 3c 2f 70 3e 0a 0a  en tested.</p>..
50a0: 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
50b0: 20 72 65 67 72 65 73 73 69 6f 6e 74 65 73 74 69   regressiontesti
50c0: 6e 67 3c 2f 74 63 6c 3e 0a 3c 68 31 3e 52 65 67  ng</tcl>.<h1>Reg
50d0: 72 65 73 73 69 6f 6e 20 54 65 73 74 69 6e 67 3c  ression Testing<
50e0: 2f 68 31 3e 0a 0a 3c 70 3e 57 68 65 6e 65 76 65  /h1>..<p>Wheneve
50f0: 72 20 61 20 62 75 67 20 69 73 20 72 65 70 6f 72  r a bug is repor
5100: 74 65 64 20 61 67 61 69 6e 73 74 20 53 51 4c 69  ted against SQLi
5110: 74 65 2c 20 74 68 61 74 20 62 75 67 20 69 73 20  te, that bug is 
5120: 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 0a 66  not considered.f
5130: 69 78 65 64 20 75 6e 74 69 6c 20 6e 65 77 20 74  ixed until new t
5140: 65 73 74 20 63 61 73 65 73 20 74 68 61 74 20 77  est cases that w
5150: 6f 75 6c 64 20 65 78 68 69 62 69 74 20 74 68 65  ould exhibit the
5160: 20 62 75 67 20 68 61 76 65 20 62 65 65 6e 20 61   bug have been a
5170: 64 64 65 64 20 0a 74 6f 20 65 69 74 68 65 72 20  dded .to either 
5180: 74 68 65 20 54 43 4c 20 6f 72 20 54 48 33 20 74  the TCL or TH3 t
5190: 65 73 74 20 73 75 69 74 65 73 2e 0a 4f 76 65 72  est suites..Over
51a0: 20 74 68 65 20 79 65 61 72 73 2c 0a 74 68 69 73   the years,.this
51b0: 20 68 61 73 20 72 65 73 75 6c 74 65 64 20 69 6e   has resulted in
51c0: 20 74 68 6f 75 73 61 6e 64 73 20 61 6e 64 20 74   thousands and t
51d0: 68 6f 75 73 61 6e 64 73 20 6f 66 20 6e 65 77 20  housands of new 
51e0: 74 65 73 74 73 2e 0a 54 68 65 73 65 20 72 65 67  tests..These reg
51f0: 72 65 73 73 69 6f 6e 20 74 65 73 74 73 20 65 6e  ression tests en
5200: 73 75 72 65 20 74 68 61 74 20 62 75 67 73 20 74  sure that bugs t
5210: 68 61 74 20 68 61 76 65 0a 62 65 65 6e 20 66 69  hat have.been fi
5220: 78 65 64 20 69 6e 20 74 68 65 20 70 61 73 74 20  xed in the past 
5230: 61 72 65 20 6e 6f 74 20 72 65 69 6e 74 72 6f 64  are not reintrod
5240: 75 63 65 64 20 69 6e 74 6f 20 66 75 74 75 72 65  uced into future
5250: 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a 53 51 4c   versions of.SQL
5260: 69 74 65 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68  ite.</p>..<tcl>h
5270: 64 5f 66 72 61 67 6d 65 6e 74 20 6c 65 61 6b 63  d_fragment leakc
5280: 68 65 63 6b 3c 2f 74 63 6c 3e 0a 3c 68 31 3e 41  heck</tcl>.<h1>A
5290: 75 74 6f 6d 61 74 69 63 20 52 65 73 6f 75 72 63  utomatic Resourc
52a0: 65 20 4c 65 61 6b 20 44 65 74 65 63 74 69 6f 6e  e Leak Detection
52b0: 3c 2f 68 31 3e 0a 0a 3c 70 3e 52 65 73 6f 75 72  </h1>..<p>Resour
52c0: 63 65 20 6c 65 61 6b 20 6f 63 63 75 72 73 20 77  ce leak occurs w
52d0: 68 65 6e 20 73 79 73 74 65 6d 20 72 65 73 6f 75  hen system resou
52e0: 72 63 65 73 0a 61 72 65 20 61 6c 6c 6f 63 61 74  rces.are allocat
52f0: 65 64 20 61 6e 64 20 6e 65 76 65 72 20 66 72 65  ed and never fre
5300: 65 64 2e 20 20 54 68 65 20 6d 6f 73 74 20 74 72  ed.  The most tr
5310: 6f 75 62 6c 65 73 6f 6d 65 20 72 65 73 6f 75 72  oublesome resour
5320: 63 65 20 6c 65 61 6b 73 0a 69 6e 20 6d 61 6e 79  ce leaks.in many
5330: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 72   applications ar
5340: 65 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 20 2d  e memory leaks -
5350: 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20   when memory is 
5360: 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 0a  allocated using.
5370: 6d 61 6c 6c 6f 63 28 29 20 62 75 74 20 6e 65 76  malloc() but nev
5380: 65 72 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  er released usin
5390: 67 20 66 72 65 65 28 29 2e 20 20 42 75 74 20 6f  g free().  But o
53a0: 74 68 65 72 20 6b 69 6e 64 73 20 6f 66 20 72 65  ther kinds of re
53b0: 73 6f 75 72 63 65 73 0a 63 61 6e 20 61 6c 73 6f  sources.can also
53c0: 20 62 65 20 6c 65 61 6b 65 64 3a 20 20 66 69 6c   be leaked:  fil
53d0: 65 20 64 65 73 63 72 69 70 74 6f 72 73 2c 20 74  e descriptors, t
53e0: 68 72 65 61 64 73 2c 20 6d 75 74 65 78 65 73 2c  hreads, mutexes,
53f0: 20 65 74 63 2e 3c 2f 70 3e 0a 0a 3c 70 3e 42 6f   etc.</p>..<p>Bo
5400: 74 68 20 74 68 65 20 54 43 4c 20 61 6e 64 20 54  th the TCL and T
5410: 48 33 20 74 65 73 74 20 68 61 72 6e 65 73 73 65  H3 test harnesse
5420: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
5430: 74 72 61 63 6b 20 73 79 73 74 65 6d 0a 72 65 73  track system.res
5440: 6f 75 72 63 65 73 20 61 6e 64 20 72 65 70 6f 72  ources and repor
5450: 74 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  t resource leaks
5460: 20 6f 6e 20 3c 75 3e 65 76 65 72 79 3c 2f 75 3e   on <u>every</u>
5470: 20 74 65 73 74 20 72 75 6e 2e 0a 4e 6f 20 73 70   test run..No sp
5480: 65 63 69 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  ecial configurat
5490: 69 6f 6e 20 6f 72 20 73 65 74 75 70 20 69 73 20  ion or setup is 
54a0: 72 65 71 75 69 72 65 64 2e 20 20 20 54 68 65 20  required.   The 
54b0: 74 65 73 74 20 68 61 72 6e 65 73 73 65 73 0a 61  test harnesses.a
54c0: 72 65 20 65 73 70 65 63 69 61 6c 6c 79 20 76 69  re especially vi
54d0: 67 69 6c 61 6e 74 20 77 69 74 68 20 72 65 67 61  gilant with rega
54e0: 72 64 20 74 6f 20 6d 65 6d 6f 72 79 20 6c 65 61  rd to memory lea
54f0: 6b 73 2e 20 20 49 66 20 61 20 63 68 61 6e 67 65  ks.  If a change
5500: 0a 63 61 75 73 65 73 20 61 20 6d 65 6d 6f 72 79  .causes a memory
5510: 20 6c 65 61 6b 2c 20 74 68 65 20 74 65 73 74 20   leak, the test 
5520: 68 61 72 6e 65 73 73 65 73 20 77 69 6c 6c 20 72  harnesses will r
5530: 65 63 6f 67 6e 69 7a 65 20 74 68 69 73 0a 71 75  ecognize this.qu
5540: 69 63 6b 6c 79 2e 20 20 53 51 4c 69 74 65 20 69  ickly.  SQLite i
5550: 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 6e 65  s designed to ne
5560: 76 65 72 20 6c 65 61 6b 20 6d 65 6d 6f 72 79 2c  ver leak memory,
5570: 20 65 76 65 6e 20 61 66 74 65 72 0a 61 6e 20 65   even after.an e
5580: 78 63 65 70 74 69 6f 6e 20 73 75 63 68 20 61 73  xception such as
5590: 20 61 6e 20 4f 4f 4d 20 65 72 72 6f 72 20 6f 72   an OOM error or
55a0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 2e   disk I/O error.
55b0: 20 20 54 68 65 20 74 65 73 74 0a 68 61 72 6e 65    The test.harne
55c0: 73 73 65 73 20 61 72 65 20 7a 65 61 6c 6f 75 73  sses are zealous
55d0: 20 74 6f 20 65 6e 66 6f 72 63 65 20 74 68 69 73   to enforce this
55e0: 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66  .</p>..<tcl>hd_f
55f0: 72 61 67 6d 65 6e 74 20 63 6f 76 65 72 61 67 65  ragment coverage
5600: 20 7b 74 65 73 74 20 63 6f 76 65 72 61 67 65 7d   {test coverage}
5610: 3c 2f 74 63 6c 3e 0a 3c 68 31 3e 54 65 73 74 20  </tcl>.<h1>Test 
5620: 43 6f 76 65 72 61 67 65 3c 2f 68 31 3e 0a 0a 3c  Coverage</h1>..<
5630: 70 3e 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  p>The SQLite cor
5640: 65 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65  e, including the
5650: 20 75 6e 69 78 20 5b 56 46 53 5d 2c 0a 68 61 73   unix [VFS],.has
5660: 20 31 30 30 25 20 62 72 61 6e 63 68 20 74 65 73   100% branch tes
5670: 74 20 63 6f 76 65 72 61 67 65 20 75 6e 64 65 72  t coverage under
5680: 20 5b 54 48 33 5d 20 69 6e 0a 69 74 73 20 64 65   [TH3] in.its de
5690: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
56a0: 69 6f 6e 20 61 73 20 6d 65 61 73 75 72 65 64 20  ion as measured 
56b0: 62 79 0a 5b 68 74 74 70 3a 2f 2f 67 63 63 2e 67  by.[http://gcc.g
56c0: 6e 75 2e 6f 72 67 2f 6f 6e 6c 69 6e 65 64 6f 63  nu.org/onlinedoc
56d0: 73 2f 67 63 63 2f 47 63 6f 76 2e 68 74 6d 6c 20  s/gcc/Gcov.html 
56e0: 7c 20 67 63 6f 76 5d 2e 0a 45 78 74 65 6e 73 69  | gcov]..Extensi
56f0: 6f 6e 73 20 73 75 63 68 20 61 73 20 46 54 53 33  ons such as FTS3
5700: 20 61 6e 64 20 52 54 72 65 65 20 61 72 65 20 65   and RTree are e
5710: 78 63 6c 75 64 65 64 20 66 72 6f 6d 20 74 68 69  xcluded from thi
5720: 73 0a 61 6e 61 6c 79 73 69 73 2e 3c 2f 70 3e 0a  s.analysis.</p>.
5730: 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
5740: 74 20 73 74 6d 74 76 62 72 3c 2f 74 63 6c 3e 0a  t stmtvbr</tcl>.
5750: 3c 68 32 3e 53 74 61 74 65 6d 65 6e 74 20 76 65  <h2>Statement ve
5760: 72 73 75 73 20 62 72 61 6e 63 68 20 63 6f 76 65  rsus branch cove
5770: 72 61 67 65 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68  rage</h2>..<p>Th
5780: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 77 61 79  ere are many way
5790: 73 20 74 6f 20 6d 65 61 73 75 72 65 20 74 65 73  s to measure tes
57a0: 74 20 63 6f 76 65 72 61 67 65 2e 20 20 54 68 65  t coverage.  The
57b0: 20 6d 6f 73 74 20 70 6f 70 75 6c 61 72 0a 6d 65   most popular.me
57c0: 74 72 69 63 20 69 73 20 22 73 74 61 74 65 6d 65  tric is "stateme
57d0: 6e 74 20 63 6f 76 65 72 61 67 65 22 2e 20 20 57  nt coverage".  W
57e0: 68 65 6e 20 79 6f 75 20 68 65 61 72 20 73 6f 6d  hen you hear som
57f0: 65 6f 6e 65 20 73 61 79 20 74 68 61 74 20 74 68  eone say that th
5800: 65 69 72 0a 70 72 6f 67 72 61 6d 20 61 73 20 22  eir.program as "
5810: 58 58 25 20 74 65 73 74 20 63 6f 76 65 72 61 67  XX% test coverag
5820: 65 22 20 77 69 74 68 6f 75 74 20 66 75 72 74 68  e" without furth
5830: 65 72 20 65 78 70 6c 61 6e 61 74 69 6f 6e 2c 20  er explanation, 
5840: 74 68 65 79 20 75 73 75 61 6c 6c 79 0a 6d 65 61  they usually.mea
5850: 6e 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 76 65  n statement cove
5860: 72 61 67 65 2e 20 20 53 74 61 74 65 6d 65 6e 74  rage.  Statement
5870: 20 63 6f 76 65 72 61 67 65 20 6d 65 61 73 75 72   coverage measur
5880: 65 73 20 77 68 61 74 20 70 65 72 63 65 6e 74 61  es what percenta
5890: 67 65 0a 6f 66 20 6c 69 6e 65 73 20 6f 66 20 63  ge.of lines of c
58a0: 6f 64 65 20 61 72 65 20 65 78 65 63 75 74 65 64  ode are executed
58b0: 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 62   at least once b
58c0: 79 20 74 68 65 20 74 65 73 74 20 73 75 69 74 65  y the test suite
58d0: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 42 72 61 6e 63 68  .</p>..<p>Branch
58e0: 20 63 6f 76 65 72 61 67 65 20 69 73 20 6d 6f 72   coverage is mor
58f0: 65 20 72 69 67 6f 72 6f 75 73 20 74 68 61 6e 20  e rigorous than 
5900: 73 74 61 74 65 6d 65 6e 74 20 63 6f 76 65 72 61  statement covera
5910: 67 65 2e 20 20 42 72 61 6e 63 68 0a 63 6f 76 65  ge.  Branch.cove
5920: 72 61 67 65 20 6d 65 61 73 75 72 65 73 20 74 68  rage measures th
5930: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 61 63 68  e number of mach
5940: 69 6e 65 2d 63 6f 64 65 20 62 72 61 6e 63 68 20  ine-code branch 
5950: 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 74 68 61  instructions tha
5960: 74 0a 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t.are evaluated 
5970: 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 6f 6e  at least once on
5980: 20 62 6f 74 68 20 64 69 72 65 63 74 69 6f 6e 73   both directions
5990: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 6f 20 69 6c 6c  .</p>..<p>To ill
59a0: 75 73 74 72 61 74 65 20 74 68 65 20 64 69 66 66  ustrate the diff
59b0: 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 73  erence between s
59c0: 74 61 74 65 6d 65 6e 74 20 63 6f 76 65 72 61 67  tatement coverag
59d0: 65 20 61 6e 64 0a 62 72 61 6e 63 68 20 63 6f 76  e and.branch cov
59e0: 65 72 61 67 65 2c 20 63 6f 6e 73 69 64 65 72 20  erage, consider 
59f0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 68 79  the following hy
5a00: 70 6f 74 68 65 74 69 63 61 6c 0a 6c 69 6e 65 20  pothetical.line 
5a10: 6f 66 20 43 20 63 6f 64 65 3a 3c 2f 70 3e 0a 0a  of C code:</p>..
5a20: 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 69 66 28 20  <codeblock>.if( 
5a30: 61 3e 62 20 26 26 20 63 21 3d 32 35 20 29 7b 20  a>b && c!=25 ){ 
5a40: 64 2b 2b 3b 20 7d 0a 3c 2f 63 6f 64 65 62 6c 6f  d++; }.</codeblo
5a50: 63 6b 3e 0a 0a 3c 70 3e 53 75 63 68 20 61 20 6c  ck>..<p>Such a l
5a60: 69 6e 65 20 6f 66 20 43 20 63 6f 64 65 20 6d 69  ine of C code mi
5a70: 67 68 74 20 67 65 6e 65 72 61 74 65 20 61 20 64  ght generate a d
5a80: 6f 7a 65 6e 20 73 65 70 61 72 61 74 65 20 6d 61  ozen separate ma
5a90: 63 68 69 6e 65 20 63 6f 64 65 0a 69 6e 73 74 72  chine code.instr
5aa0: 75 63 74 69 6f 6e 73 2e 20 20 49 66 20 61 6e 79  uctions.  If any
5ab0: 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 20 69 6e   one of those in
5ac0: 73 74 72 75 63 74 69 6f 6e 73 20 69 73 20 65 76  structions is ev
5ad0: 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68  er evaluated, th
5ae0: 65 6e 0a 77 65 20 73 61 79 20 74 68 61 74 20 74  en.we say that t
5af0: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
5b00: 20 62 65 65 6e 20 74 65 73 74 65 64 2e 20 20 53   been tested.  S
5b10: 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
5b20: 69 74 20 6d 69 67 68 74 0a 62 65 20 74 68 65 20  it might.be the 
5b30: 63 61 73 65 20 74 68 61 74 20 74 68 65 20 63 6f  case that the co
5b40: 6e 64 69 74 69 6f 6e 61 6c 20 65 78 70 72 65 73  nditional expres
5b50: 73 69 6f 6e 20 69 73 0a 61 6c 77 61 79 73 20 66  sion is.always f
5b60: 61 6c 73 65 20 61 6e 64 20 74 68 65 20 22 64 22  alse and the "d"
5b70: 20 76 61 72 69 61 62 6c 65 20 69 73 0a 6e 65 76   variable is.nev
5b80: 65 72 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e 20  er incremented. 
5b90: 20 45 76 65 6e 20 73 6f 2c 20 73 74 61 74 65 6d   Even so, statem
5ba0: 65 6e 74 20 63 6f 76 65 72 61 67 65 20 63 6f 75  ent coverage cou
5bb0: 6e 74 73 20 74 68 69 73 20 6c 69 6e 65 20 6f 66  nts this line of
5bc0: 0a 63 6f 64 65 20 61 73 20 68 61 76 69 6e 67 20  .code as having 
5bd0: 62 65 65 6e 20 74 65 73 74 65 64 2e 3c 2f 70 3e  been tested.</p>
5be0: 0a 0a 3c 70 3e 42 72 61 6e 63 68 20 63 6f 76 65  ..<p>Branch cove
5bf0: 72 61 67 65 20 69 73 20 6d 6f 72 65 20 73 74 72  rage is more str
5c00: 69 63 74 2e 20 20 57 69 74 68 20 62 72 61 6e 63  ict.  With branc
5c10: 68 20 63 6f 76 65 72 61 67 65 2c 20 65 61 63 68  h coverage, each
5c20: 20 74 65 73 74 20 61 6e 64 0a 65 61 63 68 20 73   test and.each s
5c30: 75 62 62 6c 6f 63 6b 20 77 69 74 68 69 6e 20 74  ubblock within t
5c40: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
5c50: 63 6f 6e 73 69 64 65 72 65 64 20 73 65 70 61 72  considered separ
5c60: 61 74 65 6c 79 2e 20 20 49 6e 20 6f 72 64 65 72  ately.  In order
5c70: 0a 74 6f 20 61 63 68 69 65 76 65 20 31 30 30 25  .to achieve 100%
5c80: 20 62 72 61 6e 63 68 20 63 6f 76 65 72 61 67 65   branch coverage
5c90: 20 69 6e 20 74 68 65 20 65 78 61 6d 70 6c 65 20   in the example 
5ca0: 61 62 6f 76 65 2c 20 74 68 65 72 65 20 6d 75 73  above, there mus
5cb0: 74 20 62 65 20 61 74 0a 6c 65 61 73 74 20 74 68  t be at.least th
5cc0: 72 65 65 20 74 65 73 74 20 63 61 73 65 73 3a 3c  ree test cases:<
5cd0: 2f 70 3e 0a 0a 3c 70 3e 3c 75 6c 3e 0a 3c 6c 69  /p>..<p><ul>.<li
5ce0: 3e 20 61 3c 3d 62 0a 3c 6c 69 3e 20 61 3e 62 20  > a<=b.<li> a>b 
5cf0: 26 26 20 63 3d 3d 32 35 0a 3c 6c 69 3e 20 61 3e  && c==25.<li> a>
5d00: 62 20 26 26 20 63 21 3d 32 35 0a 3c 2f 75 6c 3e  b && c!=25.</ul>
5d10: 3c 2f 70 3e 0a 0a 3c 70 3e 41 6e 79 20 6f 6e 65  </p>..<p>Any one
5d20: 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 74 65   of the above te
5d30: 73 74 20 63 61 73 65 73 20 77 6f 75 6c 64 20 70  st cases would p
5d40: 72 6f 76 69 64 65 20 31 30 30 25 20 73 74 61 74  rovide 100% stat
5d50: 65 6d 65 6e 74 20 63 6f 76 65 72 61 67 65 0a 62  ement coverage.b
5d60: 75 74 20 61 6c 6c 20 74 68 72 65 65 20 61 72 65  ut all three are
5d70: 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 31 30   required for 10
5d80: 30 25 20 62 72 61 6e 63 68 20 63 6f 76 65 72 61  0% branch covera
5d90: 67 65 2e 20 20 47 65 6e 65 72 61 6c 6c 79 20 73  ge.  Generally s
5da0: 70 65 61 6b 69 6e 67 2c 0a 31 30 30 25 20 62 72  peaking,.100% br
5db0: 61 6e 63 68 20 63 6f 76 65 72 61 67 65 20 69 6d  anch coverage im
5dc0: 70 6c 69 65 73 20 31 30 30 25 20 73 74 61 74 65  plies 100% state
5dd0: 6d 65 6e 74 20 63 6f 76 65 72 61 67 65 2c 20 62  ment coverage, b
5de0: 75 74 20 74 68 65 20 63 6f 6e 76 65 72 73 65 20  ut the converse 
5df0: 69 73 0a 6e 6f 74 20 74 72 75 65 2e 20 20 54 6f  is.not true.  To
5e00: 20 72 65 65 6d 70 68 61 73 69 7a 65 2c 20 74 68   reemphasize, th
5e10: 65 0a 5b 54 48 33 5d 20 74 65 73 74 20 68 61 72  e.[TH3] test har
5e20: 6e 65 73 73 20 66 6f 72 20 53 51 4c 69 74 65 20  ness for SQLite 
5e30: 70 72 6f 76 69 64 65 73 20 74 68 65 20 73 74 72  provides the str
5e40: 6f 6e 67 65 72 20 66 6f 72 6d 20 6f 66 0a 74 65  onger form of.te
5e50: 73 74 20 63 6f 76 65 72 61 67 65 20 2d 20 31 30  st coverage - 10
5e60: 30 25 20 62 72 61 6e 63 68 20 74 65 73 74 20 63  0% branch test c
5e70: 6f 76 65 72 61 67 65 2e 3c 2f 70 3e 0a 0a 3c 74  overage.</p>..<t
5e80: 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 64  cl>hd_fragment d
5e90: 65 66 65 6e 73 69 76 65 63 6f 64 65 3c 2f 74 63  efensivecode</tc
5ea0: 6c 3e 0a 3c 68 32 3e 43 6f 76 65 72 61 67 65 20  l>.<h2>Coverage 
5eb0: 74 65 73 74 69 6e 67 20 6f 66 20 64 65 66 65 6e  testing of defen
5ec0: 73 69 76 65 20 63 6f 64 65 3c 2f 68 32 3e 0a 0a  sive code</h2>..
5ed0: 3c 70 3e 41 20 77 65 6c 6c 2d 77 72 69 74 74 65  <p>A well-writte
5ee0: 6e 20 43 20 70 72 6f 67 72 61 6d 20 77 69 6c 6c  n C program will
5ef0: 20 74 79 70 69 63 61 6c 6c 79 20 63 6f 6e 74 61   typically conta
5f00: 69 6e 20 73 6f 6d 65 20 64 65 66 65 6e 73 69 76  in some defensiv
5f10: 65 0a 63 6f 6e 64 69 74 69 6f 6e 61 6c 73 20 77  e.conditionals w
5f20: 68 69 63 68 20 69 6e 20 70 72 61 63 74 69 63 65  hich in practice
5f30: 20 61 72 65 20 61 6c 77 61 79 73 20 74 72 75 65   are always true
5f40: 20 6f 72 20 61 6c 77 61 79 73 20 66 61 6c 73 65   or always false
5f50: 2e 0a 54 68 69 73 20 6c 65 61 64 73 20 74 6f 20  ..This leads to 
5f60: 61 20 0a 70 72 6f 67 72 61 6d 6d 69 6e 67 20 64  a .programming d
5f70: 69 6c 65 6d 6d 61 3a 20 20 44 6f 65 73 20 6f 6e  ilemma:  Does on
5f80: 65 20 72 65 6d 6f 76 65 20 64 65 66 65 6e 73 69  e remove defensi
5f90: 76 65 20 63 6f 64 65 20 69 6e 20 6f 72 64 65 72  ve code in order
5fa0: 20 74 6f 20 6f 62 74 61 69 6e 0a 31 30 30 25 20   to obtain.100% 
5fb0: 62 72 61 6e 63 68 20 63 6f 76 65 72 61 67 65 3f  branch coverage?
5fc0: 3c 2f 70 3e 0a 0a 3c 70 3e 49 6e 20 53 51 4c 69  </p>..<p>In SQLi
5fd0: 74 65 2c 20 74 68 65 20 61 6e 73 77 65 72 20 74  te, the answer t
5fe0: 6f 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 71  o the previous q
5ff0: 75 65 73 74 69 6f 6e 20 69 73 20 22 6e 6f 22 2e  uestion is "no".
6000: 0a 46 6f 72 20 74 65 73 74 69 6e 67 20 70 75 72  .For testing pur
6010: 70 6f 73 65 73 2c 20 74 68 65 20 53 51 4c 69 74  poses, the SQLit
6020: 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 64 65  e source code de
6030: 66 69 6e 65 73 0a 6d 61 63 72 6f 73 20 63 61 6c  fines.macros cal
6040: 6c 65 64 20 41 4c 57 41 59 53 28 29 20 61 6e 64  led ALWAYS() and
6050: 20 4e 45 56 45 52 28 29 2e 20 20 20 54 68 65 20   NEVER().   The 
6060: 41 4c 57 41 59 53 28 29 20 6d 61 63 72 6f 0a 73  ALWAYS() macro.s
6070: 75 72 72 6f 75 6e 64 73 20 63 6f 6e 64 69 74 69  urrounds conditi
6080: 6f 6e 73 0a 77 68 69 63 68 20 61 72 65 20 65 78  ons.which are ex
6090: 70 65 63 74 65 64 20 74 6f 20 61 6c 77 61 79 73  pected to always
60a0: 20 65 76 61 6c 75 61 74 65 20 61 73 20 74 72 75   evaluate as tru
60b0: 65 20 61 6e 64 20 4e 45 56 45 52 28 29 20 73 75  e and NEVER() su
60c0: 72 72 6f 75 6e 64 73 0a 63 6f 6e 64 69 74 69 6f  rrounds.conditio
60d0: 6e 73 20 74 68 61 74 20 61 72 65 20 61 6c 77 61  ns that are alwa
60e0: 79 73 20 65 76 61 6c 75 61 74 65 64 20 74 6f 20  ys evaluated to 
60f0: 66 61 6c 73 65 2e 20 20 54 68 65 73 65 20 6d 61  false.  These ma
6100: 63 72 6f 73 20 73 65 72 76 65 20 61 73 0a 63 6f  cros serve as.co
6110: 6d 6d 65 6e 74 73 20 74 6f 20 69 6e 64 69 63 61  mments to indica
6120: 74 65 20 74 68 61 74 20 74 68 65 20 63 6f 6e 64  te that the cond
6130: 69 74 69 6f 6e 73 20 61 72 65 20 64 65 66 65 6e  itions are defen
6140: 73 69 76 65 20 63 6f 64 65 2e 0a 49 6e 20 72 65  sive code..In re
6150: 6c 65 61 73 65 20 62 75 69 6c 64 73 2c 20 74 68  lease builds, th
6160: 65 73 65 20 6d 61 63 72 6f 73 20 61 72 65 20 70  ese macros are p
6170: 61 73 73 2d 74 68 72 6f 75 67 68 73 3a 3c 2f 70  ass-throughs:</p
6180: 3e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 23  >..<codeblock>.#
6190: 64 65 66 69 6e 65 20 41 4c 57 41 59 53 28 58 29  define ALWAYS(X)
61a0: 20 20 28 58 29 0a 23 64 65 66 69 6e 65 20 4e 45    (X).#define NE
61b0: 56 45 52 28 58 29 20 20 20 28 58 29 0a 3c 2f 63  VER(X)   (X).</c
61c0: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 44 75  odeblock>..<p>Du
61d0: 72 69 6e 67 20 6d 6f 73 74 20 74 65 73 74 69 6e  ring most testin
61e0: 67 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 65 73  g, however, thes
61f0: 65 20 6d 61 63 72 6f 73 20 77 69 6c 6c 20 74 68  e macros will th
6200: 72 6f 77 20 61 6e 20 61 73 73 65 72 74 69 6f 6e  row an assertion
6210: 0a 66 61 75 6c 74 20 69 66 20 74 68 65 69 72 20  .fault if their 
6220: 61 72 67 75 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  argument does no
6230: 74 20 68 61 76 65 20 74 68 65 20 65 78 70 65 63  t have the expec
6240: 74 65 64 20 74 72 75 74 68 20 76 61 6c 75 65 2e  ted truth value.
6250: 20 20 54 68 69 73 0a 61 6c 65 72 74 73 20 74 68    This.alerts th
6260: 65 20 64 65 76 65 6c 6f 70 65 72 73 20 71 75 69  e developers qui
6270: 63 6b 6c 79 20 74 6f 20 69 6e 63 6f 72 72 65 63  ckly to incorrec
6280: 74 20 64 65 73 69 67 6e 20 61 73 73 75 6d 70 74  t design assumpt
6290: 69 6f 6e 73 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63  ions...<codebloc
62a0: 6b 3e 0a 23 64 65 66 69 6e 65 20 41 4c 57 41 59  k>.#define ALWAY
62b0: 53 28 58 29 20 20 28 28 58 29 3f 31 3a 61 73 73  S(X)  ((X)?1:ass
62c0: 65 72 74 28 30 29 2c 30 29 0a 23 64 65 66 69 6e  ert(0),0).#defin
62d0: 65 20 4e 45 56 45 52 28 58 29 20 20 20 28 28 58  e NEVER(X)   ((X
62e0: 29 3f 61 73 73 65 72 74 28 30 29 2c 31 3a 30 29  )?assert(0),1:0)
62f0: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
6300: 70 3e 57 68 65 6e 20 6d 65 61 73 75 72 69 6e 67  p>When measuring
6310: 20 74 65 73 74 20 63 6f 76 65 72 61 67 65 2c 20   test coverage, 
6320: 74 68 65 73 65 20 6d 61 63 72 6f 73 20 61 72 65  these macros are
6330: 20 64 65 66 69 6e 65 64 20 74 6f 20 62 65 20 63   defined to be c
6340: 6f 6e 73 74 61 6e 74 0a 74 72 75 74 68 20 76 61  onstant.truth va
6350: 6c 75 65 73 20 73 6f 20 74 68 61 74 20 74 68 65  lues so that the
6360: 79 20 64 6f 20 6e 6f 74 20 67 65 6e 65 72 61 74  y do not generat
6370: 65 20 61 73 73 65 6d 62 6c 79 20 6c 61 6e 67 75  e assembly langu
6380: 61 67 65 20 62 72 61 6e 63 68 0a 69 6e 73 74 72  age branch.instr
6390: 75 63 74 69 6f 6e 73 2c 20 61 6e 64 20 68 65 6e  uctions, and hen
63a0: 63 65 20 64 6f 20 6e 6f 74 20 63 6f 6d 65 20 69  ce do not come i
63b0: 6e 74 6f 20 70 6c 61 79 20 77 68 65 6e 20 63 61  nto play when ca
63c0: 6c 63 75 6c 61 74 69 6e 67 20 74 68 65 0a 62 72  lculating the.br
63d0: 61 6e 63 68 20 63 6f 76 65 72 61 67 65 3a 3c 2f  anch coverage:</
63e0: 70 3e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  p>..<codeblock>.
63f0: 23 64 65 66 69 6e 65 20 41 4c 57 41 59 53 28 58  #define ALWAYS(X
6400: 29 20 20 28 31 29 0a 23 64 65 66 69 6e 65 20 4e  )  (1).#define N
6410: 45 56 45 52 28 58 29 20 20 20 28 30 29 0a 3c 2f  EVER(X)   (0).</
6420: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 54  codeblock>..<p>T
6430: 68 65 20 74 65 73 74 20 73 75 69 74 65 20 69 73  he test suite is
6440: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 62 65 20   designed to be 
6450: 72 75 6e 20 74 68 72 65 65 20 74 69 6d 65 73 2c  run three times,
6460: 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 6f   once for each o
6470: 66 0a 74 68 65 20 41 4c 57 41 59 53 28 29 20 61  f.the ALWAYS() a
6480: 6e 64 20 4e 45 56 45 52 28 29 20 64 65 66 69 6e  nd NEVER() defin
6490: 69 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  itions shown abo
64a0: 76 65 2e 20 20 41 6c 6c 20 74 68 72 65 65 20 74  ve.  All three t
64b0: 65 73 74 20 72 75 6e 73 0a 73 68 6f 75 6c 64 20  est runs.should 
64c0: 79 69 65 6c 64 20 65 78 61 63 74 6c 79 20 74 68  yield exactly th
64d0: 65 20 73 61 6d 65 20 72 65 73 75 6c 74 2e 20 20  e same result.  
64e0: 54 68 65 72 65 20 69 73 20 61 20 72 75 6e 2d 74  There is a run-t
64f0: 69 6d 65 20 74 65 73 74 20 75 73 69 6e 67 0a 74  ime test using.t
6500: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74  he [sqlite3_test
6510: 5f 63 6f 6e 74 72 6f 6c 5d 28 5b 53 51 4c 49 54  _control]([SQLIT
6520: 45 5f 54 45 53 54 43 54 52 4c 5f 41 4c 57 41 59  E_TESTCTRL_ALWAY
6530: 53 5d 2c 20 2e 2e 2e 29 20 69 6e 74 65 72 66 61  S], ...) interfa
6540: 63 65 20 74 68 61 74 0a 63 61 6e 20 62 65 20 75  ce that.can be u
6550: 73 65 64 20 74 6f 20 76 65 72 69 66 79 20 74 68  sed to verify th
6560: 61 74 20 74 68 65 20 6d 61 63 72 6f 73 20 61 72  at the macros ar
6570: 65 20 63 6f 72 72 65 63 74 6c 79 20 73 65 74 20  e correctly set 
6580: 74 6f 20 74 68 65 20 66 69 72 73 74 0a 66 6f 72  to the first.for
6590: 6d 20 28 74 68 65 20 70 61 73 73 2d 74 68 72 6f  m (the pass-thro
65a0: 75 67 68 20 66 6f 72 6d 29 20 66 6f 72 20 64 65  ugh form) for de
65b0: 70 6c 6f 79 6d 65 6e 74 2e 3c 2f 70 3e 0a 0a 3c  ployment.</p>..<
65c0: 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
65d0: 7b 74 65 73 74 63 61 73 65 7d 20 7b 74 65 73 74  {testcase} {test
65e0: 63 61 73 65 20 6d 61 63 72 6f 73 7d 3c 2f 74 63  case macros}</tc
65f0: 6c 3e 0a 3c 68 32 3e 46 6f 72 63 69 6e 67 20 63  l>.<h2>Forcing c
6600: 6f 76 65 72 61 67 65 20 6f 66 20 62 6f 75 6e 64  overage of bound
6610: 61 72 79 20 76 61 6c 75 65 73 20 61 6e 64 20 62  ary values and b
6620: 6f 6f 6c 65 61 6e 20 76 65 63 74 6f 72 20 74 65  oolean vector te
6630: 73 74 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 41 6e 6f  sts</h2>..<p>Ano
6640: 74 68 65 72 20 6d 61 63 72 6f 20 75 73 65 64 20  ther macro used 
6650: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 20 77  in conjunction w
6660: 69 74 68 20 74 65 73 74 20 63 6f 76 65 72 61 67  ith test coverag
6670: 65 20 6d 65 61 73 75 72 65 6d 65 6e 74 20 69 73  e measurement is
6680: 0a 74 68 65 20 3c 74 74 3e 74 65 73 74 63 61 73  .the <tt>testcas
6690: 65 28 29 3c 2f 74 74 3e 20 6d 61 63 72 6f 2e 20  e()</tt> macro. 
66a0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
66b0: 20 61 20 63 6f 6e 64 69 74 69 6f 6e 20 66 6f 72   a condition for
66c0: 20 77 68 69 63 68 0a 77 65 20 77 61 6e 74 20 74   which.we want t
66d0: 65 73 74 20 63 61 73 65 73 20 74 68 61 74 20 65  est cases that e
66e0: 76 61 6c 75 61 74 65 20 74 6f 20 62 6f 74 68 20  valuate to both 
66f0: 74 72 75 65 20 61 6e 64 20 66 61 6c 73 65 2e 0a  true and false..
6700: 49 6e 20 6e 6f 6e 2d 63 6f 76 65 72 61 67 65 20  In non-coverage 
6710: 62 75 69 6c 64 73 20 28 74 68 61 74 20 69 73 20  builds (that is 
6720: 74 6f 20 73 61 79 2c 20 69 6e 20 72 65 6c 65 61  to say, in relea
6730: 73 65 20 62 75 69 6c 64 73 29 20 74 68 65 0a 3c  se builds) the.<
6740: 74 74 3e 74 65 73 74 63 61 73 65 28 29 3c 2f 74  tt>testcase()</t
6750: 74 3e 20 6d 61 63 72 6f 20 69 73 20 61 20 6e 6f  t> macro is a no
6760: 2d 6f 70 3a 3c 2f 70 3e 0a 0a 3c 63 6f 64 65 62  -op:</p>..<codeb
6770: 6c 6f 63 6b 3e 0a 23 64 65 66 69 6e 65 20 74 65  lock>.#define te
6780: 73 74 63 61 73 65 28 58 29 0a 3c 2f 63 6f 64 65  stcase(X).</code
6790: 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 42 75 74 20 69  block>..<p>But i
67a0: 6e 20 61 20 63 6f 76 65 72 61 67 65 20 6d 65 61  n a coverage mea
67b0: 73 75 72 69 6e 67 20 62 75 69 6c 64 2c 20 74 68  suring build, th
67c0: 65 20 3c 74 74 3e 74 65 73 74 63 61 73 65 28 29  e <tt>testcase()
67d0: 3c 2f 74 74 3e 20 6d 61 63 72 6f 0a 67 65 6e 65  </tt> macro.gene
67e0: 72 61 74 65 73 20 63 6f 64 65 20 74 68 61 74 20  rates code that 
67f0: 65 76 61 6c 75 61 74 65 73 20 74 68 65 20 63 6f  evaluates the co
6800: 6e 64 69 74 69 6f 6e 61 6c 20 65 78 70 72 65 73  nditional expres
6810: 73 69 6f 6e 20 69 6e 20 69 74 73 20 61 72 67 75  sion in its argu
6820: 6d 65 6e 74 2e 20 20 0a 54 68 65 6e 20 64 75 72  ment.  .Then dur
6830: 69 6e 67 20 61 6e 61 6c 79 73 69 73 2c 20 61 20  ing analysis, a 
6840: 63 68 65 63 6b 0a 69 73 20 6d 61 64 65 20 74 6f  check.is made to
6850: 20 65 6e 73 75 72 65 20 74 65 73 74 73 20 65 78   ensure tests ex
6860: 69 73 74 20 74 68 61 74 20 65 76 61 6c 75 61 74  ist that evaluat
6870: 65 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 61  e the conditiona
6880: 6c 20 74 6f 20 62 6f 74 68 20 74 72 75 65 0a 61  l to both true.a
6890: 6e 64 20 66 61 6c 73 65 2e 20 20 3c 74 74 3e 54  nd false.  <tt>T
68a0: 65 73 74 63 61 73 65 28 29 3c 2f 74 74 3e 20 6d  estcase()</tt> m
68b0: 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 2c 20  acros are used, 
68c0: 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20  for example, to 
68d0: 68 65 6c 70 20 76 65 72 69 66 79 0a 74 68 61 74  help verify.that
68e0: 20 62 6f 75 6e 64 61 72 79 20 76 61 6c 75 65 73   boundary values
68f0: 20 61 72 65 20 74 65 73 74 65 64 2e 20 20 46 6f   are tested.  Fo
6900: 72 20 65 78 61 6d 70 6c 65 3a 3c 2f 70 3e 0a 0a  r example:</p>..
6910: 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 74 65 73 74  <codeblock>.test
6920: 63 61 73 65 28 20 61 3d 3d 62 20 29 3b 0a 74 65  case( a==b );.te
6930: 73 74 63 61 73 65 28 20 61 3d 3d 62 2b 31 20 29  stcase( a==b+1 )
6940: 3b 0a 69 66 28 20 61 3e 62 20 26 26 20 63 21 3d  ;.if( a>b && c!=
6950: 32 35 20 29 7b 20 64 2b 2b 3b 20 7d 0a 3c 2f 63  25 ){ d++; }.</c
6960: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 54 65  odeblock>..<p>Te
6970: 73 74 63 61 73 65 20 6d 61 63 72 6f 73 20 61 72  stcase macros ar
6980: 65 20 61 6c 73 6f 20 75 73 65 64 20 77 68 65 6e  e also used when
6990: 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 61 73   two or more cas
69a0: 65 73 20 6f 66 20 61 20 73 77 69 74 63 68 0a 73  es of a switch.s
69b0: 74 61 74 65 6d 65 6e 74 20 67 6f 20 74 6f 20 74  tatement go to t
69c0: 68 65 20 73 61 6d 65 20 62 6c 6f 63 6b 20 6f 66  he same block of
69d0: 20 63 6f 64 65 2c 20 74 6f 20 6d 61 6b 65 20 73   code, to make s
69e0: 75 72 65 20 74 68 61 74 20 74 68 65 20 63 6f 64  ure that the cod
69f0: 65 20 77 61 73 0a 72 65 61 63 68 65 64 20 66 6f  e was.reached fo
6a00: 72 20 61 6c 6c 20 63 61 73 65 73 3a 3c 2f 70 3e  r all cases:</p>
6a10: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 73 77  ..<codeblock>.sw
6a20: 69 74 63 68 28 20 6f 70 20 29 7b 0a 20 20 63 61  itch( op ){.  ca
6a30: 73 65 20 4f 50 5f 41 64 64 3a 0a 20 20 63 61 73  se OP_Add:.  cas
6a40: 65 20 4f 50 5f 53 75 62 74 72 61 63 74 3a 20 7b  e OP_Subtract: {
6a50: 0a 20 20 20 20 74 65 73 74 63 61 73 65 28 20 6f  .    testcase( o
6a60: 70 3d 3d 4f 50 5f 41 64 64 20 29 3b 0a 20 20 20  p==OP_Add );.   
6a70: 20 74 65 73 74 63 61 73 65 28 20 6f 70 3d 3d 4f   testcase( op==O
6a80: 50 5f 53 75 62 74 72 61 63 74 20 29 3b 0a 20 20  P_Subtract );.  
6a90: 20 20 2f 2a 20 2e 2e 2e 20 2a 2f 0a 20 20 20 20    /* ... */.    
6aa0: 62 72 65 61 6b 3b 0a 20 20 7d 0a 20 20 2f 2a 20  break;.  }.  /* 
6ab0: 2e 2e 2e 20 2a 2f 0a 7d 0a 3c 2f 63 6f 64 65 62  ... */.}.</codeb
6ac0: 6c 6f 63 6b 3e 0a 0a 3c 70 3e 46 6f 72 20 62 69  lock>..<p>For bi
6ad0: 74 6d 61 73 6b 20 74 65 73 74 73 2c 20 3c 74 74  tmask tests, <tt
6ae0: 3e 74 65 73 74 63 61 73 65 28 29 3c 2f 74 74 3e  >testcase()</tt>
6af0: 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64   macros are used
6b00: 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
6b10: 65 76 65 72 79 0a 62 69 74 20 6f 66 20 74 68 65  every.bit of the
6b20: 20 62 69 74 6d 61 73 6b 20 61 66 66 65 63 74 73   bitmask affects
6b30: 20 74 68 65 20 6f 75 74 63 6f 6d 65 2e 20 20 46   the outcome.  F
6b40: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 74  or example, in t
6b50: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 62 6c 6f  he following blo
6b60: 63 6b 0a 6f 66 20 63 6f 64 65 2c 20 74 68 65 20  ck.of code, the 
6b70: 63 6f 6e 64 69 74 69 6f 6e 20 69 73 20 74 72 75  condition is tru
6b80: 65 20 69 66 20 74 68 65 20 6d 61 73 6b 20 63 6f  e if the mask co
6b90: 6e 74 61 69 6e 73 20 65 69 74 68 65 72 20 6f 66  ntains either of
6ba0: 20 74 77 6f 20 62 69 74 73 0a 69 6e 64 69 63 61   two bits.indica
6bb0: 74 69 6e 67 20 65 69 74 68 65 72 20 61 20 4d 41  ting either a MA
6bc0: 49 4e 5f 44 42 20 6f 72 20 61 20 54 45 4d 50 5f  IN_DB or a TEMP_
6bd0: 44 42 20 69 73 20 62 65 69 6e 67 20 6f 70 65 6e  DB is being open
6be0: 65 64 2e 20 20 0a 54 68 65 20 3c 74 74 3e 74 65  ed.  .The <tt>te
6bf0: 73 74 63 61 73 65 28 29 3c 2f 74 74 3e 0a 6d 61  stcase()</tt>.ma
6c00: 63 72 6f 73 20 74 68 61 74 20 70 72 65 63 65 64  cros that preced
6c10: 65 20 74 68 65 20 69 66 20 73 74 61 74 65 6d 65  e the if stateme
6c20: 6e 74 20 76 65 72 69 66 79 20 74 68 61 74 20 62  nt verify that b
6c30: 6f 74 68 20 63 61 73 65 73 20 61 72 65 20 74 65  oth cases are te
6c40: 73 74 65 64 3a 3c 2f 70 3e 0a 0a 3c 63 6f 64 65  sted:</p>..<code
6c50: 62 6c 6f 63 6b 3e 0a 74 65 73 74 63 61 73 65 28  block>.testcase(
6c60: 20 6d 61 73 6b 20 26 20 53 51 4c 49 54 45 5f 4f   mask & SQLITE_O
6c70: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 29 3b 0a 74  PEN_MAIN_DB );.t
6c80: 65 73 74 63 61 73 65 28 20 6d 61 73 6b 20 26 20  estcase( mask & 
6c90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
6ca0: 5f 44 42 20 29 3b 0a 69 66 28 20 28 6d 61 73 6b  _DB );.if( (mask
6cb0: 20 26 20 28 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   & (SQLITE_OPEN_
6cc0: 4d 41 49 4e 5f 44 42 7c 53 51 4c 49 54 45 5f 4f  MAIN_DB|SQLITE_O
6cd0: 50 45 4e 5f 54 45 4d 50 5f 44 42 29 29 21 3d 30  PEN_TEMP_DB))!=0
6ce0: 20 29 7b 20 2e 2e 2e 20 7d 0a 3c 2f 63 6f 64 65   ){ ... }.</code
6cf0: 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 54 68 65 20 53  block>..<p>The S
6d00: 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64  QLite source cod
6d10: 65 20 63 6f 6e 74 61 69 6e 73 20 3c 74 63 6c 3e  e contains <tcl>
6d20: 4e 20 7b 24 73 74 61 74 28 6e 54 65 73 74 63 61  N {$stat(nTestca
6d30: 73 65 29 7d 3c 2f 74 63 6c 3e 0a 75 73 65 73 20  se)}</tcl>.uses 
6d40: 6f 66 20 74 68 65 20 3c 74 74 3e 74 65 73 74 63  of the <tt>testc
6d50: 61 73 65 28 29 3c 2f 74 74 3e 20 6d 61 63 72 6f  ase()</tt> macro
6d60: 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66  .</p>..<tcl>hd_f
6d70: 72 61 67 6d 65 6e 74 20 7b 6d 63 64 63 7d 20 2a  ragment {mcdc} *
6d80: 4d 43 2f 44 43 20 7b 4d 43 2f 44 43 20 74 65 73  MC/DC {MC/DC tes
6d90: 74 69 6e 67 7d 3c 2f 74 63 6c 3e 0a 3c 68 32 3e  ting}</tcl>.<h2>
6da0: 42 72 61 6e 63 68 20 63 6f 76 65 72 61 67 65 20  Branch coverage 
6db0: 76 65 72 73 75 73 20 4d 43 2f 44 43 3c 2f 68 32  versus MC/DC</h2
6dc0: 3e 0a 0a 3c 70 3e 54 77 6f 20 6d 65 74 68 6f 64  >..<p>Two method
6dd0: 73 20 6f 66 20 6d 65 61 73 75 72 69 6e 67 20 74  s of measuring t
6de0: 65 73 74 20 63 6f 76 65 72 61 67 65 20 77 65 72  est coverage wer
6df0: 65 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  e described abov
6e00: 65 3a 0a 22 73 74 61 74 65 6d 65 6e 74 22 20 61  e:."statement" a
6e10: 6e 64 20 22 62 72 61 6e 63 68 22 20 63 6f 76 65  nd "branch" cove
6e20: 72 61 67 65 2e 20 20 54 68 65 72 65 20 61 72 65  rage.  There are
6e30: 20 6d 61 6e 79 20 6f 74 68 65 72 20 74 65 73 74   many other test
6e40: 20 63 6f 76 65 72 61 67 65 0a 6d 65 74 72 69 63   coverage.metric
6e50: 73 20 62 65 73 69 64 65 73 20 74 68 65 73 65 20  s besides these 
6e60: 74 77 6f 2e 20 20 41 6e 6f 74 68 65 72 20 70 6f  two.  Another po
6e70: 70 75 6c 61 72 20 6d 65 74 72 69 63 20 69 73 20  pular metric is 
6e80: 22 4d 6f 64 69 66 69 65 64 0a 43 6f 6e 64 69 74  "Modified.Condit
6e90: 69 6f 6e 2f 44 65 63 69 73 69 6f 6e 20 43 6f 76  ion/Decision Cov
6ea0: 65 72 61 67 65 22 20 6f 72 20 4d 43 2f 44 43 2e  erage" or MC/DC.
6eb0: 20 20 0a 5b 68 74 74 70 3a 2f 2f 65 6e 2e 77 69    .[http://en.wi
6ec0: 6b 69 70 65 64 69 61 2e 6f 72 67 2f 77 69 6b 69  kipedia.org/wiki
6ed0: 2f 4d 6f 64 69 66 69 65 64 5f 43 6f 6e 64 69 74  /Modified_Condit
6ee0: 69 6f 6e 2f 44 65 63 69 73 69 6f 6e 5f 43 6f 76  ion/Decision_Cov
6ef0: 65 72 61 67 65 20 7c 20 57 69 6b 69 70 65 64 69  erage | Wikipedi
6f00: 61 5d 0a 64 65 66 69 6e 65 73 20 4d 43 2f 44 43  a].defines MC/DC
6f10: 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e   as follows:</p>
6f20: 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e 20 45 61 63 68  ..<ul>.<li> Each
6f30: 20 64 65 63 69 73 69 6f 6e 20 74 72 69 65 73 20   decision tries 
6f40: 65 76 65 72 79 20 70 6f 73 73 69 62 6c 65 20 6f  every possible o
6f50: 75 74 63 6f 6d 65 2e 0a 3c 6c 69 3e 20 45 61 63  utcome..<li> Eac
6f60: 68 20 63 6f 6e 64 69 74 69 6f 6e 20 69 6e 20 61  h condition in a
6f70: 20 64 65 63 69 73 69 6f 6e 20 74 61 6b 65 73 20   decision takes 
6f80: 6f 6e 20 65 76 65 72 79 20 70 6f 73 73 69 62 6c  on every possibl
6f90: 65 20 6f 75 74 63 6f 6d 65 2e 0a 3c 6c 69 3e 20  e outcome..<li> 
6fa0: 45 61 63 68 20 65 6e 74 72 79 20 61 6e 64 20 65  Each entry and e
6fb0: 78 69 74 20 70 6f 69 6e 74 20 69 73 20 69 6e 76  xit point is inv
6fc0: 6f 6b 65 64 2e 0a 3c 6c 69 3e 20 45 61 63 68 20  oked..<li> Each 
6fd0: 63 6f 6e 64 69 74 69 6f 6e 20 69 6e 20 61 20 64  condition in a d
6fe0: 65 63 69 73 69 6f 6e 20 69 73 20 73 68 6f 77 6e  ecision is shown
6ff0: 20 74 6f 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c   to independentl
7000: 79 0a 20 20 20 20 20 61 66 66 65 63 74 20 74 68  y.     affect th
7010: 65 20 6f 75 74 63 6f 6d 65 20 6f 66 20 74 68 65  e outcome of the
7020: 20 64 65 63 69 73 69 6f 6e 2e 0a 3c 2f 75 6c 3e   decision..</ul>
7030: 0a 0a 3c 70 3e 49 6e 20 74 68 65 20 43 20 70 72  ..<p>In the C pr
7040: 6f 67 72 61 6d 6d 69 6e 67 20 6c 61 6e 67 75 61  ogramming langua
7050: 67 65 20 0a 77 68 65 72 65 20 3c 62 3e 3c 74 74  ge .where <b><tt
7060: 3e 26 61 6d 70 3b 26 61 6d 70 3b 3c 2f 74 74 3e  >&amp;&amp;</tt>
7070: 3c 2f 62 3e 20 61 6e 64 20 3c 62 3e 3c 74 74 3e  </b> and <b><tt>
7080: 7c 7c 3c 2f 74 74 3e 3c 2f 62 3e 0a 61 72 65 20  ||</tt></b>.are 
7090: 22 73 68 6f 72 74 2d 63 69 72 63 75 69 74 22 20  "short-circuit" 
70a0: 6f 70 65 72 61 74 6f 72 73 2c 20 4d 43 2f 44 43  operators, MC/DC
70b0: 20 61 6e 64 20 62 72 61 6e 63 68 20 63 6f 76 65   and branch cove
70c0: 72 61 67 65 20 61 72 65 20 76 65 72 79 20 6e 65  rage are very ne
70d0: 61 72 6c 79 0a 74 68 65 20 73 61 6d 65 20 74 68  arly.the same th
70e0: 69 6e 67 2e 20 20 54 68 65 20 70 72 69 6d 61 72  ing.  The primar
70f0: 79 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  y difference is 
7100: 69 6e 20 62 6f 6f 6c 65 61 6e 20 76 65 63 74 6f  in boolean vecto
7110: 72 20 74 65 73 74 73 2e 0a 4f 6e 65 20 63 61 6e  r tests..One can
7120: 20 74 65 73 74 20 66 6f 72 20 61 6e 79 20 6f 66   test for any of
7130: 20 73 65 76 65 72 61 6c 20 62 69 74 73 20 69 6e   several bits in
7140: 20 62 69 74 2d 76 65 63 74 6f 72 20 61 6e 64 20   bit-vector and 
7150: 73 74 69 6c 6c 20 6f 62 74 61 69 6e 0a 31 30 30  still obtain.100
7160: 25 20 62 72 61 6e 63 68 20 74 65 73 74 20 63 6f  % branch test co
7170: 76 65 72 61 67 65 20 65 76 65 6e 20 74 68 6f 75  verage even thou
7180: 67 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c  gh the second el
7190: 65 6d 65 6e 74 20 6f 66 20 4d 43 2f 44 43 20 2d  ement of MC/DC -
71a0: 20 74 68 65 0a 72 65 71 75 69 72 65 6d 65 6e 74   the.requirement
71b0: 20 74 68 61 74 20 65 61 63 68 20 63 6f 6e 64 69   that each condi
71c0: 74 69 6f 6e 20 69 6e 20 61 20 64 65 63 69 73 69  tion in a decisi
71d0: 6f 6e 20 74 61 6b 65 20 6f 6e 20 65 76 65 72 79  on take on every
71e0: 20 70 6f 73 73 69 62 6c 65 20 6f 75 74 63 6f 6d   possible outcom
71f0: 65 20 2d 0a 6d 69 67 68 74 20 6e 6f 74 20 62 65  e -.might not be
7200: 20 73 61 74 69 73 66 69 65 64 2e 3c 2f 70 3e 0a   satisfied.</p>.
7210: 0a 3c 70 3e 53 51 4c 69 74 65 20 75 73 65 73 20  .<p>SQLite uses 
7220: 3c 74 74 3e 74 65 73 74 63 61 73 65 28 29 3c 2f  <tt>testcase()</
7230: 74 74 3e 20 6d 61 63 72 6f 73 20 61 73 20 64 65  tt> macros as de
7240: 73 63 72 69 62 65 64 20 69 6e 20 74 68 65 20 70  scribed in the p
7250: 72 65 76 69 6f 75 73 0a 73 75 62 73 65 63 74 69  revious.subsecti
7260: 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  on to make sure 
7270: 74 68 61 74 20 65 76 65 72 79 20 63 6f 6e 64 69  that every condi
7280: 74 69 6f 6e 20 69 6e 20 61 20 62 69 74 2d 76 65  tion in a bit-ve
7290: 63 74 6f 72 20 64 65 63 69 73 69 6f 6e 20 74 61  ctor decision ta
72a0: 6b 65 73 0a 6f 6e 20 65 76 65 72 79 20 70 6f 73  kes.on every pos
72b0: 73 69 62 6c 65 20 6f 75 74 63 6f 6d 65 2e 20 20  sible outcome.  
72c0: 49 6e 20 74 68 69 73 20 77 61 79 2c 20 53 51 4c  In this way, SQL
72d0: 69 74 65 20 61 6c 73 6f 20 61 63 68 69 65 76 65  ite also achieve
72e0: 73 20 31 30 30 25 20 4d 43 2f 44 43 0a 69 6e 20  s 100% MC/DC.in 
72f0: 61 64 64 69 74 69 6f 6e 20 74 6f 20 31 30 30 25  addition to 100%
7300: 20 62 72 61 6e 63 68 20 63 6f 76 65 72 61 67 65   branch coverage
7310: 2e 3c 2f 70 3e 0a 0a 3c 68 32 3e 4d 65 61 73 75  .</p>..<h2>Measu
7320: 72 69 6e 67 20 62 72 61 6e 63 68 20 63 6f 76 65  ring branch cove
7330: 72 61 67 65 3c 2f 68 32 3e 0a 0a 3c 70 3e 42 72  rage</h2>..<p>Br
7340: 61 6e 63 68 20 63 6f 76 65 72 61 67 65 20 69 6e  anch coverage in
7350: 20 53 51 4c 69 74 65 20 69 73 20 63 75 72 72 65   SQLite is curre
7360: 6e 74 6c 79 20 6d 65 61 73 75 72 65 64 0a 75 73  ntly measured.us
7370: 69 6e 67 20 5b 68 74 74 70 73 3a 2f 2f 67 63 63  ing [https://gcc
7380: 2e 67 6e 75 2e 6f 72 67 2f 6f 6e 6c 69 6e 65 64  .gnu.org/onlined
7390: 6f 63 73 2f 67 63 63 2f 47 63 6f 76 2e 68 74 6d  ocs/gcc/Gcov.htm
73a0: 6c 7c 67 63 6f 76 5d 20 77 69 74 68 20 74 68 65  l|gcov] with the
73b0: 20 22 2d 62 22 0a 6f 70 74 69 6f 6e 2e 20 20 46   "-b".option.  F
73c0: 69 72 73 74 20 74 68 65 20 74 65 73 74 20 70 72  irst the test pr
73d0: 6f 67 72 61 6d 20 69 73 20 63 6f 6d 70 69 6c 65  ogram is compile
73e0: 64 20 75 73 69 6e 67 20 6f 70 74 69 6f 6e 73 0a  d using options.
73f0: 22 2d 67 20 2d 66 70 72 6f 66 69 6c 65 2d 61 72  "-g -fprofile-ar
7400: 63 73 20 2d 66 74 65 73 74 2d 63 6f 76 65 72 61  cs -ftest-covera
7410: 67 65 22 20 61 6e 64 20 74 68 65 6e 20 74 68 65  ge" and then the
7420: 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 69 73   test program is
7430: 20 72 75 6e 2e 0a 54 68 65 6e 20 22 67 63 6f 76   run..Then "gcov
7440: 20 2d 62 22 20 69 73 20 72 75 6e 20 74 6f 20 67   -b" is run to g
7450: 65 6e 65 72 61 74 65 20 61 20 63 6f 76 65 72 61  enerate a covera
7460: 67 65 20 72 65 70 6f 72 74 2e 0a 54 68 65 20 63  ge report..The c
7470: 6f 76 65 72 61 67 65 20 72 65 70 6f 72 74 20 69  overage report i
7480: 73 20 76 65 72 62 6f 73 65 20 61 6e 64 20 69 6e  s verbose and in
7490: 63 6f 6e 76 65 6e 69 65 6e 74 20 74 6f 20 72 65  convenient to re
74a0: 61 64 2c 20 0a 73 6f 20 74 68 65 20 67 63 6f 76  ad, .so the gcov
74b0: 2d 67 65 6e 65 72 61 74 65 64 20 72 65 70 6f 72  -generated repor
74c0: 74 20 69 73 20 70 72 6f 63 65 73 73 65 64 20 75  t is processed u
74d0: 73 69 6e 67 0a 73 6f 6d 65 20 73 69 6d 70 6c 65  sing.some simple
74e0: 20 73 63 72 69 70 74 73 20 74 6f 20 70 75 74 20   scripts to put 
74f0: 69 74 20 69 6e 74 6f 20 61 20 6d 6f 72 65 20 68  it into a more h
7500: 75 6d 61 6e 2d 66 72 69 65 6e 64 6c 79 20 66 6f  uman-friendly fo
7510: 72 6d 61 74 2e 0a 54 68 69 73 20 65 6e 74 69 72  rmat..This entir
7520: 65 20 70 72 6f 63 65 73 73 20 69 73 20 61 75 74  e process is aut
7530: 6f 6d 61 74 65 64 20 75 73 69 6e 67 20 73 63 72  omated using scr
7540: 69 70 74 73 2c 20 6f 66 20 63 6f 75 72 73 65 2e  ipts, of course.
7550: 0a 0a 3c 70 3e 4e 6f 74 65 20 74 68 61 74 20 72  ..<p>Note that r
7560: 75 6e 6e 69 6e 67 20 53 51 4c 69 74 65 20 77 69  unning SQLite wi
7570: 74 68 20 67 63 6f 76 20 69 73 20 6e 6f 74 20 61  th gcov is not a
7580: 20 74 65 73 74 20 6f 66 20 53 51 4c 69 74 65 20   test of SQLite 
7590: 26 6d 64 61 73 68 3b 0a 69 74 20 69 73 20 61 20  &mdash;.it is a 
75a0: 74 65 73 74 20 6f 66 20 74 68 65 20 74 65 73 74  test of the test
75b0: 20 73 75 69 74 65 2e 20 20 54 68 65 20 67 63 6f   suite.  The gco
75c0: 76 20 72 75 6e 20 64 6f 65 73 20 6e 6f 74 20 74  v run does not t
75d0: 65 73 74 20 53 51 4c 69 74 65 20 62 65 63 61 75  est SQLite becau
75e0: 73 65 0a 74 68 65 20 2d 66 70 72 6f 66 69 6c 65  se.the -fprofile
75f0: 2d 61 72 67 73 20 61 6e 64 20 2d 66 74 65 73 74  -args and -ftest
7600: 2d 63 6f 76 65 72 61 67 65 20 6f 70 74 69 6f 6e  -coverage option
7610: 73 20 63 61 75 73 65 20 74 68 65 20 63 6f 6d 70  s cause the comp
7620: 69 6c 65 72 20 74 6f 20 0a 67 65 6e 65 72 61 74  iler to .generat
7630: 65 20 64 69 66 66 65 72 65 6e 74 20 63 6f 64 65  e different code
7640: 2e 20 20 0a 54 68 65 20 67 63 6f 76 20 72 75 6e  .  .The gcov run
7650: 20 6d 65 72 65 6c 79 20 76 65 72 69 66 69 65 73   merely verifies
7660: 20 74 68 61 74 20 74 68 65 20 74 65 73 74 20 73   that the test s
7670: 75 69 74 65 20 70 72 6f 76 69 64 65 73 20 31 30  uite provides 10
7680: 30 25 20 62 72 61 6e 63 68 20 74 65 73 74 0a 63  0% branch test.c
7690: 6f 76 65 72 61 67 65 2e 20 20 54 68 65 20 67 63  overage.  The gc
76a0: 6f 76 20 72 75 6e 20 69 73 20 61 20 74 65 73 74  ov run is a test
76b0: 20 6f 66 20 74 68 65 20 74 65 73 74 20 2d 20 61   of the test - a
76c0: 20 6d 65 74 61 2d 74 65 73 74 2e 0a 0a 3c 70 3e   meta-test...<p>
76d0: 41 66 74 65 72 20 67 63 6f 76 20 68 61 73 20 62  After gcov has b
76e0: 65 65 6e 20 72 75 6e 20 74 6f 20 76 65 72 69 66  een run to verif
76f0: 79 20 31 30 30 25 20 62 72 61 6e 63 68 20 74 65  y 100% branch te
7700: 73 74 20 63 6f 76 65 72 61 67 65 2c 0a 74 68 65  st coverage,.the
7710: 6e 20 74 68 65 20 74 65 73 74 20 70 72 6f 67 72  n the test progr
7720: 61 6d 20 69 73 20 72 65 63 6f 6d 70 69 6c 65 64  am is recompiled
7730: 20 75 73 69 6e 67 20 64 65 6c 69 76 65 72 79 20   using delivery 
7740: 63 6f 6d 70 69 6c 65 72 20 6f 70 74 69 6f 6e 73  compiler options
7750: 0a 28 77 69 74 68 6f 75 74 20 74 68 65 20 73 70  .(without the sp
7760: 65 63 69 61 6c 20 2d 66 70 72 6f 66 69 6c 65 2d  ecial -fprofile-
7770: 61 72 63 73 20 61 6e 64 20 2d 66 74 65 73 74 2d  arcs and -ftest-
7780: 63 6f 76 65 72 61 67 65 20 6f 70 74 69 6f 6e 73  coverage options
7790: 29 0a 61 6e 64 20 74 68 65 20 74 65 73 74 20 70  ).and the test p
77a0: 72 6f 67 72 61 6d 20 69 73 20 72 65 72 75 6e 2e  rogram is rerun.
77b0: 0a 54 68 69 73 20 73 65 63 6f 6e 64 20 72 75 6e  .This second run
77c0: 20 69 73 20 74 68 65 20 61 63 74 75 61 6c 20 74   is the actual t
77d0: 65 73 74 20 6f 66 20 53 51 4c 69 74 65 2e 0a 0a  est of SQLite...
77e0: 3c 70 3e 49 74 20 69 73 20 69 6d 70 6f 72 74 61  <p>It is importa
77f0: 6e 74 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  nt to verify tha
7800: 74 20 74 68 65 20 67 63 6f 76 20 74 65 73 74 20  t the gcov test 
7810: 72 75 6e 20 0a 61 6e 64 20 74 68 65 20 73 65 63  run .and the sec
7820: 6f 6e 64 20 72 65 61 6c 20 74 65 73 74 20 72 75  ond real test ru
7830: 6e 20 62 6f 74 68 20 67 69 76 65 20 74 68 65 20  n both give the 
7840: 73 61 6d 65 20 6f 75 74 70 75 74 2e 20 20 41 6e  same output.  An
7850: 79 0a 64 69 66 66 65 72 65 6e 63 65 73 20 69 6e  y.differences in
7860: 20 6f 75 74 70 75 74 20 69 6e 64 69 63 61 74 65   output indicate
7870: 20 65 69 74 68 65 72 20 74 68 65 20 75 73 65 20   either the use 
7880: 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 6f 72 0a  of undefined or.
7890: 69 6e 64 65 74 65 72 6d 69 6e 61 74 65 20 62 65  indeterminate be
78a0: 68 61 76 69 6f 72 20 69 6e 20 74 68 65 20 53 51  havior in the SQ
78b0: 4c 69 74 65 20 63 6f 64 65 20 28 61 6e 64 20 68  Lite code (and h
78c0: 65 6e 63 65 20 61 20 62 75 67 29 2c 20 0a 6f 72  ence a bug), .or
78d0: 20 61 20 62 75 67 20 69 6e 20 74 68 65 20 63 6f   a bug in the co
78e0: 6d 70 69 6c 65 72 2e 0a 4e 6f 74 65 20 74 68 61  mpiler..Note tha
78f0: 74 20 53 51 4c 69 74 65 20 68 61 73 2c 20 6f 76  t SQLite has, ov
7900: 65 72 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  er the previous 
7910: 64 65 63 61 64 65 2c 20 65 6e 63 6f 75 6e 74 65  decade, encounte
7920: 72 65 64 20 62 75 67 73 0a 69 6e 20 65 61 63 68  red bugs.in each
7930: 20 6f 66 20 47 43 43 2c 20 43 6c 61 6e 67 2c 20   of GCC, Clang, 
7940: 61 6e 64 20 4d 53 56 43 2e 20 20 43 6f 6d 70 69  and MSVC.  Compi
7950: 6c 65 72 20 62 75 67 73 2c 20 77 68 69 6c 65 20  ler bugs, while 
7960: 72 61 72 65 2c 20 64 6f 20 68 61 70 70 65 6e 2c  rare, do happen,
7970: 0a 77 68 69 63 68 20 69 73 20 77 68 79 20 69 74  .which is why it
7980: 20 69 73 20 73 6f 20 69 6d 70 6f 72 74 61 6e 74   is so important
7990: 20 74 6f 20 74 65 73 74 20 74 68 65 20 63 6f 64   to test the cod
79a0: 65 20 69 6e 20 61 6e 20 61 73 2d 64 65 6c 69 76  e in an as-deliv
79b0: 65 72 65 64 0a 63 6f 6e 66 69 67 75 72 61 74 69  ered.configurati
79c0: 6f 6e 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  on...<tcl>hd_fra
79d0: 67 6d 65 6e 74 20 6d 75 74 61 74 69 6f 6e 74 65  gment mutationte
79e0: 73 74 73 20 7b 6d 75 74 61 74 69 6f 6e 20 74 65  sts {mutation te
79f0: 73 74 69 6e 67 7d 3c 2f 74 63 6c 3e 0a 3c 68 32  sting}</tcl>.<h2
7a00: 3e 4d 75 74 61 74 69 6f 6e 20 74 65 73 74 69 6e  >Mutation testin
7a10: 67 3c 2f 68 32 3e 0a 0a 3c 70 3e 55 73 69 6e 67  g</h2>..<p>Using
7a20: 20 67 63 6f 76 20 28 6f 72 20 73 69 6d 69 6c 61   gcov (or simila
7a30: 72 29 20 74 6f 20 73 68 6f 77 20 74 68 61 74 20  r) to show that 
7a40: 65 76 65 72 79 20 62 72 61 6e 63 68 20 69 6e 73  every branch ins
7a50: 74 72 75 63 74 69 6f 6e 20 69 73 20 74 61 6b 65  truction is take
7a60: 6e 0a 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20  n.at least once 
7a70: 69 6e 20 62 6f 74 68 20 64 69 72 65 63 74 69 6f  in both directio
7a80: 6e 73 20 69 73 20 67 6f 6f 64 20 6d 65 61 73 75  ns is good measu
7a90: 72 65 20 6f 66 20 74 65 73 74 20 73 75 69 74 65  re of test suite
7aa0: 20 71 75 61 6c 69 74 79 2e 0a 42 75 74 20 65 76   quality..But ev
7ab0: 65 6e 20 62 65 74 74 65 72 20 69 73 20 73 68 6f  en better is sho
7ac0: 77 69 6e 67 20 74 68 61 74 20 65 76 65 72 79 20  wing that every 
7ad0: 62 72 61 6e 63 68 20 69 6e 73 74 72 75 63 74 69  branch instructi
7ae0: 6f 6e 20 6d 61 6b 65 73 0a 61 20 64 69 66 66 65  on makes.a diffe
7af0: 72 65 6e 63 65 20 69 6e 20 74 68 65 20 6f 75 74  rence in the out
7b00: 70 75 74 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  put.  In other w
7b10: 6f 72 64 73 2c 20 77 65 20 77 61 6e 74 20 74 6f  ords, we want to
7b20: 20 73 68 6f 77 20 0a 6e 6f 74 20 6f 6e 6c 79 20   show .not only 
7b30: 74 68 61 74 20 65 76 65 72 79 20 62 72 61 6e 63  that every branc
7b40: 68 20 69 6e 73 74 72 75 63 74 69 6f 6e 20 62 6f  h instruction bo
7b50: 74 68 20 6a 75 6d 70 73 20 61 6e 64 20 66 61 6c  th jumps and fal
7b60: 6c 73 20 74 68 72 6f 75 67 68 20 62 75 74 20 61  ls through but a
7b70: 6c 73 6f 0a 74 68 61 74 20 65 76 65 72 79 20 62  lso.that every b
7b80: 72 61 6e 63 68 20 69 73 20 64 6f 69 6e 67 20 75  ranch is doing u
7b90: 73 65 66 75 6c 20 77 6f 72 6b 20 61 6e 64 20 74  seful work and t
7ba0: 68 61 74 20 74 68 65 20 74 65 73 74 20 73 75 69  hat the test sui
7bb0: 74 65 20 69 73 20 61 62 6c 65 0a 74 6f 20 64 65  te is able.to de
7bc0: 74 65 63 74 20 61 6e 64 20 76 65 72 69 66 79 20  tect and verify 
7bd0: 74 68 61 74 20 77 6f 72 6b 2e 20 20 57 68 65 6e  that work.  When
7be0: 20 61 20 62 72 61 6e 63 68 20 69 73 20 66 6f 75   a branch is fou
7bf0: 6e 64 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nd that does not
7c00: 0a 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e  .make a differen
7c10: 63 65 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74  ce in the output
7c20: 2c 20 74 68 61 74 20 73 75 67 67 65 73 74 73 20  , that suggests 
7c30: 74 68 61 74 20 74 68 65 20 63 6f 64 65 20 61 73  that the code as
7c40: 73 6f 63 69 61 74 65 64 20 0a 74 68 65 20 62 72  sociated .the br
7c50: 61 6e 63 68 20 63 61 6e 20 62 65 20 72 65 6d 6f  anch can be remo
7c60: 76 65 64 20 28 72 65 64 75 63 69 6e 67 20 74 68  ved (reducing th
7c70: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 69  e size of the li
7c80: 62 72 61 72 79 20 61 6e 64 20 70 65 72 68 61 70  brary and perhap
7c90: 73 0a 6d 61 6b 69 6e 67 20 69 74 20 72 75 6e 20  s.making it run 
7ca0: 66 61 73 74 65 72 29 20 6f 72 20 74 68 61 74 20  faster) or that 
7cb0: 74 68 65 20 74 65 73 74 20 73 75 69 74 65 20 69  the test suite i
7cc0: 73 20 69 6e 61 64 65 71 75 61 74 65 6c 79 20 74  s inadequately t
7cd0: 65 73 74 69 6e 67 20 74 68 65 0a 66 65 61 74 75  esting the.featu
7ce0: 72 65 20 74 68 61 74 20 74 68 65 20 62 72 61 6e  re that the bran
7cf0: 63 68 20 69 6d 70 6c 65 6d 65 6e 74 73 2e 0a 0a  ch implements...
7d00: 3c 70 3e 53 51 4c 69 74 65 20 73 74 72 69 76 65  <p>SQLite strive
7d10: 73 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  s to verify that
7d20: 20 65 76 65 72 79 20 62 72 61 6e 63 68 20 69 6e   every branch in
7d30: 73 74 72 75 63 74 69 6f 6e 20 6d 61 6b 65 73 20  struction makes 
7d40: 61 20 64 69 66 66 65 72 65 6e 63 65 0a 75 73 69  a difference.usi
7d50: 6e 67 20 5b 68 74 74 70 73 3a 2f 2f 65 6e 2e 77  ng [https://en.w
7d60: 69 6b 69 70 65 64 69 61 2e 6f 72 67 2f 77 69 6b  ikipedia.org/wik
7d70: 69 2f 4d 75 74 61 74 69 6f 6e 5f 74 65 73 74 69  i/Mutation_testi
7d80: 6e 67 7c 6d 75 74 61 74 69 6f 6e 20 74 65 73 74  ng|mutation test
7d90: 69 6e 67 5d 2e 0a 5b 6d 75 74 61 74 69 6f 6e 20  ing]..[mutation 
7da0: 74 65 73 74 20 73 63 72 69 70 74 7c 41 20 73 63  test script|A sc
7db0: 72 69 70 74 5d 0a 66 69 72 73 74 20 63 6f 6d 70  ript].first comp
7dc0: 69 6c 65 73 20 74 68 65 20 53 51 4c 69 74 65 20  iles the SQLite 
7dd0: 73 6f 75 72 63 65 20 63 6f 64 65 20 69 6e 74 6f  source code into
7de0: 20 61 73 73 65 6d 62 6c 79 20 6c 61 6e 67 75 61   assembly langua
7df0: 67 65 0a 28 75 73 69 6e 67 2c 20 66 6f 72 20 65  ge.(using, for e
7e00: 78 61 6d 70 6c 65 2c 20 74 68 65 20 2d 53 20 6f  xample, the -S o
7e10: 70 74 69 6f 6e 20 74 6f 20 67 63 63 29 2e 20 20  ption to gcc).  
7e20: 54 68 65 6e 20 74 68 65 20 73 63 72 69 70 74 20  Then the script 
7e30: 73 74 65 70 73 20 74 68 72 6f 75 67 68 0a 74 68  steps through.th
7e40: 65 20 67 65 6e 65 72 61 74 65 64 20 61 73 73 65  e generated asse
7e50: 6d 62 6c 79 20 6c 61 6e 67 75 61 67 65 20 61 6e  mbly language an
7e60: 64 2c 20 6f 6e 65 20 62 79 20 6f 6e 65 2c 20 63  d, one by one, c
7e70: 68 61 6e 67 65 73 20 65 61 63 68 20 62 72 61 6e  hanges each bran
7e80: 63 68 20 0a 69 6e 73 74 72 75 63 74 69 6f 6e 20  ch .instruction 
7e90: 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e 20 75  into either an u
7ea0: 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 20 6a 75 6d  nconditional jum
7eb0: 70 20 6f 72 20 61 20 6e 6f 2d 6f 70 2c 20 63 6f  p or a no-op, co
7ec0: 6d 70 69 6c 65 73 20 74 68 65 20 0a 72 65 73 75  mpiles the .resu
7ed0: 6c 74 2c 20 61 6e 64 20 76 65 72 69 66 69 65 73  lt, and verifies
7ee0: 20 74 68 61 74 20 74 68 65 20 74 65 73 74 20 73   that the test s
7ef0: 75 69 74 65 20 63 61 74 63 68 65 73 20 74 68 65  uite catches the
7f00: 20 6d 75 74 61 74 69 6f 6e 2e 0a 0a 3c 70 3e 0a   mutation...<p>.
7f10: 55 6e 66 6f 72 74 75 6e 61 74 65 6c 79 2c 20 53  Unfortunately, S
7f20: 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 6d  QLite contains m
7f30: 61 6e 79 20 62 72 61 6e 63 68 20 69 6e 73 74 72  any branch instr
7f40: 75 63 74 69 6f 6e 73 20 74 68 61 74 0a 68 65 6c  uctions that.hel
7f50: 70 20 74 68 65 20 63 6f 64 65 20 72 75 6e 20 66  p the code run f
7f60: 61 73 74 65 72 20 77 69 74 68 6f 75 74 20 63 68  aster without ch
7f70: 61 6e 67 69 6e 67 20 74 68 65 20 6f 75 74 70 75  anging the outpu
7f80: 74 2e 0a 53 75 63 68 20 62 72 61 6e 63 68 65 73  t..Such branches
7f90: 20 67 65 6e 65 72 61 74 65 20 66 61 6c 73 65 2d   generate false-
7fa0: 70 6f 73 69 74 69 76 65 73 20 64 75 72 69 6e 67  positives during
7fb0: 20 6d 75 74 61 74 69 6f 6e 20 74 65 73 74 69 6e   mutation testin
7fc0: 67 2e 0a 41 73 20 61 6e 20 65 78 61 6d 70 6c 65  g..As an example
7fd0: 2c 20 63 6f 6e 73 69 64 65 72 20 74 68 65 20 66  , consider the f
7fe0: 6f 6c 6c 6f 77 69 6e 67 20 0a 5b 68 74 74 70 73  ollowing .[https
7ff0: 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72  ://www.sqlite.or
8000: 67 2f 73 72 63 2f 61 72 74 69 66 61 63 74 2f 35  g/src/artifact/5
8010: 35 62 35 66 62 34 37 34 3f 6c 6e 3d 35 35 2d 36  5b5fb474?ln=55-6
8020: 32 20 7c 20 68 61 73 68 20 66 75 6e 63 74 69 6f  2 | hash functio
8030: 6e 5d 0a 75 73 65 64 20 74 6f 20 61 63 63 65 6c  n].used to accel
8040: 65 72 61 74 65 20 74 61 62 6c 65 2d 6e 61 6d 65  erate table-name
8050: 20 6c 6f 6f 6b 75 70 3a 0a 0a 3c 63 6f 64 65 62   lookup:..<codeb
8060: 6c 6f 63 6b 3e 0a 35 35 20 20 73 74 61 74 69 63  lock>.55  static
8070: 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 74   unsigned int st
8080: 72 48 61 73 68 28 63 6f 6e 73 74 20 63 68 61 72  rHash(const char
8090: 20 2a 7a 29 7b 0a 35 36 20 20 20 20 75 6e 73 69   *z){.56    unsi
80a0: 67 6e 65 64 20 69 6e 74 20 68 20 3d 20 30 3b 0a  gned int h = 0;.
80b0: 35 37 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  57    unsigned c
80c0: 68 61 72 20 63 3b 0a 35 38 20 20 20 20 77 68 69  har c;.58    whi
80d0: 6c 65 28 20 28 63 20 3d 20 28 75 6e 73 69 67 6e  le( (c = (unsign
80e0: 65 64 20 63 68 61 72 29 2a 7a 2b 2b 29 21 3d 30  ed char)*z++)!=0
80f0: 20 29 7b 20 20 20 20 20 2f 2a 4f 50 54 49 4d 49   ){     /*OPTIMI
8100: 5a 41 54 49 4f 4e 2d 49 46 2d 54 52 55 45 2a 2f  ZATION-IF-TRUE*/
8110: 0a 35 39 20 20 20 20 20 20 68 20 3d 20 28 68 26  .59      h = (h&
8120: 6c 74 3b 26 6c 74 3b 33 29 20 26 23 39 34 3b 20  lt;&lt;3) &#94; 
8130: 68 20 26 23 39 34 3b 20 73 71 6c 69 74 65 33 55  h &#94; sqlite3U
8140: 70 70 65 72 54 6f 4c 6f 77 65 72 26 23 39 31 3b  pperToLower&#91;
8150: 63 26 23 39 33 3b 3b 0a 36 30 20 20 20 20 7d 0a  c&#93;;.60    }.
8160: 36 31 20 20 20 20 72 65 74 75 72 6e 20 68 3b 0a  61    return h;.
8170: 36 32 20 20 7d 0a 3c 2f 63 6f 64 65 62 6c 6f 63  62  }.</codebloc
8180: 6b 3e 0a 0a 3c 70 3e 0a 49 66 20 74 68 65 20 62  k>..<p>.If the b
8190: 72 61 6e 63 68 20 69 6e 73 74 72 75 63 74 69 6f  ranch instructio
81a0: 6e 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  n that implement
81b0: 73 20 74 68 65 20 22 63 21 3d 30 22 20 74 65 73  s the "c!=0" tes
81c0: 74 20 6f 6e 20 6c 69 6e 65 20 35 38 0a 69 73 20  t on line 58.is 
81d0: 63 68 61 6e 67 65 64 20 69 6e 74 6f 20 61 20 6e  changed into a n
81e0: 6f 2d 6f 70 2c 20 74 68 65 6e 20 74 68 65 20 77  o-op, then the w
81f0: 68 69 6c 65 2d 6c 6f 6f 70 20 77 69 6c 6c 20 6c  hile-loop will l
8200: 6f 6f 70 20 66 6f 72 65 76 65 72 20 61 6e 64 20  oop forever and 
8210: 74 68 65 0a 74 65 73 74 20 73 75 69 74 65 20 77  the.test suite w
8220: 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 20  ill fail with a 
8230: 74 69 6d 65 2d 6f 75 74 2e 20 20 42 75 74 20 69  time-out.  But i
8240: 66 20 74 68 61 74 20 62 72 61 6e 63 68 20 69 73  f that branch is
8250: 20 63 68 61 6e 67 65 64 0a 69 6e 74 6f 20 61 6e   changed.into an
8260: 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 20 6a   unconditional j
8270: 75 6d 70 2c 20 74 68 65 6e 20 74 68 65 20 68 61  ump, then the ha
8280: 73 68 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  sh function will
8290: 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 30   always return 0
82a0: 2e 0a 54 68 65 20 70 72 6f 62 6c 65 6d 20 69 73  ..The problem is
82b0: 20 74 68 61 74 20 30 20 69 73 20 61 20 76 61 6c   that 0 is a val
82c0: 69 64 20 68 61 73 68 2e 20 20 41 20 68 61 73 68  id hash.  A hash
82d0: 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 61   function that a
82e0: 6c 77 61 79 73 0a 72 65 74 75 72 6e 73 20 30 20  lways.returns 0 
82f0: 73 74 69 6c 6c 20 77 6f 72 6b 73 20 69 6e 20 74  still works in t
8300: 68 65 20 73 65 6e 73 65 20 74 68 61 74 20 53 51  he sense that SQ
8310: 4c 69 74 65 20 73 74 69 6c 6c 20 61 6c 77 61 79  Lite still alway
8320: 73 20 67 65 74 73 20 74 68 65 20 63 6f 72 72 65  s gets the corre
8330: 63 74 0a 61 6e 73 77 65 72 2e 20 20 54 68 65 20  ct.answer.  The 
8340: 74 61 62 6c 65 2d 6e 61 6d 65 20 68 61 73 68 20  table-name hash 
8350: 74 61 62 6c 65 20 64 65 67 65 6e 65 72 61 74 65  table degenerate
8360: 73 20 69 6e 74 6f 20 61 20 6c 69 6e 6b 65 64 2d  s into a linked-
8370: 6c 69 73 74 0a 61 6e 64 20 73 6f 20 74 68 65 20  list.and so the 
8380: 74 61 62 6c 65 2d 6e 61 6d 65 20 6c 6f 6f 6b 75  table-name looku
8390: 70 73 20 74 68 61 74 20 6f 63 63 75 72 20 77 68  ps that occur wh
83a0: 69 6c 65 20 70 61 72 73 69 6e 67 20 53 51 4c 20  ile parsing SQL 
83b0: 73 74 61 74 65 6d 65 6e 74 73 20 0a 6d 69 67 68  statements .migh
83c0: 74 20 62 65 20 61 20 6c 69 74 74 6c 65 20 73 6c  t be a little sl
83d0: 6f 77 65 72 2c 20 62 75 74 20 74 68 65 20 65 6e  ower, but the en
83e0: 64 20 72 65 73 75 6c 74 20 77 69 6c 6c 20 62 65  d result will be
83f0: 20 74 68 65 20 73 61 6d 65 2e 0a 0a 3c 70 3e 0a   the same...<p>.
8400: 54 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 74  To work around t
8410: 68 69 73 20 70 72 6f 62 6c 65 6d 2c 20 63 6f 6d  his problem, com
8420: 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72  ments of the for
8430: 6d 0a 22 3c 63 6f 64 65 3e 2f 2a 4f 50 54 49 4d  m."<code>/*OPTIM
8440: 49 5a 41 54 49 4f 4e 2d 49 46 2d 54 52 55 45 2a  IZATION-IF-TRUE*
8450: 2f 3c 2f 63 6f 64 65 3e 22 20 61 6e 64 0a 22 3c  /</code>" and."<
8460: 63 6f 64 65 3e 2f 2a 4f 50 54 49 4d 49 5a 41 54  code>/*OPTIMIZAT
8470: 49 4f 4e 2d 49 46 2d 46 41 4c 53 45 2a 2f 3c 2f  ION-IF-FALSE*/</
8480: 63 6f 64 65 3e 22 20 61 72 65 20 69 6e 73 65 72  code>" are inser
8490: 74 65 64 20 69 6e 74 6f 20 74 68 65 20 53 51 4c  ted into the SQL
84a0: 69 74 65 0a 73 6f 75 72 63 65 20 63 6f 64 65 20  ite.source code 
84b0: 74 6f 20 74 65 6c 6c 20 74 68 65 20 6d 75 74 61  to tell the muta
84c0: 74 69 6f 6e 20 74 65 73 74 69 6e 67 20 73 63 72  tion testing scr
84d0: 69 70 74 20 74 6f 20 69 67 6e 6f 72 65 20 73 6f  ipt to ignore so
84e0: 6d 65 20 62 72 61 6e 63 68 0a 69 6e 73 74 72 75  me branch.instru
84f0: 63 74 69 6f 6e 73 2e 0a 0a 3c 74 63 6c 3e 68 64  ctions...<tcl>hd
8500: 5f 66 72 61 67 6d 65 6e 74 20 74 68 6f 75 67 68  _fragment though
8510: 74 73 31 3c 2f 74 63 6c 3e 0a 3c 68 32 3e 45 78  ts1</tcl>.<h2>Ex
8520: 70 65 72 69 65 6e 63 65 20 77 69 74 68 20 66 75  perience with fu
8530: 6c 6c 20 74 65 73 74 20 63 6f 76 65 72 61 67 65  ll test coverage
8540: 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65 20 64 65  </h2>..<p>The de
8550: 76 65 6c 6f 70 65 72 73 20 6f 66 20 53 51 4c 69  velopers of SQLi
8560: 74 65 20 68 61 76 65 20 66 6f 75 6e 64 20 74 68  te have found th
8570: 61 74 20 66 75 6c 6c 20 63 6f 76 65 72 61 67 65  at full coverage
8580: 20 74 65 73 74 69 6e 67 20 69 73 20 61 6e 0a 65   testing is an.e
8590: 78 74 72 65 6d 65 6c 79 20 65 66 66 65 63 74 69  xtremely effecti
85a0: 76 65 20 6d 65 74 68 6f 64 20 66 6f 72 20 6c 6f  ve method for lo
85b0: 63 61 74 69 6e 67 20 61 6e 64 20 70 72 65 76 65  cating and preve
85c0: 6e 74 69 6e 67 20 62 75 67 73 2e 0a 42 65 63 61  nting bugs..Beca
85d0: 75 73 65 20 65 76 65 72 79 20 73 69 6e 67 6c 65  use every single
85e0: 20 62 72 61 6e 63 68 0a 69 6e 73 74 72 75 63 74   branch.instruct
85f0: 69 6f 6e 20 69 6e 20 53 51 4c 69 74 65 20 63 6f  ion in SQLite co
8600: 72 65 20 63 6f 64 65 20 69 73 20 63 6f 76 65 72  re code is cover
8610: 65 64 20 62 79 20 74 65 73 74 20 63 61 73 65 73  ed by test cases
8620: 2c 20 74 68 65 20 64 65 76 65 6c 6f 70 65 72 73  , the developers
8630: 0a 63 61 6e 20 62 65 20 63 6f 6e 66 69 64 65 6e  .can be confiden
8640: 74 20 74 68 61 74 20 63 68 61 6e 67 65 73 20 6d  t that changes m
8650: 61 64 65 20 69 6e 20 6f 6e 65 20 70 61 72 74 20  ade in one part 
8660: 6f 66 20 74 68 65 20 63 6f 64 65 0a 64 6f 20 6e  of the code.do n
8670: 6f 74 20 68 61 76 65 20 75 6e 69 6e 74 65 6e 64  ot have unintend
8680: 65 64 20 63 6f 6e 73 65 71 75 65 6e 63 65 73 20  ed consequences 
8690: 69 6e 20 6f 74 68 65 72 20 70 61 72 74 73 20 6f  in other parts o
86a0: 66 20 74 68 65 20 63 6f 64 65 2e 0a 54 68 65 20  f the code..The 
86b0: 6d 61 6e 79 20 6e 65 77 20 66 65 61 74 75 72 65  many new feature
86c0: 73 20 61 6e 64 20 70 65 72 66 6f 72 6d 61 6e 63  s and performanc
86d0: 65 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 20 74  e improvements t
86e0: 68 61 74 20 68 61 76 65 20 62 65 65 6e 0a 61 64  hat have been.ad
86f0: 64 65 64 20 74 6f 20 53 51 4c 69 74 65 20 69 6e  ded to SQLite in
8700: 20 72 65 63 65 6e 74 20 79 65 61 72 73 20 77 6f   recent years wo
8710: 75 6c 64 20 6e 6f 74 20 68 61 76 65 20 62 65 65  uld not have bee
8720: 6e 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  n possible witho
8730: 75 74 0a 74 68 65 20 61 76 61 69 6c 61 62 69 6c  ut.the availabil
8740: 69 74 79 20 66 75 6c 6c 2d 63 6f 76 65 72 61 67  ity full-coverag
8750: 65 20 74 65 73 74 69 6e 67 2e 3c 2f 70 3e 0a 0a  e testing.</p>..
8760: 3c 70 3e 4d 61 69 6e 74 61 69 6e 69 6e 67 20 31  <p>Maintaining 1
8770: 30 30 25 20 4d 43 2f 44 43 20 69 73 20 6c 61 62  00% MC/DC is lab
8780: 6f 72 69 6f 75 73 20 61 6e 64 20 74 69 6d 65 2d  orious and time-
8790: 63 6f 6e 73 75 6d 69 6e 67 2e 0a 54 68 65 20 6c  consuming..The l
87a0: 65 76 65 6c 20 6f 66 20 65 66 66 6f 72 74 20 6e  evel of effort n
87b0: 65 65 64 65 64 20 74 6f 20 6d 61 69 6e 74 61 69  eeded to maintai
87c0: 6e 20 66 75 6c 6c 2d 63 6f 76 65 72 61 67 65 20  n full-coverage 
87d0: 74 65 73 74 69 6e 67 0a 69 73 20 70 72 6f 62 61  testing.is proba
87e0: 62 6c 79 20 6e 6f 74 20 63 6f 73 74 20 65 66 66  bly not cost eff
87f0: 65 63 74 69 76 65 20 66 6f 72 20 61 20 74 79 70  ective for a typ
8800: 69 63 61 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e  ical application
8810: 2e 0a 48 6f 77 65 76 65 72 2c 20 77 65 20 74 68  ..However, we th
8820: 69 6e 6b 20 74 68 61 74 20 66 75 6c 6c 2d 63 6f  ink that full-co
8830: 76 65 72 61 67 65 20 74 65 73 74 69 6e 67 20 69  verage testing i
8840: 73 20 6a 75 73 74 69 66 69 65 64 20 66 6f 72 20  s justified for 
8850: 61 0a 5b 6d 6f 73 74 20 77 69 64 65 6c 79 20 64  a.[most widely d
8860: 65 70 6c 6f 79 65 64 7c 76 65 72 79 20 77 69 64  eployed|very wid
8870: 65 6c 79 20 64 65 70 6c 6f 79 65 64 5d 20 69 6e  ely deployed] in
8880: 66 72 61 73 74 72 75 63 74 75 72 65 20 6c 69 62  frastructure lib
8890: 72 61 72 79 0a 6c 69 6b 65 20 53 51 4c 69 74 65  rary.like SQLite
88a0: 2c 20 61 6e 64 20 65 73 70 65 63 69 61 6c 6c 79  , and especially
88b0: 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
88c0: 6c 69 62 72 61 72 79 20 77 68 69 63 68 20 62 79  library which by
88d0: 20 69 74 73 20 76 65 72 79 0a 6e 61 74 75 72 65   its very.nature
88e0: 20 22 72 65 6d 65 6d 62 65 72 73 22 20 70 61 73   "remembers" pas
88f0: 74 20 6d 69 73 74 61 6b 65 73 2e 0a 0a 0a 3c 74  t mistakes....<t
8900: 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 64  cl>hd_fragment d
8910: 79 6e 61 6d 69 63 61 6e 61 6c 79 73 69 73 3c 2f  ynamicanalysis</
8920: 74 63 6c 3e 0a 3c 68 31 3e 44 79 6e 61 6d 69 63  tcl>.<h1>Dynamic
8930: 20 41 6e 61 6c 79 73 69 73 3c 2f 68 31 3e 0a 0a   Analysis</h1>..
8940: 3c 70 3e 44 79 6e 61 6d 69 63 20 61 6e 61 6c 79  <p>Dynamic analy
8950: 73 69 73 20 72 65 66 65 72 73 20 74 6f 20 69 6e  sis refers to in
8960: 74 65 72 6e 61 6c 20 61 6e 64 20 65 78 74 65 72  ternal and exter
8970: 6e 61 6c 20 63 68 65 63 6b 73 20 6f 6e 20 74 68  nal checks on th
8980: 65 0a 53 51 4c 69 74 65 20 63 6f 64 65 20 77 68  e.SQLite code wh
8990: 69 63 68 20 61 72 65 20 70 65 72 66 6f 72 6d 65  ich are performe
89a0: 64 20 77 68 69 6c 65 20 74 68 65 20 63 6f 64 65  d while the code
89b0: 20 69 73 20 6c 69 76 65 20 61 6e 64 20 72 75 6e   is live and run
89c0: 6e 69 6e 67 2e 0a 44 79 6e 61 6d 69 63 20 61 6e  ning..Dynamic an
89d0: 61 6c 79 73 69 73 20 68 61 73 20 70 72 6f 76 65  alysis has prove
89e0: 6e 20 74 6f 20 62 65 20 61 20 67 72 65 61 74 20  n to be a great 
89f0: 68 65 6c 70 20 69 6e 20 6d 61 69 6e 74 61 69 6e  help in maintain
8a00: 69 6e 67 20 74 68 65 0a 71 75 61 6c 69 74 79 20  ing the.quality 
8a10: 6f 66 20 53 51 4c 69 74 65 2e 3c 2f 70 3e 0a 0a  of SQLite.</p>..
8a20: 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
8a30: 20 61 73 73 65 72 74 73 3c 2f 74 63 6c 3e 0a 3c   asserts</tcl>.<
8a40: 68 32 3e 41 73 73 65 72 74 3c 2f 68 32 3e 0a 0a  h2>Assert</h2>..
8a50: 3c 70 3e 54 68 65 20 53 51 4c 69 74 65 20 63 6f  <p>The SQLite co
8a60: 72 65 20 63 6f 6e 74 61 69 6e 73 20 3c 74 63 6c  re contains <tcl
8a70: 3e 4e 20 7b 24 73 74 61 74 28 6e 41 73 73 65 72  >N {$stat(nAsser
8a80: 74 29 7d 3c 2f 74 63 6c 3e 20 3c 74 74 3e 61 73  t)}</tcl> <tt>as
8a90: 73 65 72 74 28 29 3c 2f 74 74 3e 0a 73 74 61 74  sert()</tt>.stat
8aa0: 65 6d 65 6e 74 73 20 74 68 61 74 20 76 65 72 69  ements that veri
8ab0: 66 79 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 63  fy function prec
8ac0: 6f 6e 64 69 74 69 6f 6e 73 20 61 6e 64 20 70 6f  onditions and po
8ad0: 73 74 63 6f 6e 64 69 74 69 6f 6e 73 20 61 6e 64  stconditions and
8ae0: 0a 6c 6f 6f 70 20 69 6e 76 61 72 69 61 6e 74 73  .loop invariants
8af0: 2e 20 20 41 73 73 65 72 74 28 29 20 69 73 20 61  .  Assert() is a
8b00: 20 6d 61 63 72 6f 20 77 68 69 63 68 20 69 73 20   macro which is 
8b10: 61 20 73 74 61 6e 64 61 72 64 20 70 61 72 74 20  a standard part 
8b20: 6f 66 0a 41 4e 53 49 2d 43 2e 20 20 54 68 65 20  of.ANSI-C.  The 
8b30: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 62 6f  argument is a bo
8b40: 6f 6c 65 61 6e 20 76 61 6c 75 65 20 74 68 61 74  olean value that
8b50: 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 61   is assumed to a
8b60: 6c 77 61 79 73 20 62 65 0a 74 72 75 65 2e 20 20  lways be.true.  
8b70: 49 66 20 74 68 65 20 61 73 73 65 72 74 69 6f 6e  If the assertion
8b80: 20 69 73 20 66 61 6c 73 65 2c 20 74 68 65 20 70   is false, the p
8b90: 72 6f 67 72 61 6d 20 70 72 69 6e 74 73 20 61 6e  rogram prints an
8ba0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 61   error message.a
8bb0: 6e 64 20 68 61 6c 74 73 2e 3c 2f 70 3e 0a 0a 3c  nd halts.</p>..<
8bc0: 70 3e 41 73 73 65 72 74 28 29 20 6d 61 63 72 6f  p>Assert() macro
8bd0: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
8be0: 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68  y compiling with
8bf0: 20 74 68 65 20 4e 44 45 42 55 47 20 6d 61 63 72   the NDEBUG macr
8c00: 6f 20 64 65 66 69 6e 65 64 2e 0a 49 6e 20 6d 6f  o defined..In mo
8c10: 73 74 20 73 79 73 74 65 6d 73 2c 20 61 73 73 65  st systems, asse
8c20: 72 74 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  rts are enabled 
8c30: 62 79 20 64 65 66 61 75 6c 74 2e 20 20 42 75 74  by default.  But
8c40: 20 69 6e 20 53 51 4c 69 74 65 2c 20 74 68 65 0a   in SQLite, the.
8c50: 61 73 73 65 72 74 73 20 61 72 65 20 73 6f 20 6e  asserts are so n
8c60: 75 6d 65 72 6f 75 73 20 61 6e 64 20 61 72 65 20  umerous and are 
8c70: 69 6e 20 73 75 63 68 20 70 65 72 66 6f 72 6d 61  in such performa
8c80: 6e 63 65 20 63 72 69 74 69 63 61 6c 20 70 6c 61  nce critical pla
8c90: 63 65 73 2c 20 74 68 61 74 0a 74 68 65 20 64 61  ces, that.the da
8ca0: 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 72 75  tabase engine ru
8cb0: 6e 73 20 61 62 6f 75 74 20 74 68 72 65 65 20 74  ns about three t
8cc0: 69 6d 65 73 20 73 6c 6f 77 65 72 20 77 68 65 6e  imes slower when
8cd0: 20 61 73 73 65 72 74 73 20 61 72 65 20 65 6e 61   asserts are ena
8ce0: 62 6c 65 64 2e 0a 48 65 6e 63 65 2c 20 74 68 65  bled..Hence, the
8cf0: 20 64 65 66 61 75 6c 74 20 28 70 72 6f 64 75 63   default (produc
8d00: 74 69 6f 6e 29 20 62 75 69 6c 64 20 6f 66 20 53  tion) build of S
8d10: 51 4c 69 74 65 20 64 69 73 61 62 6c 65 73 20 61  QLite disables a
8d20: 73 73 65 72 74 73 2e 20 20 0a 41 73 73 65 72 74  sserts.  .Assert
8d30: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
8d40: 6f 6e 6c 79 20 65 6e 61 62 6c 65 64 20 77 68 65  only enabled whe
8d50: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
8d60: 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 53 51  iled with the.SQ
8d70: 4c 49 54 45 5f 44 45 42 55 47 20 70 72 65 70 72  LITE_DEBUG prepr
8d80: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65  ocessor macro de
8d90: 66 69 6e 65 64 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c  fined.</p>..<tcl
8da0: 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 76 61 6c  >hd_fragment val
8db0: 67 72 69 6e 64 3c 2f 74 63 6c 3e 0a 3c 68 32 3e  grind</tcl>.<h2>
8dc0: 56 61 6c 67 72 69 6e 64 3c 2f 68 32 3e 0a 0a 3c  Valgrind</h2>..<
8dd0: 70 3e 5b 68 74 74 70 3a 2f 2f 76 61 6c 67 72 69  p>[http://valgri
8de0: 6e 64 2e 6f 72 67 2f 20 7c 20 56 61 6c 67 72 69  nd.org/ | Valgri
8df0: 6e 64 5d 20 69 73 20 70 65 72 68 61 70 73 20 74  nd] is perhaps t
8e00: 68 65 20 6d 6f 73 74 20 61 6d 61 7a 69 6e 67 0a  he most amazing.
8e10: 61 6e 64 20 75 73 65 66 75 6c 20 64 65 76 65 6c  and useful devel
8e20: 6f 70 65 72 20 74 6f 6f 6c 20 69 6e 20 74 68 65  oper tool in the
8e30: 20 77 6f 72 6c 64 2e 20 20 56 61 6c 67 72 69 6e   world.  Valgrin
8e40: 64 20 69 73 20 61 20 73 69 6d 75 6c 61 74 6f 72  d is a simulator
8e50: 20 2d 20 69 74 20 73 69 6d 75 6c 61 74 65 73 0a   - it simulates.
8e60: 61 6e 20 78 38 36 20 72 75 6e 6e 69 6e 67 20 61  an x86 running a
8e70: 20 4c 69 6e 75 78 20 62 69 6e 61 72 79 2e 20 20   Linux binary.  
8e80: 28 50 6f 72 74 73 20 6f 66 20 56 61 6c 67 72 69  (Ports of Valgri
8e90: 6e 64 20 66 6f 72 20 70 6c 61 74 66 6f 72 6d 73  nd for platforms
8ea0: 20 6f 74 68 65 72 0a 74 68 61 6e 20 4c 69 6e 75   other.than Linu
8eb0: 78 20 61 72 65 20 69 6e 20 64 65 76 65 6c 6f 70  x are in develop
8ec0: 6d 65 6e 74 2c 20 62 75 74 20 61 73 20 6f 66 20  ment, but as of 
8ed0: 74 68 69 73 20 77 72 69 74 69 6e 67 2c 20 56 61  this writing, Va
8ee0: 6c 67 72 69 6e 64 20 6f 6e 6c 79 0a 77 6f 72 6b  lgrind only.work
8ef0: 73 20 72 65 6c 69 61 62 6c 79 20 6f 6e 20 4c 69  s reliably on Li
8f00: 6e 75 78 2c 20 77 68 69 63 68 20 69 6e 20 74 68  nux, which in th
8f10: 65 20 6f 70 69 6e 69 6f 6e 20 6f 66 20 74 68 65  e opinion of the
8f20: 20 53 51 4c 69 74 65 20 64 65 76 65 6c 6f 70 65   SQLite develope
8f30: 72 73 20 0a 6d 65 61 6e 73 20 74 68 61 74 20 4c  rs .means that L
8f40: 69 6e 75 78 20 73 68 6f 75 6c 64 20 62 65 20 74  inux should be t
8f50: 68 65 20 70 72 65 66 65 72 72 65 64 20 70 6c 61  he preferred pla
8f60: 74 66 6f 72 6d 20 66 6f 72 20 61 6c 6c 20 73 6f  tform for all so
8f70: 66 74 77 61 72 65 20 64 65 76 65 6c 6f 70 6d 65  ftware developme
8f80: 6e 74 2e 29 0a 41 73 20 56 61 6c 67 72 69 6e 64  nt.).As Valgrind
8f90: 20 72 75 6e 73 20 61 20 4c 69 6e 75 78 20 62 69   runs a Linux bi
8fa0: 6e 61 72 79 2c 20 69 74 20 6c 6f 6f 6b 73 20 66  nary, it looks f
8fb0: 6f 72 20 61 6c 6c 20 6b 69 6e 64 73 20 6f 66 20  or all kinds of 
8fc0: 69 6e 74 65 72 65 73 74 69 6e 67 0a 65 72 72 6f  interesting.erro
8fd0: 72 73 20 73 75 63 68 20 61 73 20 61 72 72 61 79  rs such as array
8fe0: 20 6f 76 65 72 72 75 6e 73 2c 20 72 65 61 64 69   overruns, readi
8ff0: 6e 67 20 66 72 6f 6d 20 75 6e 69 6e 69 74 69 61  ng from uninitia
9000: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 2c 0a 73 74  lized memory,.st
9010: 61 63 6b 20 6f 76 65 72 66 6c 6f 77 73 2c 20 6d  ack overflows, m
9020: 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 61 6e 64  emory leaks, and
9030: 20 73 6f 20 66 6f 72 74 68 2e 20 20 56 61 6c 67   so forth.  Valg
9040: 72 69 6e 64 20 66 69 6e 64 73 20 70 72 6f 62 6c  rind finds probl
9050: 65 6d 73 0a 74 68 61 74 20 63 61 6e 20 65 61 73  ems.that can eas
9060: 69 6c 79 20 73 6c 69 70 20 74 68 72 6f 75 67 68  ily slip through
9070: 20 61 6c 6c 20 6f 66 20 74 68 65 20 6f 74 68 65   all of the othe
9080: 72 20 74 65 73 74 73 20 72 75 6e 20 61 67 61 69  r tests run agai
9090: 6e 73 74 20 53 51 4c 69 74 65 2e 0a 41 6e 64 2c  nst SQLite..And,
90a0: 20 77 68 65 6e 20 56 61 6c 67 72 69 6e 64 20 64   when Valgrind d
90b0: 6f 65 73 20 66 69 6e 64 20 61 6e 20 65 72 72 6f  oes find an erro
90c0: 72 2c 20 69 74 20 63 61 6e 20 64 75 6d 70 20 74  r, it can dump t
90d0: 68 65 20 64 65 76 65 6c 6f 70 65 72 20 64 69 72  he developer dir
90e0: 65 63 74 6c 79 0a 69 6e 74 6f 20 61 20 73 79 6d  ectly.into a sym
90f0: 62 6f 6c 69 63 20 64 65 62 75 67 67 65 72 20 61  bolic debugger a
9100: 74 20 74 68 65 20 65 78 61 63 74 20 70 6f 69 6e  t the exact poin
9110: 74 20 77 68 65 72 65 20 74 68 65 20 65 72 72 6f  t where the erro
9120: 72 20 6f 63 63 75 72 2c 20 74 6f 0a 66 61 63 69  r occur, to.faci
9130: 6c 69 74 61 74 65 20 61 20 71 75 69 63 6b 20 66  litate a quick f
9140: 69 78 2e 3c 2f 70 3e 0a 0a 3c 70 3e 42 65 63 61  ix.</p>..<p>Beca
9150: 75 73 65 20 69 74 20 69 73 20 61 20 73 69 6d 75  use it is a simu
9160: 6c 61 74 6f 72 2c 20 72 75 6e 6e 69 6e 67 20 61  lator, running a
9170: 20 62 69 6e 61 72 79 20 69 6e 20 56 61 6c 67 72   binary in Valgr
9180: 69 6e 64 20 69 73 20 73 6c 6f 77 65 72 20 74 68  ind is slower th
9190: 61 6e 20 0a 72 75 6e 6e 69 6e 67 20 69 74 20 6f  an .running it o
91a0: 6e 20 6e 61 74 69 76 65 20 68 61 72 64 77 61 72  n native hardwar
91b0: 65 2e 20 20 28 54 6f 20 61 20 66 69 72 73 74 20  e.  (To a first 
91c0: 61 70 70 72 6f 78 69 6d 61 74 69 6f 6e 2c 20 61  approximation, a
91d0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 72 75  n application.ru
91e0: 6e 6e 69 6e 67 20 69 6e 20 56 61 6c 67 72 69 6e  nning in Valgrin
91f0: 64 20 6f 6e 20 61 20 77 6f 72 6b 73 74 61 74 69  d on a workstati
9200: 6f 6e 20 77 69 6c 6c 20 70 65 72 66 6f 72 6d 20  on will perform 
9210: 61 62 6f 75 74 20 74 68 65 20 73 61 6d 65 20 61  about the same a
9220: 73 20 69 74 0a 77 6f 75 6c 64 20 72 75 6e 6e 69  s it.would runni
9230: 6e 67 20 6e 61 74 69 76 65 6c 79 20 6f 6e 20 61  ng natively on a
9240: 20 73 6d 61 72 74 70 68 6f 6e 65 2e 29 20 20 53   smartphone.)  S
9250: 6f 20 69 74 20 69 73 20 69 6d 70 72 61 63 74 69  o it is impracti
9260: 63 61 6c 20 74 6f 20 72 75 6e 20 74 68 65 20 66  cal to run the f
9270: 75 6c 6c 0a 53 51 4c 69 74 65 20 74 65 73 74 20  ull.SQLite test 
9280: 73 75 69 74 65 20 74 68 72 6f 75 67 68 20 56 61  suite through Va
9290: 6c 67 72 69 6e 64 2e 20 20 48 6f 77 65 76 65 72  lgrind.  However
92a0: 2c 20 74 68 65 20 76 65 72 79 71 75 69 63 6b 20  , the veryquick 
92b0: 74 65 73 74 73 20 61 6e 64 0a 74 68 65 20 63 6f  tests and.the co
92c0: 76 65 72 61 67 65 20 6f 66 20 74 68 65 20 54 48  verage of the TH
92d0: 33 20 74 65 73 74 73 20 61 72 65 20 72 75 6e 20  3 tests are run 
92e0: 74 68 72 6f 75 67 68 20 56 61 6c 67 72 69 6e 64  through Valgrind
92f0: 20 70 72 69 6f 72 20 74 6f 20 65 76 65 72 79 0a   prior to every.
9300: 72 65 6c 65 61 73 65 2e 3c 2f 70 3e 0a 0a 3c 74  release.</p>..<t
9310: 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 6d  cl>hd_fragment m
9320: 65 6d 74 65 73 74 69 6e 67 3c 2f 74 63 6c 3e 0a  emtesting</tcl>.
9330: 3c 68 32 3e 4d 65 6d 73 79 73 32 3c 2f 68 32 3e  <h2>Memsys2</h2>
9340: 0a 0a 3c 70 3e 53 51 4c 69 74 65 20 63 6f 6e 74  ..<p>SQLite cont
9350: 61 69 6e 73 20 61 20 70 6c 75 67 67 61 62 6c 65  ains a pluggable
9360: 0a 5b 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  .[memory allocat
9370: 69 6f 6e 20 7c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ion | memory all
9380: 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
9390: 6d 5d 2e 0a 54 68 65 20 64 65 66 61 75 6c 74 20  m]..The default 
93a0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
93b0: 73 65 73 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  ses system mallo
93c0: 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 2e 20  c() and free(). 
93d0: 0a 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  .However, if SQL
93e0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
93f0: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4d 45 4d  with [SQLITE_MEM
9400: 44 45 42 55 47 5d 2c 20 61 6e 20 61 6c 74 65 72  DEBUG], an alter
9410: 6e 61 74 69 76 65 0a 6d 65 6d 6f 72 79 20 61 6c  native.memory al
9420: 6c 6f 63 61 74 69 6f 6e 20 77 72 61 70 70 65 72  location wrapper
9430: 20 28 5b 6d 65 6d 73 79 73 32 5d 29 0a 69 73 20   ([memsys2]).is 
9440: 69 6e 73 65 72 74 65 64 20 74 68 61 74 20 6c 6f  inserted that lo
9450: 6f 6b 73 20 66 6f 72 20 6d 65 6d 6f 72 79 20 61  oks for memory a
9460: 6c 6c 6f 63 61 74 69 6f 6e 0a 65 72 72 6f 72 73  llocation.errors
9470: 20 61 74 20 72 75 6e 2d 74 69 6d 65 2e 20 20 54   at run-time.  T
9480: 68 65 20 6d 65 6d 73 79 73 32 20 77 72 61 70 70  he memsys2 wrapp
9490: 65 72 20 63 68 65 63 6b 73 20 66 6f 72 20 6d 65  er checks for me
94a0: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 6f 66 0a 63  mory leaks, of.c
94b0: 6f 75 72 73 65 2c 20 62 75 74 20 61 6c 73 6f 20  ourse, but also 
94c0: 6c 6f 6f 6b 73 20 66 6f 72 20 62 75 66 66 65 72  looks for buffer
94d0: 20 6f 76 65 72 72 75 6e 73 2c 20 75 73 65 73 20   overruns, uses 
94e0: 6f 66 20 75 6e 69 6e 69 74 69 61 6c 69 7a 65 64  of uninitialized
94f0: 20 6d 65 6d 6f 72 79 2c 0a 61 6e 64 20 61 74 74   memory,.and att
9500: 65 6d 70 74 73 20 74 6f 20 75 73 65 20 6d 65 6d  empts to use mem
9510: 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
9520: 20 62 65 65 6e 20 66 72 65 65 64 2e 20 20 54 68   been freed.  Th
9530: 65 73 65 20 73 61 6d 65 20 63 68 65 63 6b 73 0a  ese same checks.
9540: 61 72 65 20 61 6c 73 6f 20 64 6f 6e 65 20 62 79  are also done by
9550: 20 76 61 6c 67 72 69 6e 64 20 28 61 6e 64 2c 20   valgrind (and, 
9560: 69 6e 64 65 65 64 2c 20 56 61 6c 67 72 69 6e 64  indeed, Valgrind
9570: 20 64 6f 65 73 20 74 68 65 6d 20 62 65 74 74 65   does them bette
9580: 72 29 0a 62 75 74 20 6d 65 6d 73 79 73 32 20 68  r).but memsys2 h
9590: 61 73 20 74 68 65 20 61 64 76 61 6e 74 61 67 65  as the advantage
95a0: 20 6f 66 20 62 65 69 6e 67 20 6d 75 63 68 20 66   of being much f
95b0: 61 73 74 65 72 20 74 68 61 6e 20 56 61 6c 67 72  aster than Valgr
95c0: 69 6e 64 2c 20 77 68 69 63 68 0a 6d 65 61 6e 73  ind, which.means
95d0: 20 74 68 65 20 63 68 65 63 6b 73 20 63 61 6e 20   the checks can 
95e0: 62 65 20 64 6f 6e 65 20 6d 6f 72 65 20 6f 66 74  be done more oft
95f0: 65 6e 20 61 6e 64 20 66 6f 72 20 6c 6f 6e 67 65  en and for longe
9600: 72 20 74 65 73 74 73 2e 3c 2f 70 3e 0a 0a 3c 74  r tests.</p>..<t
9610: 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 6d  cl>hd_fragment m
9620: 75 74 65 78 74 65 73 74 69 6e 67 3c 2f 74 63 6c  utextesting</tcl
9630: 3e 0a 3c 68 32 3e 4d 75 74 65 78 20 41 73 73 65  >.<h2>Mutex Asse
9640: 72 74 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 53 51 4c  rts</h2>..<p>SQL
9650: 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 70  ite contains a p
9660: 6c 75 67 67 61 62 6c 65 20 6d 75 74 65 78 20 73  luggable mutex s
9670: 75 62 73 79 73 74 65 6d 2e 20 20 44 65 70 65 6e  ubsystem.  Depen
9680: 64 69 6e 67 20 6f 6e 20 0a 63 6f 6d 70 69 6c 65  ding on .compile
9690: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 73 2c 20 74  -time options, t
96a0: 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
96b0: 20 73 79 73 74 65 6d 20 63 6f 6e 74 61 69 6e 73   system contains
96c0: 20 69 6e 74 65 72 66 61 63 65 73 0a 5b 73 71 6c   interfaces.[sql
96d0: 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
96e0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
96f0: 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d  mutex_notheld()]
9700: 20 74 68 61 74 20 64 65 74 65 63 74 0a 77 68 65   that detect.whe
9710: 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 20 70 61  ther or not a pa
9720: 72 74 69 63 75 6c 61 72 20 6d 75 74 65 78 20 69  rticular mutex i
9730: 73 20 68 65 6c 64 20 62 79 20 74 68 65 20 63 61  s held by the ca
9740: 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a 54 68  lling thread..Th
9750: 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
9760: 65 73 20 61 72 65 20 75 73 65 64 20 65 78 74 65  es are used exte
9770: 6e 73 69 76 65 6c 79 20 77 69 74 68 69 6e 20 61  nsively within a
9780: 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
9790: 74 73 0a 69 6e 20 53 51 4c 69 74 65 20 74 6f 20  ts.in SQLite to 
97a0: 76 65 72 69 66 79 20 6d 75 74 65 78 65 73 20 61  verify mutexes a
97b0: 72 65 20 68 65 6c 64 20 61 6e 64 20 72 65 6c 65  re held and rele
97c0: 61 73 65 64 20 61 74 20 61 6c 6c 20 74 68 65 20  ased at all the 
97d0: 72 69 67 68 74 0a 6d 6f 6d 65 6e 74 73 2c 20 69  right.moments, i
97e0: 6e 20 6f 72 64 65 72 20 74 6f 20 64 6f 75 62 6c  n order to doubl
97f0: 65 2d 63 68 65 63 6b 20 74 68 61 74 20 53 51 4c  e-check that SQL
9800: 69 74 65 20 64 6f 65 73 20 77 6f 72 6b 20 63 6f  ite does work co
9810: 72 72 65 63 74 6c 79 0a 69 6e 20 6d 75 6c 74 69  rrectly.in multi
9820: 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
9830: 61 74 69 6f 6e 73 2e 3c 2f 70 3e 0a 0a 3c 74 63  ations.</p>..<tc
9840: 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 6a 6f  l>hd_fragment jo
9850: 75 72 6e 61 6c 74 65 73 74 3c 2f 74 63 6c 3e 0a  urnaltest</tcl>.
9860: 3c 68 32 3e 4a 6f 75 72 6e 61 6c 20 54 65 73 74  <h2>Journal Test
9870: 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 4f 6e 65 20 6f  s</h2>..<p>One o
9880: 66 20 74 68 65 20 74 68 69 6e 67 73 20 74 68 61  f the things tha
9890: 74 20 53 51 4c 69 74 65 20 64 6f 65 73 20 74 6f  t SQLite does to
98a0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 72 61   ensure that tra
98b0: 6e 73 61 63 74 69 6f 6e 73 0a 61 72 65 20 61 74  nsactions.are at
98c0: 6f 6d 69 63 20 61 63 72 6f 73 73 20 73 79 73 74  omic across syst
98d0: 65 6d 20 63 72 61 73 68 65 73 20 61 6e 64 20 70  em crashes and p
98e0: 6f 77 65 72 20 66 61 69 6c 75 72 65 73 20 69 73  ower failures is
98f0: 20 74 6f 20 77 72 69 74 65 0a 61 6c 6c 20 63 68   to write.all ch
9900: 61 6e 67 65 73 20 69 6e 74 6f 20 74 68 65 20 72  anges into the r
9910: 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20  ollback journal 
9920: 66 69 6c 65 20 70 72 69 6f 72 20 74 6f 20 63 68  file prior to ch
9930: 61 6e 67 69 6e 67 20 74 68 65 0a 64 61 74 61 62  anging the.datab
9940: 61 73 65 2e 20 20 54 68 65 20 54 43 4c 20 74 65  ase.  The TCL te
9950: 73 74 20 68 61 72 6e 65 73 73 20 63 6f 6e 74 61  st harness conta
9960: 69 6e 73 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ins an alternati
9970: 76 65 0a 5b 4f 53 20 62 61 63 6b 65 6e 64 5d 20  ve.[OS backend] 
9980: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
9990: 68 61 74 20 68 65 6c 70 73 20 74 6f 0a 76 65 72  hat helps to.ver
99a0: 69 66 79 20 74 68 69 73 20 69 73 20 6f 63 63 75  ify this is occu
99b0: 72 72 69 6e 67 20 63 6f 72 72 65 63 74 6c 79 2e  rring correctly.
99c0: 20 20 54 68 65 20 22 6a 6f 75 72 6e 61 6c 2d 74    The "journal-t
99d0: 65 73 74 20 56 46 53 22 20 6d 6f 6e 69 74 6f 72  est VFS" monitor
99e0: 73 0a 61 6c 6c 20 64 69 73 6b 20 49 2f 4f 20 74  s.all disk I/O t
99f0: 72 61 66 66 69 63 20 62 65 74 77 65 65 6e 20 74  raffic between t
9a00: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9a10: 20 61 6e 64 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f   and rollback jo
9a20: 75 72 6e 61 6c 2c 0a 63 68 65 63 6b 69 6e 67 20  urnal,.checking 
9a30: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
9a40: 74 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69  t nothing is wri
9a50: 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 64 61  tten into the da
9a60: 74 61 62 61 73 65 0a 66 69 6c 65 20 77 68 69 63  tabase.file whic
9a70: 68 20 68 61 73 20 6e 6f 74 20 66 69 72 73 74 20  h has not first 
9a80: 62 65 65 6e 20 77 72 69 74 74 65 6e 20 61 6e 64  been written and
9a90: 20 73 79 6e 63 65 64 20 74 6f 20 74 68 65 20 72   synced to the r
9aa0: 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 2e  ollback journal.
9ab0: 0a 49 66 20 61 6e 79 20 64 69 73 63 72 65 70 61  .If any discrepa
9ac0: 6e 63 69 65 73 20 61 72 65 20 66 6f 75 6e 64 2c  ncies are found,
9ad0: 20 61 6e 20 61 73 73 65 72 74 69 6f 6e 20 66 61   an assertion fa
9ae0: 75 6c 74 20 69 73 20 72 61 69 73 65 64 2e 3c 2f  ult is raised.</
9af0: 70 3e 0a 0a 3c 70 3e 54 68 65 20 6a 6f 75 72 6e  p>..<p>The journ
9b00: 61 6c 20 74 65 73 74 73 20 61 72 65 20 61 6e 20  al tests are an 
9b10: 61 64 64 69 74 69 6f 6e 61 6c 20 64 6f 75 62 6c  additional doubl
9b20: 65 2d 63 68 65 63 6b 20 6f 76 65 72 20 61 6e 64  e-check over and
9b30: 20 61 62 6f 76 65 0a 74 68 65 20 63 72 61 73 68   above.the crash
9b40: 20 74 65 73 74 73 20 74 6f 20 6d 61 6b 65 20 73   tests to make s
9b50: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
9b60: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 77 69 6c  transactions wil
9b70: 6c 20 62 65 20 61 74 6f 6d 69 63 0a 61 63 72 6f  l be atomic.acro
9b80: 73 73 20 73 79 73 74 65 6d 20 63 72 61 73 68 65  ss system crashe
9b90: 73 20 61 6e 64 20 70 6f 77 65 72 20 66 61 69 6c  s and power fail
9ba0: 75 72 65 73 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e  ures.</p>..<tcl>
9bb0: 68 64 5f 66 72 61 67 6d 65 6e 74 20 69 6e 74 6f  hd_fragment into
9bc0: 76 65 72 66 6c 6f 77 3c 2f 74 63 6c 3e 0a 3c 68  verflow</tcl>.<h
9bd0: 32 3e 55 6e 64 65 66 69 6e 65 64 20 42 65 68 61  2>Undefined Beha
9be0: 76 69 6f 72 20 43 68 65 63 6b 73 3c 2f 68 32 3e  vior Checks</h2>
9bf0: 0a 0a 3c 70 3e 49 6e 20 74 68 65 20 43 20 70 72  ..<p>In the C pr
9c00: 6f 67 72 61 6d 6d 69 6e 67 20 6c 61 6e 67 75 61  ogramming langua
9c10: 67 65 2c 20 69 74 20 69 73 20 76 65 72 79 20 65  ge, it is very e
9c20: 61 73 79 20 74 6f 20 77 72 69 74 65 20 63 6f 64  asy to write cod
9c30: 65 20 74 68 61 74 0a 68 61 73 20 22 75 6e 64 65  e that.has "unde
9c40: 66 69 6e 65 64 22 20 6f 72 20 22 69 6d 70 6c 65  fined" or "imple
9c50: 6d 65 6e 74 61 74 69 6f 6e 20 64 65 66 69 6e 65  mentation define
9c60: 64 22 20 62 65 68 61 76 69 6f 72 2e 0a 54 68 61  d" behavior..Tha
9c70: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
9c80: 20 63 6f 64 65 20 6d 69 67 68 74 20 77 6f 72 6b   code might work
9c90: 20 64 75 72 69 6e 67 20 64 65 76 65 6c 6f 70 6d   during developm
9ca0: 65 6e 74 2c 20 62 75 74 20 74 68 65 6e 20 67 69  ent, but then gi
9cb0: 76 65 0a 61 20 64 69 66 66 65 72 65 6e 74 20 61  ve.a different a
9cc0: 6e 73 77 65 72 20 6f 6e 20 61 20 64 69 66 66 65  nswer on a diffe
9cd0: 72 65 6e 74 20 73 79 73 74 65 6d 2c 20 6f 72 20  rent system, or 
9ce0: 77 68 65 6e 20 72 65 63 6f 6d 70 69 6c 65 64 20  when recompiled 
9cf0: 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 0a  using different.
9d00: 63 6f 6d 70 69 6c 65 72 20 6f 70 74 69 6f 6e 73  compiler options
9d10: 2e 20 20 0a 45 78 61 6d 70 6c 65 73 20 6f 66 20  .  .Examples of 
9d20: 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 69 6d  undefined and im
9d30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2d 64 65 66  plementation-def
9d40: 69 6e 65 64 20 62 65 68 61 76 69 6f 72 20 69 6e  ined behavior in
9d50: 0a 41 4e 53 49 20 43 20 69 6e 63 6c 75 64 65 3a  .ANSI C include:
9d60: 0a 3c 75 6c 3e 0a 3c 6c 69 3e 53 69 67 6e 65 64  .<ul>.<li>Signed
9d70: 20 69 6e 74 65 67 65 72 20 6f 76 65 72 66 6c 6f   integer overflo
9d80: 77 2e 20 20 28 53 69 67 6e 65 64 20 69 6e 74 65  w.  (Signed inte
9d90: 67 65 72 20 6f 76 65 72 66 6c 6f 77 20 64 6f 65  ger overflow doe
9da0: 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 0a 6e 65 63  s <u>not</u>.nec
9db0: 65 73 73 61 72 69 6c 79 20 77 72 61 70 20 61 72  essarily wrap ar
9dc0: 6f 75 6e 64 2c 20 61 73 20 6d 6f 73 74 20 70 65  ound, as most pe
9dd0: 6f 70 6c 65 20 65 78 70 65 63 74 2e 29 0a 3c 6c  ople expect.).<l
9de0: 69 3e 53 68 69 66 74 69 6e 67 20 61 6e 20 4e 2d  i>Shifting an N-
9df0: 62 69 74 20 69 6e 74 65 67 65 72 20 62 79 20 6d  bit integer by m
9e00: 6f 72 65 20 74 68 61 6e 20 4e 20 62 69 74 73 2e  ore than N bits.
9e10: 0a 3c 6c 69 3e 53 68 69 66 74 69 6e 67 20 62 79  .<li>Shifting by
9e20: 20 61 20 6e 65 67 61 74 69 76 65 20 61 6d 6f 75   a negative amou
9e30: 6e 74 2e 0a 3c 6c 69 3e 53 68 69 66 74 69 6e 67  nt..<li>Shifting
9e40: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
9e50: 65 72 2e 0a 3c 6c 69 3e 55 73 69 6e 67 20 74 68  er..<li>Using th
9e60: 65 20 6d 65 6d 63 70 79 28 29 20 66 75 6e 63 74  e memcpy() funct
9e70: 69 6f 6e 20 6f 6e 20 6f 76 65 72 6c 61 70 70 69  ion on overlappi
9e80: 6e 67 20 62 75 66 66 65 72 73 2e 0a 3c 6c 69 3e  ng buffers..<li>
9e90: 54 68 65 20 6f 72 64 65 72 20 6f 66 20 65 76 61  The order of eva
9ea0: 6c 75 61 74 69 6f 6e 20 6f 66 20 66 75 6e 63 74  luation of funct
9eb0: 69 6f 6e 20 61 72 67 75 6d 65 6e 74 73 2e 0a 3c  ion arguments..<
9ec0: 6c 69 3e 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  li>Whether or no
9ed0: 74 20 22 63 68 61 72 22 20 76 61 72 69 61 62 6c  t "char" variabl
9ee0: 65 73 20 61 72 65 20 73 69 67 6e 65 64 20 6f 72  es are signed or
9ef0: 20 75 6e 73 69 67 6e 65 64 2e 0a 3c 6c 69 3e 41   unsigned..<li>A
9f00: 6e 64 20 73 6f 20 66 6f 72 74 68 2e 2e 2e 2e 0a  nd so forth.....
9f10: 3c 2f 75 6c 3e 0a 0a 3c 70 3e 53 69 6e 63 65 20  </ul>..<p>Since 
9f20: 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 69 6d  undefined and im
9f30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2d 64 65 66  plementation-def
9f40: 69 6e 65 64 20 62 65 68 61 76 69 6f 72 20 69 73  ined behavior is
9f50: 20 6e 6f 6e 2d 70 6f 72 74 61 62 6c 65 0a 61 6e   non-portable.an
9f60: 64 20 63 61 6e 20 65 61 73 69 6c 79 20 6c 65 61  d can easily lea
9f70: 64 20 74 6f 20 69 6e 63 6f 72 72 65 63 74 20 61  d to incorrect a
9f80: 6e 73 77 65 72 73 2c 20 53 51 4c 69 74 65 20 77  nswers, SQLite w
9f90: 6f 72 6b 73 20 76 65 72 79 20 68 61 72 64 20 74  orks very hard t
9fa0: 6f 20 61 76 6f 69 64 20 69 74 2e 0a 46 6f 72 20  o avoid it..For 
9fb0: 65 78 61 6d 70 6c 65 2c 0a 77 68 65 6e 20 61 64  example,.when ad
9fc0: 64 69 6e 67 20 74 77 6f 20 69 6e 74 65 67 65 72  ding two integer
9fd0: 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 74   column values t
9fe0: 6f 67 65 74 68 65 72 20 61 73 20 70 61 72 74 20  ogether as part 
9ff0: 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
a000: 65 6e 74 2c 0a 53 51 4c 69 74 65 20 64 6f 65 73  ent,.SQLite does
a010: 20 6e 6f 74 20 73 69 6d 70 6c 65 20 61 64 64 20   not simple add 
a020: 74 68 65 6d 20 74 6f 67 65 74 68 65 72 20 75 73  them together us
a030: 69 6e 67 20 74 68 65 20 43 2d 6c 61 6e 67 75 61  ing the C-langua
a040: 67 65 20 22 2b 22 20 6f 70 65 72 61 74 6f 72 2e  ge "+" operator.
a050: 0a 49 6e 73 74 65 61 64 2c 20 69 74 20 66 69 72  .Instead, it fir
a060: 73 74 20 63 68 65 63 6b 73 20 74 6f 20 6d 61 6b  st checks to mak
a070: 65 20 73 75 72 65 20 74 68 65 0a 61 64 64 69 74  e sure the.addit
a080: 69 6f 6e 20 77 69 6c 6c 20 6e 6f 74 20 6f 76 65  ion will not ove
a090: 72 66 6c 6f 77 2c 20 61 6e 64 20 69 66 20 69 74  rflow, and if it
a0a0: 20 77 69 6c 6c 2c 20 69 74 20 64 6f 65 73 20 74   will, it does t
a0b0: 68 65 20 61 64 64 69 74 69 6f 6e 20 75 73 69 6e  he addition usin
a0c0: 67 0a 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  g.floating point
a0d0: 20 69 6e 73 74 65 61 64 2e 0a 0a 3c 70 3e 54 6f   instead...<p>To
a0e0: 20 68 65 6c 70 20 65 6e 73 75 72 65 20 74 68 61   help ensure tha
a0f0: 74 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f  t SQLite does no
a100: 74 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 75 6e  t make use of un
a110: 64 65 66 69 6e 65 64 20 6f 72 0a 69 6d 70 6c 65  defined or.imple
a120: 6d 65 6e 74 61 74 69 6f 6e 20 64 65 66 69 6e 65  mentation define
a130: 64 20 62 65 68 61 76 69 6f 72 2c 20 74 68 65 20  d behavior, the 
a140: 74 65 73 74 20 73 75 69 74 65 73 20 61 72 65 20  test suites are 
a150: 72 65 72 75 6e 20 75 73 69 6e 67 0a 69 6e 73 74  rerun using.inst
a160: 72 75 6d 65 6e 74 65 64 20 62 75 69 6c 64 73 20  rumented builds 
a170: 74 68 61 74 20 74 72 79 20 74 6f 20 64 65 74 65  that try to dete
a180: 63 74 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  ct undefined beh
a190: 61 76 69 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d  avior.  For exam
a1a0: 70 6c 65 2c 0a 74 65 73 74 20 73 75 69 74 65 73  ple,.test suites
a1b0: 20 61 72 65 20 72 75 6e 20 75 73 69 6e 67 20 74   are run using t
a1c0: 68 65 20 22 2d 66 74 72 61 70 76 22 20 6f 70 74  he "-ftrapv" opt
a1d0: 69 6f 6e 20 6f 66 20 47 43 43 2e 20 20 41 6e 64  ion of GCC.  And
a1e0: 20 74 68 65 79 0a 61 72 65 20 72 75 6e 20 61 67   they.are run ag
a1f0: 61 69 6e 20 75 73 69 6e 67 20 74 68 65 20 22 2d  ain using the "-
a200: 66 73 61 6e 69 74 69 7a 65 3d 75 6e 64 65 66 69  fsanitize=undefi
a210: 6e 65 64 22 20 6f 70 74 69 6f 6e 20 6f 6e 20 43  ned" option on C
a220: 6c 61 6e 67 2e 20 20 41 6e 64 0a 61 67 61 69 6e  lang.  And.again
a230: 20 75 73 69 6e 67 20 74 68 65 20 22 2f 52 54 43   using the "/RTC
a240: 31 22 20 6f 70 74 69 6f 6e 20 69 6e 20 4d 53 56  1" option in MSV
a250: 43 2e 20 20 54 68 65 6e 20 74 68 65 20 74 65 73  C.  Then the tes
a260: 74 20 73 75 69 74 65 73 20 61 72 65 20 72 65 72  t suites are rer
a270: 75 6e 0a 75 73 69 6e 67 20 6f 70 74 69 6f 6e 73  un.using options
a280: 20 6c 69 6b 65 20 22 2d 66 75 6e 73 69 67 6e 65   like "-funsigne
a290: 64 2d 63 68 61 72 22 20 61 6e 64 20 22 2d 66 73  d-char" and "-fs
a2a0: 69 67 6e 65 64 2d 63 68 61 72 22 20 74 6f 20 6d  igned-char" to m
a2b0: 61 6b 65 20 73 75 72 65 0a 74 68 61 74 20 69 6d  ake sure.that im
a2c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 69 66  plementation dif
a2d0: 66 65 72 65 6e 63 65 73 20 64 6f 20 6e 6f 74 20  ferences do not 
a2e0: 6d 61 74 74 65 72 20 65 69 74 68 65 72 2e 20 20  matter either.  
a2f0: 54 65 73 74 73 20 61 72 65 20 74 68 65 6e 20 72  Tests are then r
a300: 65 70 65 61 74 65 64 0a 6f 6e 20 33 32 2d 62 69  epeated.on 32-bi
a310: 74 20 61 6e 64 20 36 34 2d 62 69 74 20 73 79 73  t and 64-bit sys
a320: 74 65 6d 73 20 61 6e 64 20 6f 6e 20 62 69 67 2d  tems and on big-
a330: 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
a340: 65 2d 65 6e 64 69 61 6e 20 73 79 73 74 65 6d 73  e-endian systems
a350: 2c 0a 75 73 69 6e 67 20 61 20 76 61 72 69 65 74  ,.using a variet
a360: 79 20 6f 66 20 43 50 55 20 61 72 63 68 69 74 65  y of CPU archite
a370: 63 74 75 72 65 73 2e 0a 46 75 72 74 68 65 72 6d  ctures..Furtherm
a380: 6f 72 65 2c 20 74 68 65 20 74 65 73 74 20 73 75  ore, the test su
a390: 69 74 65 73 20 61 72 65 20 61 75 67 6d 65 6e 74  ites are augment
a3a0: 65 64 20 77 69 74 68 20 6d 61 6e 79 20 74 65 73  ed with many tes
a3b0: 74 20 63 61 73 65 73 20 74 68 61 74 20 61 72 65  t cases that are
a3c0: 0a 64 65 6c 69 62 65 72 61 74 65 6c 79 20 64 65  .deliberately de
a3d0: 73 69 67 6e 65 64 20 74 6f 20 70 72 6f 76 6f 6b  signed to provok
a3e0: 65 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  e undefined beha
a3f0: 76 69 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70  vior.  For examp
a400: 6c 65 3a 0a 22 3c 62 3e 53 45 4c 45 43 54 20 2d  le:."<b>SELECT -
a410: 31 2a 28 2d 39 32 32 33 33 37 32 30 33 36 38 35  1*(-922337203685
a420: 34 37 37 35 38 30 38 29 3b 3c 2f 62 3e 22 2e 0a  4775808);</b>"..
a430: 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
a440: 74 20 64 69 73 6f 70 74 74 65 73 74 3c 2f 74 63  t disopttest</tc
a450: 6c 3e 0a 3c 68 31 3e 44 69 73 61 62 6c 65 64 20  l>.<h1>Disabled 
a460: 4f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 54 65 73  Optimization Tes
a470: 74 73 3c 2f 68 31 3e 0a 0a 3c 70 3e 54 68 65 20  ts</h1>..<p>The 
a480: 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f  [sqlite3_test_co
a490: 6e 74 72 6f 6c 5d 28 5b 53 51 4c 49 54 45 5f 54  ntrol]([SQLITE_T
a4a0: 45 53 54 43 54 52 4c 5f 4f 50 54 49 4d 49 5a 41  ESTCTRL_OPTIMIZA
a4b0: 54 49 4f 4e 53 5d 2c 20 2e 2e 2e 29 20 69 6e 74  TIONS], ...) int
a4c0: 65 72 66 61 63 65 0a 61 6c 6c 6f 77 73 20 73 65  erface.allows se
a4d0: 6c 65 63 74 65 64 20 53 51 4c 20 73 74 61 74 65  lected SQL state
a4e0: 6d 65 6e 74 20 6f 70 74 69 6d 69 7a 61 74 69 6f  ment optimizatio
a4f0: 6e 73 20 74 6f 20 62 65 20 64 69 73 61 62 6c 65  ns to be disable
a500: 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 2e 0a 53  d at run-time..S
a510: 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 61 6c 77  QLite should alw
a520: 61 79 73 20 67 65 6e 65 72 61 74 65 20 65 78 61  ays generate exa
a530: 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 6e  ctly the same an
a540: 73 77 65 72 20 77 69 74 68 20 6f 70 74 69 6d 69  swer with optimi
a550: 7a 61 74 69 6f 6e 73 0a 65 6e 61 62 6c 65 64 20  zations.enabled 
a560: 61 6e 64 20 77 69 74 68 20 6f 70 74 69 6d 69 7a  and with optimiz
a570: 61 74 69 6f 6e 73 20 64 69 73 61 62 6c 65 64 3b  ations disabled;
a580: 20 74 68 65 20 61 6e 73 77 65 72 20 73 69 6d 70   the answer simp
a590: 6c 79 20 61 72 72 69 76 65 73 20 71 75 69 63 6b  ly arrives quick
a5a0: 65 72 0a 77 69 74 68 20 74 68 65 20 6f 70 74 69  er.with the opti
a5b0: 6d 69 7a 61 74 69 6f 6e 73 20 74 75 72 6e 65 64  mizations turned
a5c0: 20 6f 6e 2e 20 20 53 6f 20 69 6e 20 61 20 70 72   on.  So in a pr
a5d0: 6f 64 75 63 74 69 6f 6e 20 65 6e 76 69 72 6f 6e  oduction environ
a5e0: 6d 65 6e 74 2c 20 6f 6e 65 20 61 6c 77 61 79 73  ment, one always
a5f0: 0a 6c 65 61 76 65 73 20 74 68 65 20 6f 70 74 69  .leaves the opti
a600: 6d 69 7a 61 74 69 6f 6e 73 20 74 75 72 6e 65 64  mizations turned
a610: 20 6f 6e 20 28 74 68 65 20 64 65 66 61 75 6c 74   on (the default
a620: 20 73 65 74 74 69 6e 67 29 2e 3c 2f 70 3e 0a 0a   setting).</p>..
a630: 3c 70 3e 4f 6e 65 20 76 65 72 69 66 69 63 61 74  <p>One verificat
a640: 69 6f 6e 20 74 65 63 68 6e 69 71 75 65 20 75 73  ion technique us
a650: 65 64 20 6f 6e 20 53 51 4c 69 74 65 20 69 73 20  ed on SQLite is 
a660: 74 6f 20 72 75 6e 20 61 6e 20 65 6e 74 69 72 65  to run an entire
a670: 20 74 65 73 74 20 73 75 69 74 65 0a 74 77 69 63   test suite.twic
a680: 65 2c 20 6f 6e 63 65 20 77 69 74 68 20 6f 70 74  e, once with opt
a690: 69 6d 69 7a 61 74 69 6f 6e 73 20 6c 65 66 74 20  imizations left 
a6a0: 6f 6e 20 61 6e 64 20 61 20 73 65 63 6f 6e 64 20  on and a second 
a6b0: 74 69 6d 65 20 77 69 74 68 20 6f 70 74 69 6d 69  time with optimi
a6c0: 7a 61 74 69 6f 6e 73 0a 74 75 72 6e 65 64 20 6f  zations.turned o
a6d0: 66 66 2c 20 61 6e 64 20 76 65 72 69 66 79 20 74  ff, and verify t
a6e0: 68 61 74 20 74 68 65 20 73 61 6d 65 20 6f 75 74  hat the same out
a6f0: 70 75 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20  put is obtained 
a700: 62 6f 74 68 20 74 69 6d 65 73 2e 20 20 54 68 69  both times.  Thi
a710: 73 0a 73 68 6f 77 73 20 74 68 61 74 20 74 68 65  s.shows that the
a720: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 64   optimizations d
a730: 6f 20 6e 6f 74 20 69 6e 74 72 6f 64 75 63 65 20  o not introduce 
a740: 65 72 72 6f 72 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e  errors.</p>..<p>
a750: 4e 6f 74 20 61 6c 6c 20 74 65 73 74 20 63 61 73  Not all test cas
a760: 65 73 20 63 61 6e 20 62 65 20 68 61 6e 64 6c 65  es can be handle
a770: 64 20 74 68 69 73 20 77 61 79 2e 20 20 53 6f 6d  d this way.  Som
a780: 65 20 74 65 73 74 20 63 61 73 65 73 20 63 68 65  e test cases che
a790: 63 6b 0a 74 6f 20 76 65 72 69 66 79 20 74 68 61  ck.to verify tha
a7a0: 74 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  t the optimizati
a7b0: 6f 6e 73 20 72 65 61 6c 6c 79 20 61 72 65 20 72  ons really are r
a7c0: 65 64 75 63 69 6e 67 20 74 68 65 20 61 6d 6f 75  educing the amou
a7d0: 6e 74 20 6f 66 0a 63 6f 6d 70 75 74 61 74 69 6f  nt of.computatio
a7e0: 6e 20 62 79 20 63 6f 75 6e 74 69 6e 67 20 74 68  n by counting th
a7f0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 73 6b  e number of disk
a800: 20 61 63 63 65 73 73 65 73 2c 20 73 6f 72 74 20   accesses, sort 
a810: 6f 70 65 72 61 74 69 6f 6e 73 2c 20 0a 66 75 6c  operations, .ful
a820: 6c 2d 73 63 61 6e 20 73 74 65 70 73 2c 20 6f 72  l-scan steps, or
a830: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 69 6e   other processin
a840: 67 20 73 74 65 70 73 20 74 68 61 74 20 6f 63 63  g steps that occ
a850: 75 72 20 64 75 72 69 6e 67 20 71 75 65 72 69 65  ur during querie
a860: 73 2e 0a 54 68 6f 73 65 20 74 65 73 74 20 63 61  s..Those test ca
a870: 73 65 73 20 77 69 6c 6c 20 61 70 70 65 61 72 20  ses will appear 
a880: 74 6f 20 66 61 69 6c 20 77 68 65 6e 20 6f 70 74  to fail when opt
a890: 69 6d 69 7a 61 74 69 6f 6e 73 20 61 72 65 20 64  imizations are d
a8a0: 69 73 61 62 6c 65 64 2e 0a 42 75 74 20 74 68 65  isabled..But the
a8b0: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 74 65 73   majority of tes
a8c0: 74 20 63 61 73 65 73 20 73 69 6d 70 6c 79 20 63  t cases simply c
a8d0: 68 65 63 6b 20 74 68 61 74 20 74 68 65 20 63 6f  heck that the co
a8e0: 72 72 65 63 74 20 61 6e 73 77 65 72 0a 77 61 73  rrect answer.was
a8f0: 20 6f 62 74 61 69 6e 65 64 2c 20 61 6e 64 20 61   obtained, and a
a900: 6c 6c 20 6f 66 20 74 68 6f 73 65 20 63 61 73 65  ll of those case
a910: 73 20 63 61 6e 20 62 65 20 72 75 6e 20 73 75 63  s can be run suc
a920: 63 65 73 73 66 75 6c 6c 79 20 77 69 74 68 20 61  cessfully with a
a930: 6e 64 0a 77 69 74 68 6f 75 74 20 74 68 65 20 6f  nd.without the o
a940: 70 74 69 6d 69 7a 61 74 69 6f 6e 73 2c 20 69 6e  ptimizations, in
a950: 20 6f 72 64 65 72 20 74 6f 20 73 68 6f 77 20 74   order to show t
a960: 68 61 74 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hat the optimiza
a970: 74 69 6f 6e 73 20 64 6f 20 6e 6f 74 0a 63 61 75  tions do not.cau
a980: 73 65 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 73 2e  se malfunctions.
a990: 3c 2f 70 3e 0a 0a 0a 3c 74 63 6c 3e 68 64 5f 66  </p>...<tcl>hd_f
a9a0: 72 61 67 6d 65 6e 74 20 63 6b 6c 69 73 74 20 7b  ragment cklist {
a9b0: 72 65 6c 65 61 73 65 20 74 65 73 74 69 6e 67 20  release testing 
a9c0: 63 68 65 63 6b 6c 69 73 74 73 7d 20 7b 63 68 65  checklists} {che
a9d0: 63 6b 6c 69 73 74 7d 3c 2f 74 63 6c 3e 0a 3c 68  cklist}</tcl>.<h
a9e0: 31 3e 43 68 65 63 6b 6c 69 73 74 73 3c 2f 68 31  1>Checklists</h1
a9f0: 3e 0a 0a 3c 70 3e 54 68 65 20 53 51 4c 69 74 65  >..<p>The SQLite
aa00: 20 64 65 76 65 6c 6f 70 65 72 73 20 75 73 65 20   developers use 
aa10: 61 6e 20 6f 6e 2d 6c 69 6e 65 20 63 68 65 63 6b  an on-line check
aa20: 6c 69 73 74 20 74 6f 20 63 6f 6f 72 64 69 6e 61  list to coordina
aa30: 74 65 20 74 65 73 74 69 6e 67 0a 61 63 74 69 76  te testing.activ
aa40: 69 74 79 20 61 6e 64 20 74 6f 20 76 65 72 69 66  ity and to verif
aa50: 79 20 74 68 61 74 20 61 6c 6c 20 74 65 73 74 73  y that all tests
aa60: 20 70 61 73 73 20 70 72 69 6f 72 20 65 61 63 68   pass prior each
aa70: 20 53 51 4c 69 74 65 20 72 65 6c 65 61 73 65 2e   SQLite release.
aa80: 0a 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f  .<a href="http:/
aa90: 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f  /www.sqlite.org/
aaa0: 63 68 65 63 6b 6c 69 73 74 73 2f 69 6e 64 65 78  checklists/index
aab0: 2e 68 74 6d 6c 22 3e 50 61 73 74 20 63 68 65 63  .html">Past chec
aac0: 6b 6c 69 73 74 73 3c 2f 61 3e 0a 61 72 65 20 72  klists</a>.are r
aad0: 65 74 61 69 6e 65 64 20 66 6f 72 20 68 69 73 74  etained for hist
aae0: 6f 72 69 63 61 6c 20 72 65 66 65 72 65 6e 63 65  orical reference
aaf0: 2e 0a 28 54 68 65 20 63 68 65 63 6b 6c 69 73 74  ..(The checklist
ab00: 73 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 20  s are read-only 
ab10: 66 6f 72 20 61 6e 6f 6e 79 6d 6f 75 73 20 69 6e  for anonymous in
ab20: 74 65 72 6e 65 74 20 76 69 65 77 65 72 73 2c 20  ternet viewers, 
ab30: 62 75 74 0a 64 65 76 65 6c 6f 70 65 72 73 20 63  but.developers c
ab40: 61 6e 20 6c 6f 67 20 69 6e 20 61 6e 64 20 75 70  an log in and up
ab50: 64 61 74 65 20 63 68 65 63 6b 6c 69 73 74 20 69  date checklist i
ab60: 74 65 6d 73 20 69 6e 20 74 68 65 69 72 20 77 65  tems in their we
ab70: 62 0a 62 72 6f 77 73 65 72 73 2e 29 0a 54 68 65  b.browsers.).The
ab80: 20 75 73 65 20 6f 66 20 63 68 65 63 6b 6c 69 73   use of checklis
ab90: 74 73 20 66 6f 72 20 53 51 4c 69 74 65 20 74 65  ts for SQLite te
aba0: 73 74 69 6e 67 20 61 6e 64 20 6f 74 68 65 72 20  sting and other 
abb0: 64 65 76 65 6c 6f 70 6d 65 6e 74 20 61 63 74 69  development acti
abc0: 76 69 74 69 65 73 0a 69 73 20 69 6e 73 70 69 72  vities.is inspir
abd0: 65 64 20 62 79 20 3c 69 3e 0a 5b 68 74 74 70 3a  ed by <i>.[http:
abe0: 2f 2f 61 74 75 6c 67 61 77 61 6e 64 65 2e 63 6f  //atulgawande.co
abf0: 6d 2f 62 6f 6f 6b 2f 74 68 65 2d 63 68 65 63 6b  m/book/the-check
ac00: 6c 69 73 74 2d 6d 61 6e 69 66 65 73 74 6f 2f 20  list-manifesto/ 
ac10: 7c 20 54 68 65 20 43 68 65 63 6b 6c 69 73 74 20  | The Checklist 
ac20: 4d 61 6e 69 66 65 73 74 6f 5d 0a 3c 2f 69 3e 2e  Manifesto].</i>.
ac30: 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 6c 61 74  </p>..<p>The lat
ac40: 65 73 74 20 63 68 65 63 6b 6c 69 73 74 73 20 63  est checklists c
ac50: 6f 6e 74 61 69 6e 20 61 70 70 72 6f 78 69 6d 61  ontain approxima
ac60: 74 65 6c 79 20 32 30 30 20 69 74 65 6d 73 20 74  tely 200 items t
ac70: 68 61 74 20 61 72 65 0a 69 6e 64 69 76 69 64 75  hat are.individu
ac80: 61 6c 6c 79 20 76 65 72 69 66 69 65 64 20 66 6f  ally verified fo
ac90: 72 20 65 61 63 68 20 72 65 6c 65 61 73 65 2e 20  r each release. 
aca0: 20 53 6f 6d 65 20 63 68 65 63 6b 6c 69 73 74 20   Some checklist 
acb0: 69 74 65 6d 73 20 6f 6e 6c 79 20 74 61 6b 65 0a  items only take.
acc0: 61 20 66 65 77 20 73 65 63 6f 6e 64 73 20 74 6f  a few seconds to
acd0: 20 76 65 72 69 66 79 20 61 6e 64 20 6d 61 72 6b   verify and mark
ace0: 20 6f 66 66 2e 20 20 4f 74 68 65 72 73 20 69 6e   off.  Others in
acf0: 76 6f 6c 76 65 20 74 65 73 74 20 73 75 69 74 65  volve test suite
ad00: 73 0a 74 68 61 74 20 72 75 6e 20 66 6f 72 20 6d  s.that run for m
ad10: 61 6e 79 20 68 6f 75 72 73 2e 3c 2f 70 3e 0a 0a  any hours.</p>..
ad20: 3c 70 3e 54 68 65 20 72 65 6c 65 61 73 65 20 63  <p>The release c
ad30: 68 65 63 6b 6c 69 73 74 20 69 73 20 6e 6f 74 20  hecklist is not 
ad40: 61 75 74 6f 6d 61 74 65 64 3a 20 64 65 76 65 6c  automated: devel
ad50: 6f 70 65 72 73 20 72 75 6e 20 65 61 63 68 20 69  opers run each i
ad60: 74 65 6d 20 6f 6e 0a 74 68 65 20 63 68 65 63 6b  tem on.the check
ad70: 6c 69 73 74 20 6d 61 6e 75 61 6c 6c 79 2e 20 20  list manually.  
ad80: 57 65 20 66 69 6e 64 20 74 68 61 74 20 69 74 20  We find that it 
ad90: 69 73 20 69 6d 70 6f 72 74 61 6e 74 20 74 6f 20  is important to 
ada0: 6b 65 65 70 20 61 20 68 75 6d 61 6e 20 69 6e 0a  keep a human in.
adb0: 74 68 65 20 6c 6f 6f 70 2e 20 20 53 6f 6d 65 74  the loop.  Somet
adc0: 69 6d 65 73 20 70 72 6f 62 6c 65 6d 73 20 61 72  imes problems ar
add0: 65 20 66 6f 75 6e 64 20 77 68 69 6c 65 20 72 75  e found while ru
ade0: 6e 6e 69 6e 67 20 61 20 63 68 65 63 6b 6c 69 73  nning a checklis
adf0: 74 20 69 74 65 6d 0a 65 76 65 6e 20 74 68 6f 75  t item.even thou
ae00: 67 68 20 74 68 65 20 74 65 73 74 20 69 74 73 65  gh the test itse
ae10: 6c 66 20 70 61 73 73 65 64 2e 20 20 49 74 20 69  lf passed.  It i
ae20: 73 20 69 6d 70 6f 72 74 61 6e 74 20 74 6f 20 68  s important to h
ae30: 61 76 65 20 61 20 68 75 6d 61 6e 0a 72 65 76 69  ave a human.revi
ae40: 65 77 69 6e 67 20 74 68 65 20 74 65 73 74 20 6f  ewing the test o
ae50: 75 74 70 75 74 20 61 74 20 74 68 65 20 68 69 67  utput at the hig
ae60: 68 65 73 74 20 6c 65 76 65 6c 2c 20 61 6e 64 20  hest level, and 
ae70: 63 6f 6e 73 74 61 6e 74 6c 79 20 61 73 6b 69 6e  constantly askin
ae80: 67 0a 22 49 73 20 74 68 69 73 20 72 65 61 6c 6c  g."Is this reall
ae90: 79 20 72 69 67 68 74 3f 22 3c 2f 70 3e 0a 0a 3c  y right?"</p>..<
aea0: 70 3e 54 68 65 20 72 65 6c 65 61 73 65 20 63 68  p>The release ch
aeb0: 65 63 6b 6c 69 73 74 20 69 73 20 63 6f 6e 74 69  ecklist is conti
aec0: 6e 75 6f 75 73 6c 79 20 65 76 6f 6c 76 69 6e 67  nuously evolving
aed0: 2e 20 20 41 73 20 6e 65 77 20 70 72 6f 62 6c 65  .  As new proble
aee0: 6d 73 20 6f 72 0a 70 6f 74 65 6e 74 69 61 6c 20  ms or.potential 
aef0: 70 72 6f 62 6c 65 6d 73 20 61 72 65 20 64 69 73  problems are dis
af00: 63 6f 76 65 72 65 64 2c 20 6e 65 77 20 63 68 65  covered, new che
af10: 63 6b 6c 69 73 74 20 69 74 65 6d 73 20 61 72 65  cklist items are
af20: 20 61 64 64 65 64 20 74 6f 0a 6d 61 6b 65 20 73   added to.make s
af30: 75 72 65 20 74 68 6f 73 65 20 70 72 6f 62 6c 65  ure those proble
af40: 6d 73 20 64 6f 20 6e 6f 74 20 61 70 70 65 61 72  ms do not appear
af50: 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 72   in subsequent r
af60: 65 6c 65 61 73 65 73 2e 20 20 54 68 65 0a 72 65  eleases.  The.re
af70: 6c 65 61 73 65 20 63 68 65 63 6b 6c 69 73 74 20  lease checklist 
af80: 68 61 73 20 70 72 6f 76 65 6e 20 74 6f 20 62 65  has proven to be
af90: 20 61 6e 20 69 6e 76 61 6c 75 61 62 6c 65 20 74   an invaluable t
afa0: 6f 6f 6c 20 69 6e 20 68 65 6c 70 69 6e 67 20 74  ool in helping t
afb0: 6f 0a 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  o.ensure that no
afc0: 74 68 69 6e 67 20 69 73 20 6f 76 65 72 6c 6f 6f  thing is overloo
afd0: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 72  ked during the r
afe0: 65 6c 65 61 73 65 20 70 72 6f 63 65 73 73 2e 3c  elease process.<
aff0: 2f 70 3e 0a 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72  /p>...<tcl>hd_fr
b000: 61 67 6d 65 6e 74 20 73 74 61 74 69 63 61 6e 61  agment staticana
b010: 6c 79 73 69 73 3c 2f 74 63 6c 3e 0a 3c 68 31 3e  lysis</tcl>.<h1>
b020: 53 74 61 74 69 63 20 41 6e 61 6c 79 73 69 73 3c  Static Analysis<
b030: 2f 68 31 3e 0a 0a 3c 70 3e 53 74 61 74 69 63 20  /h1>..<p>Static 
b040: 61 6e 61 6c 79 73 69 73 20 6d 65 61 6e 73 20 61  analysis means a
b050: 6e 61 6c 79 7a 69 6e 67 20 73 6f 75 72 63 65 20  nalyzing source 
b060: 63 6f 64 65 20 61 74 20 63 6f 6d 70 69 6c 65 2d  code at compile-
b070: 74 69 6d 65 20 74 6f 0a 63 68 65 63 6b 20 66 6f  time to.check fo
b080: 72 20 63 6f 72 72 65 63 74 6e 65 73 73 2e 20 20  r correctness.  
b090: 53 74 61 74 69 63 20 61 6e 61 6c 79 73 69 73 20  Static analysis 
b0a0: 69 6e 63 6c 75 64 65 73 20 63 6f 6d 70 69 6c 65  includes compile
b0b0: 72 0a 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  r.warning messag
b0c0: 65 73 20 61 6e 64 20 6d 6f 72 65 20 69 6e 2d 64  es and more in-d
b0d0: 65 70 74 68 20 61 6e 61 6c 79 73 69 73 20 65 6e  epth analysis en
b0e0: 67 69 6e 65 73 20 73 75 63 68 20 61 73 20 74 68  gines such as th
b0f0: 65 0a 5b 68 74 74 70 3a 2f 2f 63 6c 61 6e 67 2d  e.[http://clang-
b100: 61 6e 61 6c 79 7a 65 72 2e 6c 6c 76 6d 2e 6f 72  analyzer.llvm.or
b110: 67 2f 20 7c 20 43 6c 61 6e 67 20 53 74 61 74 69  g/ | Clang Stati
b120: 63 20 41 6e 61 6c 79 7a 65 72 5d 2e 0a 53 51 4c  c Analyzer]..SQL
b130: 69 74 65 20 63 6f 6d 70 69 6c 65 73 20 77 69 74  ite compiles wit
b140: 68 6f 75 74 20 77 61 72 6e 69 6e 67 73 20 6f 6e  hout warnings on
b150: 20 47 43 43 20 61 6e 64 20 43 6c 61 6e 67 20 75   GCC and Clang u
b160: 73 69 6e 67 20 0a 74 68 65 20 2d 57 61 6c 6c 20  sing .the -Wall 
b170: 61 6e 64 20 2d 57 65 78 74 72 61 20 66 6c 61 67  and -Wextra flag
b180: 73 20 6f 6e 20 4c 69 6e 75 78 20 61 6e 64 20 4d  s on Linux and M
b190: 61 63 20 61 6e 64 20 6f 6e 20 4d 53 56 43 20 6f  ac and on MSVC o
b1a0: 6e 20 57 69 6e 64 6f 77 73 2e 0a 4e 6f 20 76 61  n Windows..No va
b1b0: 6c 69 64 20 77 61 72 6e 69 6e 67 73 20 61 72 65  lid warnings are
b1c0: 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 68   generated by th
b1d0: 65 20 43 6c 61 6e 67 20 53 74 61 74 69 63 20 41  e Clang Static A
b1e0: 6e 61 6c 79 7a 65 72 20 74 6f 6f 6c 20 22 73 63  nalyzer tool "sc
b1f0: 61 6e 2d 62 75 69 6c 64 22 0a 65 69 74 68 65 72  an-build".either
b200: 20 28 74 68 6f 75 67 68 20 72 65 63 65 6e 74 20   (though recent 
b210: 76 65 72 73 69 6f 6e 73 20 6f 66 20 63 6c 61 6e  versions of clan
b220: 67 20 73 65 65 6d 20 74 6f 20 67 65 6e 65 72 61  g seem to genera
b230: 74 65 20 6d 61 6e 79 20 66 61 6c 73 65 2d 70 6f  te many false-po
b240: 73 69 74 69 76 65 73 2e 29 0a 4e 65 76 65 72 74  sitives.).Nevert
b250: 68 65 6c 65 73 73 2c 20 73 6f 6d 65 20 77 61 72  heless, some war
b260: 6e 69 6e 67 73 20 6d 69 67 68 74 20 62 65 20 67  nings might be g
b270: 65 6e 65 72 61 74 65 64 20 62 79 20 6f 74 68 65  enerated by othe
b280: 72 0a 73 74 61 74 69 63 20 61 6e 61 6c 79 7a 65  r.static analyze
b290: 72 73 2e 20 20 55 73 65 72 73 20 61 72 65 20 65  rs.  Users are e
b2a0: 6e 63 6f 75 72 61 67 65 64 20 6e 6f 74 20 74 6f  ncouraged not to
b2b0: 20 73 74 72 65 73 73 20 6f 76 65 72 20 74 68 65   stress over the
b2c0: 73 65 0a 77 61 72 6e 69 6e 67 73 20 61 6e 64 20  se.warnings and 
b2d0: 74 6f 20 69 6e 73 74 65 61 64 20 74 61 6b 65 20  to instead take 
b2e0: 73 6f 6c 61 63 65 20 69 6e 20 74 68 65 20 69 6e  solace in the in
b2f0: 74 65 6e 73 65 20 74 65 73 74 69 6e 67 20 6f 66  tense testing of
b300: 20 53 51 4c 69 74 65 0a 64 65 73 63 72 69 62 65   SQLite.describe
b310: 64 20 61 62 6f 76 65 2e 20 0a 3c 2f 70 3e 0a 0a  d above. .</p>..
b320: 3c 70 3e 53 74 61 74 69 63 20 61 6e 61 6c 79 73  <p>Static analys
b330: 69 73 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  is has not been 
b340: 68 65 6c 70 66 75 6c 20 69 6e 20 66 69 6e 64 69  helpful in findi
b350: 6e 67 0a 62 75 67 73 20 69 6e 20 53 51 4c 69 74  ng.bugs in SQLit
b360: 65 2e 20 20 53 74 61 74 69 63 20 61 6e 61 6c 79  e.  Static analy
b370: 73 69 73 20 68 61 73 20 66 6f 75 6e 64 20 61 20  sis has found a 
b380: 66 65 77 20 62 75 67 73 20 69 6e 20 53 51 4c 69  few bugs in SQLi
b390: 74 65 2c 20 62 75 74 0a 74 68 6f 73 65 20 61 72  te, but.those ar
b3a0: 65 20 74 68 65 20 65 78 63 65 70 74 69 6f 6e 73  e the exceptions
b3b0: 2e 20 20 4d 6f 72 65 20 62 75 67 73 20 68 61 76  .  More bugs hav
b3c0: 65 20 62 65 65 6e 0a 69 6e 74 72 6f 64 75 63 65  e been.introduce
b3d0: 64 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  d into SQLite wh
b3e0: 69 6c 65 20 74 72 79 69 6e 67 20 74 6f 20 67 65  ile trying to ge
b3f0: 74 20 69 74 20 74 6f 20 63 6f 6d 70 69 6c 65 20  t it to compile 
b400: 77 69 74 68 6f 75 74 20 0a 77 61 72 6e 69 6e 67  without .warning
b410: 73 20 74 68 61 6e 20 68 61 76 65 20 62 65 65 6e  s than have been
b420: 20 66 6f 75 6e 64 20 62 79 20 73 74 61 74 69 63   found by static
b430: 20 61 6e 61 6c 79 73 69 73 2e 3c 2f 70 3e 0a 0a   analysis.</p>..
b440: 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
b450: 20 73 75 6d 6d 61 72 79 3c 2f 74 63 6c 3e 0a 3c   summary</tcl>.<
b460: 68 31 3e 53 75 6d 6d 61 72 79 3c 2f 68 31 3e 0a  h1>Summary</h1>.
b470: 0a 3c 70 3e 53 51 4c 69 74 65 20 69 73 20 6f 70  .<p>SQLite is op
b480: 65 6e 20 73 6f 75 72 63 65 2e 20 20 54 68 69 73  en source.  This
b490: 20 67 69 76 65 73 20 6d 61 6e 79 20 70 65 6f 70   gives many peop
b4a0: 6c 65 20 74 68 65 20 69 64 65 61 20 74 68 61 74  le the idea that
b4b0: 0a 69 74 20 69 73 20 6e 6f 74 20 77 65 6c 6c 20  .it is not well 
b4c0: 74 65 73 74 65 64 20 61 73 20 63 6f 6d 6d 65 72  tested as commer
b4d0: 63 69 61 6c 20 73 6f 66 74 77 61 72 65 20 61 6e  cial software an
b4e0: 64 20 69 73 20 70 65 72 68 61 70 73 20 75 6e 72  d is perhaps unr
b4f0: 65 6c 69 61 62 6c 65 2e 0a 42 75 74 20 74 68 61  eliable..But tha
b500: 74 20 69 6d 70 72 65 73 73 69 6f 6e 20 69 73 20  t impression is 
b510: 66 61 6c 73 65 2e 20 20 0a 53 51 4c 69 74 65 20  false.  .SQLite 
b520: 68 61 73 20 65 78 68 69 62 69 74 65 64 20 76 65  has exhibited ve
b530: 72 79 20 68 69 67 68 20 72 65 6c 69 61 62 69 6c  ry high reliabil
b540: 69 74 79 20 69 6e 20 74 68 65 20 66 69 65 6c 64  ity in the field
b550: 20 61 6e 64 0a 61 20 76 65 72 79 20 6c 6f 77 20   and.a very low 
b560: 64 65 66 65 63 74 20 72 61 74 65 2c 20 65 73 70  defect rate, esp
b570: 65 63 69 61 6c 6c 79 20 63 6f 6e 73 69 64 65 72  ecially consider
b580: 69 6e 67 20 68 6f 77 20 72 61 70 69 64 6c 79 20  ing how rapidly 
b590: 69 74 20 69 73 20 65 76 6f 6c 76 69 6e 67 2e 0a  it is evolving..
b5a0: 54 68 65 20 71 75 61 6c 69 74 79 20 6f 66 20 53  The quality of S
b5b0: 51 4c 69 74 65 20 69 73 20 61 63 68 69 65 76 65  QLite is achieve
b5c0: 64 20 69 6e 20 70 61 72 74 20 62 79 20 63 61 72  d in part by car
b5d0: 65 66 75 6c 20 63 6f 64 65 20 64 65 73 69 67 6e  eful code design
b5e0: 20 61 6e 64 0a 69 6d 70 6c 65 6d 65 6e 74 61 74   and.implementat
b5f0: 69 6f 6e 2e 20 20 42 75 74 20 65 78 74 65 6e 73  ion.  But extens
b600: 69 76 65 20 74 65 73 74 69 6e 67 20 61 6c 73 6f  ive testing also
b610: 20 70 6c 61 79 73 20 61 20 76 69 74 61 6c 20 72   plays a vital r
b620: 6f 6c 65 20 69 6e 0a 6d 61 69 6e 74 61 69 6e 69  ole in.maintaini
b630: 6e 67 20 61 6e 64 20 69 6d 70 72 6f 76 69 6e 67  ng and improving
b640: 20 74 68 65 20 71 75 61 6c 69 74 79 20 6f 66 20   the quality of 
b650: 53 51 4c 69 74 65 2e 20 20 54 68 69 73 20 64 6f  SQLite.  This do
b660: 63 75 6d 65 6e 74 20 68 61 73 0a 73 75 6d 6d 61  cument has.summa
b670: 72 69 7a 65 64 20 74 68 65 20 74 65 73 74 69 6e  rized the testin
b680: 67 20 70 72 6f 63 65 64 75 72 65 73 20 74 68 61  g procedures tha
b690: 74 20 65 76 65 72 79 20 72 65 6c 65 61 73 65 20  t every release 
b6a0: 6f 66 20 53 51 4c 69 74 65 20 75 6e 64 65 72 67  of SQLite underg
b6b0: 6f 65 73 0a 77 69 74 68 20 74 68 65 20 68 6f 70  oes.with the hop
b6c0: 65 20 6f 66 20 69 6e 73 70 69 72 69 6e 67 20 63  e of inspiring c
b6d0: 6f 6e 66 69 64 65 6e 63 65 20 74 68 61 74 20 53  onfidence that S
b6e0: 51 4c 69 74 65 20 69 73 0a 73 75 69 74 61 62 6c  QLite is.suitabl
b6f0: 65 20 66 6f 72 20 75 73 65 20 69 6e 20 6d 69 73  e for use in mis
b700: 73 69 6f 6e 2d 63 72 69 74 69 63 61 6c 20 61 70  sion-critical ap
b710: 70 6c 69 63 61 74 69 6f 6e 73 2e 3c 2f 70 3e 0a  plications.</p>.