Documentation Source Text

Hex Artifact Content
Login

Artifact faea21548eadc0619c4645e286e6eebde5788b48:


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 63 6c 3e 0a 23  }</tcl>..<tcl>.#
0060: 20 54 68 69 73 20 64 6f 63 75 6d 65 6e 74 20 63   This document c
0070: 6f 6e 74 61 69 6e 73 20 6d 61 6e 79 20 73 69 7a  ontains many siz
0080: 65 20 73 74 61 74 69 73 74 69 63 73 20 61 62 6f  e statistics abo
0090: 75 74 20 53 51 4c 69 74 65 2c 20 73 74 61 74 69  ut SQLite, stati
00a0: 73 74 69 63 73 0a 23 20 74 68 61 74 20 63 68 61  stics.# that cha
00b0: 6e 67 65 20 66 72 65 71 75 65 6e 74 6c 79 2e 20  nge frequently. 
00c0: 20 57 65 20 77 61 6e 74 20 74 68 65 20 64 6f 63   We want the doc
00d0: 75 6d 65 6e 74 20 74 6f 20 62 65 20 75 70 2d 74  ument to be up-t
00e0: 6f 2d 64 61 74 65 2e 20 20 54 6f 0a 23 20 66 61  o-date.  To.# fa
00f0: 63 69 6c 69 74 61 74 65 20 74 68 61 74 2c 20 61  cilitate that, a
0100: 6c 6c 20 74 68 65 20 73 69 7a 65 20 76 61 6c 75  ll the size valu
0110: 65 73 20 61 72 65 20 64 65 66 69 6e 65 64 20 62  es are defined b
0120: 79 20 76 61 72 69 61 62 6c 65 73 20 68 65 72 65  y variables here
0130: 0a 23 20 77 68 69 63 68 20 61 72 65 20 74 68 65  .# which are the
0140: 6e 20 75 73 65 64 20 61 73 20 6e 65 65 64 65 64  n used as needed
0150: 20 74 68 72 6f 75 67 68 20 74 68 65 20 64 6f 63   through the doc
0160: 75 6d 65 6e 74 2e 0a 23 0a 23 20 4e 4f 54 45 3a  ument..#.# NOTE:
0170: 20 20 41 6c 73 6f 20 75 70 64 61 74 65 20 74 68    Also update th
0180: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
0190: 20 69 6e 20 74 68 65 20 74 65 78 74 21 21 21 0a   in the text!!!.
01a0: 23 0a 0a 23 20 73 6c 6f 63 20 73 71 6c 69 74 65  #..# sloc sqlite
01b0: 33 2e 63 0a 73 65 74 20 73 74 61 74 28 63 6f 72  3.c.set stat(cor
01c0: 65 53 4c 4f 43 29 20 20 20 20 37 33 30 33 36 20  eSLOC)    73036 
01d0: 20 3b 23 20 4e 6f 6e 2d 63 6f 6d 6d 65 6e 74 20   ;# Non-comment 
01e0: 6c 69 6e 65 73 20 6f 66 20 61 6d 61 6c 67 61 6d  lines of amalgam
01f0: 61 74 69 6f 6e 20 63 6f 64 65 20 0a 23 20 73 6c  ation code .# sl
0200: 6f 63 20 74 65 73 74 2a 2e 63 0a 73 65 74 20 73  oc test*.c.set s
0210: 74 61 74 28 74 63 6c 63 53 4c 4f 43 29 20 20 20  tat(tclcSLOC)   
0220: 20 31 38 39 31 32 20 20 3b 23 20 4e 6f 6e 2d 63   18912  ;# Non-c
0230: 6f 6d 6d 65 6e 74 20 6c 69 6e 65 73 20 6f 66 20  omment lines of 
0240: 74 65 73 74 20 43 20 63 6f 64 65 0a 23 20 6c 73  test C code.# ls
0250: 20 74 65 73 74 2a 2e 63 20 74 63 6c 73 71 6c 69   test*.c tclsqli
0260: 74 65 2e 63 20 7c 20 77 63 0a 73 65 74 20 73 74  te.c | wc.set st
0270: 61 74 28 74 63 6c 63 4e 66 69 6c 65 29 20 20 20  at(tclcNfile)   
0280: 20 20 20 33 39 20 20 3b 23 20 4e 75 6d 62 65 72     39  ;# Number
0290: 20 6f 66 20 66 69 6c 65 73 20 6f 66 20 54 43 4c   of files of TCL
02a0: 20 43 20 74 65 73 74 63 6f 64 65 20 2b 20 74 63   C testcode + tc
02b0: 6c 73 71 6c 69 74 65 2e 63 0a 23 20 6c 73 20 2d  lsqlite.c.# ls -
02c0: 6c 20 74 65 73 74 2a 2e 63 20 74 63 6c 73 71 6c  l test*.c tclsql
02d0: 69 74 65 2e 63 20 7c 20 61 77 6b 20 27 7b 73 75  ite.c | awk '{su
02e0: 6d 2b 3d 24 35 7d 45 4e 44 7b 70 72 69 6e 74 20  m+=$5}END{print 
02f0: 73 75 6d 7d 27 0a 73 65 74 20 73 74 61 74 28 74  sum}'.set stat(t
0300: 63 6c 63 4e 42 79 74 65 29 20 20 39 30 37 38 37  clcNByte)  90787
0310: 37 20 20 3b 23 20 4e 75 6d 62 65 72 20 6f 66 20  7  ;# Number of 
0320: 62 79 74 65 73 20 6f 66 20 54 43 4c 20 43 20 74  bytes of TCL C t
0330: 65 73 74 63 6f 64 65 20 2b 20 74 63 6c 73 71 6c  estcode + tclsql
0340: 69 74 65 2e 63 0a 23 20 73 6c 6f 63 20 2a 2e 74  ite.c.# sloc *.t
0350: 65 73 74 20 2a 2e 74 63 6c 0a 73 65 74 20 73 74  est *.tcl.set st
0360: 61 74 28 74 63 6c 73 53 4c 4f 43 29 20 20 20 32  at(tclsSLOC)   2
0370: 32 31 39 36 37 20 20 3b 23 20 4e 6f 6e 2d 63 6f  21967  ;# Non-co
0380: 6d 6d 65 6e 74 20 6c 69 6e 65 73 20 6f 66 20 54  mment lines of T
0390: 43 4c 20 74 65 73 74 20 73 63 72 69 70 74 0a 23  CL test script.#
03a0: 20 6c 73 20 2a 2e 74 65 73 74 20 2a 2e 74 63 6c   ls *.test *.tcl
03b0: 20 7c 20 77 63 0a 73 65 74 20 73 74 61 74 28 74   | wc.set stat(t
03c0: 63 6c 73 4e 46 69 6c 65 29 20 20 20 20 20 36 31  clsNFile)     61
03d0: 37 20 20 3b 23 20 4e 75 6d 62 65 72 20 6f 66 20  7  ;# Number of 
03e0: 66 69 6c 65 73 20 6f 66 20 54 43 4c 20 74 65 73  files of TCL tes
03f0: 74 20 73 63 72 69 70 74 0a 23 20 6c 73 20 2d 6c  t script.# ls -l
0400: 20 2a 2e 74 65 73 74 20 2a 2e 74 63 6c 20 7c 20   *.test *.tcl | 
0410: 61 77 6b 20 27 7b 73 75 6d 2b 3d 24 35 7d 45 4e  awk '{sum+=$5}EN
0420: 44 7b 70 72 69 6e 74 20 73 75 6d 7d 27 0a 73 65  D{print sum}'.se
0430: 74 20 73 74 61 74 28 74 63 6c 73 4e 42 79 74 65  t stat(tclsNByte
0440: 29 20 39 37 35 36 37 31 36 20 20 3b 23 20 4e 75  ) 9756716  ;# Nu
0450: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
0460: 20 54 43 4c 20 74 65 73 74 20 73 63 72 69 70 74   TCL test script
0470: 0a 23 20 67 72 65 70 20 64 6f 5f 74 65 73 74 20  .# grep do_test 
0480: 2a 2e 74 65 73 74 20 7c 20 77 63 3b 20 67 72 65  *.test | wc; gre
0490: 70 20 64 6f 5f 65 78 65 63 73 71 6c 5f 74 65 73  p do_execsql_tes
04a0: 74 20 2a 2e 74 65 73 74 20 7c 20 77 63 0a 73 65  t *.test | wc.se
04b0: 74 20 73 74 61 74 28 74 63 6c 4e 54 65 73 74 29  t stat(tclNTest)
04c0: 20 20 20 20 32 37 36 36 34 20 20 3b 23 20 4e 75      27664  ;# Nu
04d0: 6d 62 65 72 20 6f 66 20 74 65 73 74 20 63 61 73  mber of test cas
04e0: 65 73 20 69 6e 20 74 68 65 20 54 43 4c 20 74 65  es in the TCL te
04f0: 73 74 20 73 75 69 74 65 0a 73 65 74 20 73 74 61  st suite.set sta
0500: 74 28 74 63 6c 4e 45 76 61 6c 29 20 20 31 34 33  t(tclNEval)  143
0510: 35 34 31 34 20 20 3b 23 20 4e 75 6d 62 65 72 20  5414  ;# Number 
0520: 6f 66 20 74 65 73 74 20 63 61 73 65 20 65 76 61  of test case eva
0530: 6c 75 61 74 69 6f 6e 73 0a 73 65 74 20 73 74 61  luations.set sta
0540: 74 28 6e 53 71 6c 46 75 7a 7a 29 20 20 20 31 30  t(nSqlFuzz)   10
0550: 33 38 38 34 20 20 3b 23 20 4e 75 6d 62 65 72 20  3884  ;# Number 
0560: 6f 66 20 53 51 4c 20 66 75 7a 7a 20 74 65 73 74  of SQL fuzz test
0570: 73 0a 73 65 74 20 73 74 61 74 28 76 71 4e 45 76  s.set stat(vqNEv
0580: 61 6c 29 20 20 20 20 31 33 34 37 35 33 20 20 3b  al)    134753  ;
0590: 23 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 73 74  # Number of test
05a0: 20 65 76 61 6c 75 61 74 69 6f 6e 73 20 66 6f 72   evaluations for
05b0: 20 76 65 72 79 71 75 69 63 6b 2e 74 65 73 74 0a   veryquick.test.
05c0: 23 20 20 73 65 74 20 73 74 61 74 28 76 71 53 74  #  set stat(vqSt
05d0: 6d 74 43 6f 76 29 20 20 20 39 37 2e 32 33 20 20  mtCov)   97.23  
05e0: 3b 23 20 76 65 72 79 71 75 69 63 6b 20 73 74 61  ;# veryquick sta
05f0: 74 65 6d 65 6e 74 20 63 6f 76 65 72 61 67 65 0a  tement coverage.
0600: 23 20 20 73 65 74 20 73 74 61 74 28 76 71 42 72  #  set stat(vqBr
0610: 43 6f 76 29 20 20 20 20 20 39 32 2e 35 37 20 20  Cov)     92.57  
0620: 3b 23 20 76 65 72 79 71 75 69 63 6b 20 62 72 61  ;# veryquick bra
0630: 6e 63 68 20 63 6f 76 65 72 61 67 65 0a 23 20 20  nch coverage.#  
0640: 73 65 74 20 73 74 61 74 28 61 6c 6c 53 74 6d 74  set stat(allStmt
0650: 43 6f 76 29 20 20 39 39 2e 35 30 20 20 3b 23 20  Cov)  99.50  ;# 
0660: 61 6c 6c 2e 74 65 73 74 20 73 74 61 74 65 6d 65  all.test stateme
0670: 6e 74 20 63 6f 76 65 72 61 67 65 0a 23 20 20 73  nt coverage.#  s
0680: 65 74 20 73 74 61 74 28 61 6c 6c 42 72 43 6f 76  et stat(allBrCov
0690: 29 20 20 20 20 39 37 2e 34 31 20 20 3b 23 20 61  )    97.41  ;# a
06a0: 6c 6c 2e 74 65 73 74 20 63 6f 6e 64 69 74 69 6f  ll.test conditio
06b0: 6e 2f 64 65 63 69 73 69 6f 6e 20 63 6f 76 65 72  n/decision cover
06c0: 61 67 65 0a 23 20 74 63 6c 73 68 20 6d 6b 74 68  age.# tclsh mkth
06d0: 33 2e 74 63 6c 20 63 66 67 2f 2a 2e 63 66 67 20  3.tcl cfg/*.cfg 
06e0: 2a 2f 2a 2e 74 65 73 74 20 3e 74 68 33 2e 63 3b  */*.test >th3.c;
06f0: 20 73 6c 6f 63 20 74 68 33 2e 63 0a 73 65 74 20   sloc th3.c.set 
0700: 73 74 61 74 28 74 68 33 53 4c 4f 43 29 20 20 20  stat(th3SLOC)   
0710: 20 36 34 36 38 31 37 20 20 3b 23 20 4e 6f 6e 2d   646817  ;# Non-
0720: 63 6f 6d 6d 65 6e 74 20 6c 69 6e 65 73 20 69 6e  comment lines in
0730: 20 66 75 6c 6c 20 74 68 33 2e 63 0a 23 20 6c 73   full th3.c.# ls
0740: 20 2d 6c 20 74 68 33 2e 63 0a 73 65 74 20 73 74   -l th3.c.set st
0750: 61 74 28 74 68 33 4e 42 79 74 65 29 20 34 38 36  at(th3NByte) 486
0760: 39 32 35 35 33 20 20 3b 23 20 4e 75 6d 62 65 72  92553  ;# Number
0770: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 66 75 6c   of bytes in ful
0780: 6c 20 74 68 33 2e 63 0a 23 20 67 72 65 70 20 74  l th3.c.# grep t
0790: 68 33 74 65 73 74 42 65 67 69 6e 20 2a 2f 2a 2e  h3testBegin */*.
07a0: 74 65 73 74 0a 23 20 67 72 65 70 20 74 68 33 6f  test.# grep th3o
07b0: 6f 6d 42 65 67 69 6e 20 2a 2f 2a 2e 74 65 73 74  omBegin */*.test
07c0: 0a 23 20 67 72 65 70 20 74 68 33 69 6f 65 72 72  .# grep th3ioerr
07d0: 42 65 67 69 6e 20 2a 2f 2a 2e 74 65 73 74 0a 23  Begin */*.test.#
07e0: 20 67 72 65 70 20 27 5e 2d 2d 74 65 73 74 63 61   grep '^--testca
07f0: 73 65 27 20 2a 2f 2a 2e 74 65 73 74 0a 73 65 74  se' */*.test.set
0800: 20 73 74 61 74 28 74 68 33 4e 54 65 73 74 29 20   stat(th3NTest) 
0810: 20 20 20 20 20 33 32 36 38 38 20 20 3b 23 20 4e       32688  ;# N
0820: 75 6d 62 65 72 20 6f 66 20 74 65 73 74 20 63 61  umber of test ca
0830: 73 65 73 0a 23 20 66 72 6f 6d 20 6f 75 74 70 75  ses.# from outpu
0840: 74 20 6f 66 20 61 20 66 75 6c 6c 20 74 65 73 74  t of a full test
0850: 20 72 75 6e 2e 0a 73 65 74 20 73 74 61 74 28 74   run..set stat(t
0860: 68 33 4e 45 43 6f 76 29 20 20 20 20 20 37 33 35  h3NECov)     735
0870: 39 30 35 20 20 3b 23 20 4e 75 6d 62 65 72 20 6f  905  ;# Number o
0880: 66 20 74 65 73 74 20 63 61 73 65 20 65 76 61 6c  f test case eval
0890: 73 20 66 6f 72 20 63 6f 76 65 72 61 67 65 0a 23  s for coverage.#
08a0: 73 65 74 20 73 74 61 74 28 74 68 33 4e 45 54 65  set stat(th3NETe
08b0: 73 74 29 20 20 31 35 30 34 38 36 36 20 20 3b 23  st)  1504866  ;#
08c0: 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 73 74 20   Number of test 
08d0: 63 61 73 65 20 65 76 61 6c 75 61 74 69 6f 6e 73  case evaluations
08e0: 0a 23 73 65 74 20 73 74 61 74 28 74 68 33 4e 45  .#set stat(th3NE
08f0: 45 78 74 29 20 35 38 39 31 37 35 34 38 33 20 20  Ext) 589175483  
0900: 3b 23 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 73  ;# Number of tes
0910: 74 20 63 61 73 65 20 65 76 61 6c 73 20 65 78 74  t case evals ext
0920: 65 6e 64 65 64 0a 23 73 65 74 20 73 74 61 74 28  ended.#set stat(
0930: 74 68 33 4e 45 52 65 6c 29 20 32 35 30 30 30 30  th3NERel) 250000
0940: 30 30 30 30 20 3b 23 20 4e 75 6d 62 65 72 20 6f  0000 ;# Number o
0950: 66 20 74 65 73 74 20 63 61 73 65 20 65 76 61 6c  f test case eval
0960: 73 20 72 65 6c 65 61 73 65 0a 73 65 74 20 73 74  s release.set st
0970: 61 74 28 74 68 33 53 74 6d 74 43 6f 76 29 20 31  at(th3StmtCov) 1
0980: 30 30 2e 30 30 20 20 3b 23 20 54 48 33 20 73 74  00.00  ;# TH3 st
0990: 61 74 65 6d 65 6e 74 20 63 6f 76 65 72 61 67 65  atement coverage
09a0: 0a 73 65 74 20 73 74 61 74 28 74 68 33 42 72 43  .set stat(th3BrC
09b0: 6f 76 29 20 20 20 31 30 30 2e 30 30 20 20 3b 23  ov)   100.00  ;#
09c0: 20 54 48 33 20 62 72 61 6e 63 68 20 63 6f 76 65   TH3 branch cove
09d0: 72 61 67 65 0a 23 20 77 63 20 60 66 69 6e 64 20  rage.# wc `find 
09e0: 2e 20 2d 6e 61 6d 65 20 27 2a 2e 74 65 73 74 27  . -name '*.test'
09f0: 60 20 7c 20 61 77 6b 20 27 7b 78 2b 3d 24 31 7d  ` | awk '{x+=$1}
0a00: 45 4e 44 7b 70 72 69 6e 74 20 78 7d 27 0a 73 65  END{print x}'.se
0a10: 74 20 73 74 61 74 28 73 6c 74 73 53 4c 4f 43 29  t stat(sltsSLOC)
0a20: 20 20 39 30 34 38 39 34 39 34 20 3b 23 20 4e 6f    90489494 ;# No
0a30: 6e 2d 63 6f 6d 6d 65 6e 74 20 6c 69 6e 65 73 20  n-comment lines 
0a40: 6f 66 20 53 4c 54 20 74 65 73 74 20 73 63 72 69  of SLT test scri
0a50: 70 74 0a 23 20 6c 73 20 2d 6c 20 60 66 69 6e 64  pt.# ls -l `find
0a60: 20 2e 20 2d 6e 61 6d 65 20 27 2a 2e 74 65 73 74   . -name '*.test
0a70: 27 60 20 7c 20 61 77 6b 20 27 7b 73 75 6d 2b 3d  '` | awk '{sum+=
0a80: 24 35 7d 45 4e 44 7b 70 72 69 6e 74 20 73 75 6d  $5}END{print sum
0a90: 7d 27 0a 73 65 74 20 73 74 61 74 28 73 6c 74 73  }'.set stat(slts
0aa0: 4e 42 79 74 65 29 20 31 31 32 30 36 39 33 34 35  NByte) 112069345
0ab0: 37 20 3b 23 20 42 79 74 65 73 20 6f 66 20 53 4c  7 ;# Bytes of SL
0ac0: 54 20 74 65 73 74 20 73 63 72 69 70 74 0a 23 20  T test script.# 
0ad0: 66 69 6e 64 20 2e 20 2d 6e 61 6d 65 20 27 2a 2e  find . -name '*.
0ae0: 74 65 73 74 27 20 7c 20 77 63 0a 73 65 74 20 73  test' | wc.set s
0af0: 74 61 74 28 73 6c 74 73 4e 46 69 6c 65 29 20 20  tat(sltsNFile)  
0b00: 20 20 20 20 20 20 36 32 39 20 3b 23 20 46 69 6c        629 ;# Fil
0b10: 65 73 20 6f 66 20 53 4c 54 20 74 65 73 74 20 73  es of SLT test s
0b20: 63 72 69 70 74 0a 23 20 73 6c 6f 63 20 6d 64 35  cript.# sloc md5
0b30: 2e 63 20 73 6c 74 5f 2a 2e 63 20 73 71 6c 6c 6f  .c slt_*.c sqllo
0b40: 67 69 63 74 65 73 74 2e 63 0a 73 65 74 20 73 74  gictest.c.set st
0b50: 61 74 28 73 6c 74 63 53 4c 4f 43 29 20 20 20 20  at(sltcSLOC)    
0b60: 20 20 20 20 31 34 30 33 20 3b 23 20 4e 6f 6e 2d      1403 ;# Non-
0b70: 63 6f 6d 6d 65 6e 74 20 6c 69 6e 65 73 20 6f 66  comment lines of
0b80: 20 53 4c 54 20 43 20 63 6f 64 65 0a 23 20 67 72   SLT C code.# gr
0b90: 65 70 20 27 5e 71 75 65 72 79 27 20 60 66 6f 73  ep '^query' `fos
0ba0: 73 69 6c 20 6c 73 20 7c 20 61 77 6b 20 27 2f 5c  sil ls | awk '/\
0bb0: 2e 74 65 73 74 24 2f 7b 70 72 69 6e 74 20 24 32  .test$/{print $2
0bc0: 7d 27 60 20 7c 20 77 63 0a 73 65 74 20 73 74 61  }'` | wc.set sta
0bd0: 74 28 73 6c 74 4e 54 65 73 74 29 20 20 20 20 20  t(sltNTest)     
0be0: 37 32 30 30 34 37 38 20 3b 23 20 4e 75 6d 62 65  7200478 ;# Numbe
0bf0: 72 20 6f 66 20 74 65 73 74 20 63 61 73 65 73 20  r of test cases 
0c00: 69 6e 20 53 4c 54 0a 23 20 67 72 65 70 20 27 61  in SLT.# grep 'a
0c10: 73 73 65 72 74 28 27 20 73 71 6c 69 74 65 33 2e  ssert(' sqlite3.
0c20: 63 20 7c 20 77 63 0a 73 65 74 20 73 74 61 74 28  c | wc.set stat(
0c30: 6e 41 73 73 65 72 74 29 20 20 20 20 20 20 20 20  nAssert)        
0c40: 20 33 32 34 32 20 3b 23 20 4e 75 6d 62 65 72 20   3242 ;# Number 
0c50: 6f 66 20 61 73 73 65 72 74 20 73 74 61 74 65 6d  of assert statem
0c60: 65 6e 74 73 0a 23 20 67 72 65 70 20 27 74 65 73  ents.# grep 'tes
0c70: 74 63 61 73 65 28 27 20 73 71 6c 69 74 65 33 2e  tcase(' sqlite3.
0c80: 63 20 7c 20 67 72 65 70 20 2d 76 20 64 65 66 69  c | grep -v defi
0c90: 6e 65 20 7c 20 77 63 0a 73 65 74 20 73 74 61 74  ne | wc.set stat
0ca0: 28 6e 54 65 73 74 63 61 73 65 29 20 20 20 20 20  (nTestcase)     
0cb0: 20 20 20 36 34 38 20 3b 23 20 4e 75 6d 62 65 72     648 ;# Number
0cc0: 20 6f 66 20 74 65 73 74 63 61 73 65 20 73 74 61   of testcase sta
0cd0: 74 65 6d 65 6e 74 73 0a 0a 73 65 74 20 73 74 61  tements..set sta
0ce0: 74 28 74 6f 74 61 6c 53 4c 4f 43 29 20 5b 65 78  t(totalSLOC) [ex
0cf0: 70 72 20 7b 24 73 74 61 74 28 74 63 6c 63 53 4c  pr {$stat(tclcSL
0d00: 4f 43 29 2b 24 73 74 61 74 28 74 63 6c 73 53 4c  OC)+$stat(tclsSL
0d10: 4f 43 29 2b 0a 20 20 20 20 20 20 20 20 20 20 20  OC)+.           
0d20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0d30: 24 73 74 61 74 28 74 68 33 53 4c 4f 43 29 2b 24  $stat(th3SLOC)+$
0d40: 73 74 61 74 28 73 6c 74 63 53 4c 4f 43 29 2b 24  stat(sltcSLOC)+$
0d50: 73 74 61 74 28 73 6c 74 73 53 4c 4f 43 29 7d 5d  stat(sltsSLOC)}]
0d60: 0a 0a 70 72 6f 63 20 47 42 20 7b 65 78 70 72 7d  ..proc GB {expr}
0d70: 20 7b 0a 20 20 73 65 74 20 6e 20 5b 75 70 6c 65   {.  set n [uple
0d80: 76 65 6c 20 23 30 20 65 78 70 72 20 24 65 78 70  vel #0 expr $exp
0d90: 72 5d 0a 20 20 68 64 5f 70 75 74 73 20 5b 66 6f  r].  hd_puts [fo
0da0: 72 6d 61 74 20 25 2e 32 66 20 5b 65 78 70 72 20  rmat %.2f [expr 
0db0: 7b 24 6e 2f 28 31 30 30 30 2e 30 2a 31 30 30 30  {$n/(1000.0*1000
0dc0: 2e 30 2a 31 30 30 30 2e 30 29 7d 5d 5d 0a 7d 20  .0*1000.0)}]].} 
0dd0: 20 0a 70 72 6f 63 20 4d 69 42 20 7b 65 78 70 72   .proc MiB {expr
0de0: 7d 20 7b 0a 20 20 73 65 74 20 6e 20 5b 75 70 6c  } {.  set n [upl
0df0: 65 76 65 6c 20 23 30 20 65 78 70 72 20 24 65 78  evel #0 expr $ex
0e00: 70 72 5d 0a 20 20 68 64 5f 70 75 74 73 20 5b 66  pr].  hd_puts [f
0e10: 6f 72 6d 61 74 20 25 2e 31 66 20 5b 65 78 70 72  ormat %.1f [expr
0e20: 20 7b 24 6e 2f 28 31 30 32 34 2e 30 2a 31 30 32   {$n/(1024.0*102
0e30: 34 2e 30 29 7d 5d 5d 0a 7d 20 20 0a 70 72 6f 63  4.0)}]].}  .proc
0e40: 20 4d 42 20 7b 65 78 70 72 7d 20 7b 0a 20 20 73   MB {expr} {.  s
0e50: 65 74 20 6e 20 5b 75 70 6c 65 76 65 6c 20 23 30  et n [uplevel #0
0e60: 20 65 78 70 72 20 24 65 78 70 72 5d 0a 20 20 68   expr $expr].  h
0e70: 64 5f 70 75 74 73 20 5b 66 6f 72 6d 61 74 20 25  d_puts [format %
0e80: 2e 31 66 20 5b 65 78 70 72 20 7b 24 6e 2f 28 31  .1f [expr {$n/(1
0e90: 30 30 30 2e 30 2a 31 30 30 30 2e 30 29 7d 5d 5d  000.0*1000.0)}]]
0ea0: 0a 7d 20 20 0a 70 72 6f 63 20 4b 69 42 20 7b 65  .}  .proc KiB {e
0eb0: 78 70 72 7d 20 7b 0a 20 20 73 65 74 20 6e 20 5b  xpr} {.  set n [
0ec0: 75 70 6c 65 76 65 6c 20 23 30 20 65 78 70 72 20  uplevel #0 expr 
0ed0: 24 65 78 70 72 5d 0a 20 20 68 64 5f 70 75 74 73  $expr].  hd_puts
0ee0: 20 5b 66 6f 72 6d 61 74 20 25 2e 31 66 20 5b 65   [format %.1f [e
0ef0: 78 70 72 20 7b 24 6e 2f 28 31 30 32 34 2e 30 29  xpr {$n/(1024.0)
0f00: 7d 5d 5d 0a 7d 20 20 0a 70 72 6f 63 20 4b 42 20  }]].}  .proc KB 
0f10: 7b 65 78 70 72 7d 20 7b 0a 20 20 73 65 74 20 6e  {expr} {.  set n
0f20: 20 5b 75 70 6c 65 76 65 6c 20 23 30 20 65 78 70   [uplevel #0 exp
0f30: 72 20 24 65 78 70 72 5d 0a 20 20 68 64 5f 70 75  r $expr].  hd_pu
0f40: 74 73 20 5b 66 6f 72 6d 61 74 20 25 2e 31 66 20  ts [format %.1f 
0f50: 5b 65 78 70 72 20 7b 24 6e 2f 28 31 30 30 30 2e  [expr {$n/(1000.
0f60: 30 29 7d 5d 5d 0a 7d 0a 70 72 6f 63 20 4e 20 7b  0)}]].}.proc N {
0f70: 65 78 70 72 7d 20 7b 0a 20 20 68 64 5f 70 75 74  expr} {.  hd_put
0f80: 73 20 5b 75 70 6c 65 76 65 6c 20 23 30 20 65 78  s [uplevel #0 ex
0f90: 70 72 20 24 65 78 70 72 5d 0a 7d 0a 70 72 6f 63  pr $expr].}.proc
0fa0: 20 76 65 72 73 69 6f 6e 20 7b 7d 20 7b 0a 20 20   version {} {.  
0fb0: 68 64 5f 70 75 74 73 20 24 3a 3a 73 74 61 74 28  hd_puts $::stat(
0fc0: 76 65 72 73 69 6f 6e 29 0a 7d 0a 0a 3c 2f 74 63  version).}..</tc
0fd0: 6c 3e 0a 0a 3c 68 31 20 61 6c 69 67 6e 3d 22 63  l>..<h1 align="c
0fe0: 65 6e 74 65 72 22 3e 48 6f 77 20 53 51 4c 69 74  enter">How SQLit
0ff0: 65 20 49 73 20 54 65 73 74 65 64 3c 2f 68 31 3e  e Is Tested</h1>
1000: 0a 0a 3c 68 32 3e 31 2e 30 20 49 6e 74 72 6f 64  ..<h2>1.0 Introd
1010: 75 63 74 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e  uction</h2>..<p>
1020: 54 68 65 20 72 65 6c 69 61 62 69 6c 69 74 79 20  The reliability 
1030: 61 6e 64 20 72 6f 62 75 73 74 6e 65 73 73 20 6f  and robustness o
1040: 66 20 53 51 4c 69 74 65 20 69 73 20 61 63 68 69  f SQLite is achi
1050: 65 76 65 64 20 69 6e 20 70 61 72 74 0a 62 79 20  eved in part.by 
1060: 74 68 6f 72 6f 75 67 68 20 61 6e 64 20 63 61 72  thorough and car
1070: 65 66 75 6c 20 74 65 73 74 69 6e 67 2e 3c 2f 70  eful testing.</p
1080: 3e 0a 0a 3c 70 3e 41 73 20 6f 66 20 5b 76 65 72  >..<p>As of [ver
1090: 73 69 6f 6e 20 33 2e 37 2e 35 5d 20 28 61 6c 6c  sion 3.7.5] (all
10a0: 20 73 74 61 74 69 73 74 69 63 73 20 69 6e 20 74   statistics in t
10b0: 68 65 20 72 65 70 6f 72 74 20 61 72 65 20 61 67  he report are ag
10c0: 61 69 6e 73 74 20 74 68 61 74 0a 72 65 6c 65 61  ainst that.relea
10d0: 73 65 20 6f 66 20 53 51 4c 69 74 65 29 2c 0a 74  se of SQLite),.t
10e0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
10f0: 79 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 70  y consists of ap
1100: 70 72 6f 78 69 6d 61 74 65 6c 79 0a 3c 74 63 6c  proximately.<tcl
1110: 3e 4b 42 20 7b 24 73 74 61 74 28 63 6f 72 65 53  >KB {$stat(coreS
1120: 4c 4f 43 29 7d 3c 2f 74 63 6c 3e 20 4b 53 4c 4f  LOC)}</tcl> KSLO
1130: 43 20 6f 66 20 43 20 63 6f 64 65 2e 0a 28 4b 53  C of C code..(KS
1140: 4c 4f 43 20 6d 65 61 6e 73 20 74 68 6f 75 73 61  LOC means thousa
1150: 6e 64 73 20 6f 66 20 22 53 6f 75 72 63 65 20 4c  nds of "Source L
1160: 69 6e 65 73 20 4f 66 20 43 6f 64 65 22 20 6f 72  ines Of Code" or
1170: 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  , in other words
1180: 2c 0a 6c 69 6e 65 73 20 6f 66 20 63 6f 64 65 20  ,.lines of code 
1190: 65 78 63 6c 75 64 69 6e 67 20 62 6c 61 6e 6b 20  excluding blank 
11a0: 6c 69 6e 65 73 20 61 6e 64 20 63 6f 6d 6d 65 6e  lines and commen
11b0: 74 73 2e 29 0a 42 79 20 63 6f 6d 70 61 72 69 73  ts.).By comparis
11c0: 6f 6e 2c 20 74 68 65 20 70 72 6f 6a 65 63 74 20  on, the project 
11d0: 68 61 73 0a 3c 74 63 6c 3e 0a 68 64 5f 70 75 74  has.<tcl>.hd_put
11e0: 73 20 22 5b 65 78 70 72 20 7b 69 6e 74 28 24 73  s "[expr {int($s
11f0: 74 61 74 28 74 6f 74 61 6c 53 4c 4f 43 29 2f 24  tat(totalSLOC)/$
1200: 73 74 61 74 28 63 6f 72 65 53 4c 4f 43 29 29 7d  stat(coreSLOC))}
1210: 5d 20 74 69 6d 65 73 20 61 73 20 6d 75 63 68 22  ] times as much"
1220: 0a 3c 2f 74 63 6c 3e 0a 74 65 73 74 20 63 6f 64  .</tcl>.test cod
1230: 65 20 61 6e 64 20 74 65 73 74 20 73 63 72 69 70  e and test scrip
1240: 74 73 20 2d 20 0a 3c 74 63 6c 3e 4b 42 20 7b 24  ts - .<tcl>KB {$
1250: 73 74 61 74 28 74 6f 74 61 6c 53 4c 4f 43 29 7d  stat(totalSLOC)}
1260: 3c 2f 74 63 6c 3e 20 4b 53 4c 4f 43 2e 3c 2f 70  </tcl> KSLOC.</p
1270: 3e 0a 0a 3c 68 33 3e 31 2e 31 20 45 78 65 63 75  >..<h3>1.1 Execu
1280: 74 69 76 65 20 53 75 6d 6d 61 72 79 3c 2f 68 33  tive Summary</h3
1290: 3e 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e 20 54 68 72  >..<ul>.<li> Thr
12a0: 65 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79  ee independently
12b0: 20 64 65 76 65 6c 6f 70 65 64 20 74 65 73 74 20   developed test 
12c0: 68 61 72 6e 65 73 73 65 73 0a 3c 6c 69 3e 20 31  harnesses.<li> 1
12d0: 30 30 25 20 62 72 61 6e 63 68 20 74 65 73 74 20  00% branch test 
12e0: 63 6f 76 65 72 61 67 65 20 69 6e 20 61 6e 20 61  coverage in an a
12f0: 73 2d 64 65 70 6c 6f 79 65 64 20 63 6f 6e 66 69  s-deployed confi
1300: 67 75 72 61 74 69 6f 6e 0a 3c 6c 69 3e 20 4d 69  guration.<li> Mi
1310: 6c 6c 69 6f 6e 73 20 61 6e 64 20 6d 69 6c 6c 69  llions and milli
1320: 6f 6e 73 20 6f 66 20 74 65 73 74 20 63 61 73 65  ons of test case
1330: 73 0a 3c 6c 69 3e 20 4f 75 74 2d 6f 66 2d 6d 65  s.<li> Out-of-me
1340: 6d 6f 72 79 20 74 65 73 74 73 0a 3c 6c 69 3e 20  mory tests.<li> 
1350: 49 2f 4f 20 65 72 72 6f 72 20 74 65 73 74 73 0a  I/O error tests.
1360: 3c 6c 69 3e 20 43 72 61 73 68 20 61 6e 64 20 70  <li> Crash and p
1370: 6f 77 65 72 20 6c 6f 73 73 20 74 65 73 74 73 0a  ower loss tests.
1380: 3c 6c 69 3e 20 46 75 7a 7a 20 74 65 73 74 73 0a  <li> Fuzz tests.
1390: 3c 6c 69 3e 20 42 6f 75 6e 64 61 72 79 20 76 61  <li> Boundary va
13a0: 6c 75 65 20 74 65 73 74 73 0a 3c 6c 69 3e 20 44  lue tests.<li> D
13b0: 69 73 61 62 6c 65 64 20 6f 70 74 69 6d 69 7a 61  isabled optimiza
13c0: 74 69 6f 6e 20 74 65 73 74 73 0a 3c 6c 69 3e 20  tion tests.<li> 
13d0: 52 65 67 72 65 73 73 69 6f 6e 20 74 65 73 74 73  Regression tests
13e0: 0a 3c 6c 69 3e 20 4d 61 6c 66 6f 72 6d 65 64 20  .<li> Malformed 
13f0: 64 61 74 61 62 61 73 65 20 74 65 73 74 73 0a 3c  database tests.<
1400: 6c 69 3e 20 45 78 74 65 6e 73 69 76 65 20 75 73  li> Extensive us
1410: 65 20 6f 66 20 61 73 73 65 72 74 28 29 20 61 6e  e of assert() an
1420: 64 20 72 75 6e 2d 74 69 6d 65 20 63 68 65 63 6b  d run-time check
1430: 73 0a 3c 6c 69 3e 20 56 61 6c 67 72 69 6e 64 20  s.<li> Valgrind 
1440: 61 6e 61 6c 79 73 69 73 0a 3c 6c 69 3e 20 53 69  analysis.<li> Si
1450: 67 6e 65 64 2d 69 6e 74 65 67 65 72 20 6f 76 65  gned-integer ove
1460: 72 66 6c 6f 77 20 63 68 65 63 6b 73 0a 3c 2f 75  rflow checks.</u
1470: 6c 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67  l>..<tcl>hd_frag
1480: 6d 65 6e 74 20 7b 68 61 72 6e 65 73 73 65 73 7d  ment {harnesses}
1490: 20 7b 74 65 73 74 20 68 61 72 6e 65 73 73 7d 20   {test harness} 
14a0: 7b 74 68 72 65 65 20 74 65 73 74 20 68 61 72 6e  {three test harn
14b0: 65 73 73 65 73 7d 3c 2f 74 63 6c 3e 0a 3c 68 32  esses}</tcl>.<h2
14c0: 3e 32 2e 30 20 54 65 73 74 20 48 61 72 6e 65 73  >2.0 Test Harnes
14d0: 73 65 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65  ses</h2>..<p>The
14e0: 72 65 20 61 72 65 20 74 68 72 65 65 20 69 6e 64  re are three ind
14f0: 65 70 65 6e 64 65 6e 74 20 74 65 73 74 20 68 61  ependent test ha
1500: 72 6e 65 73 73 65 73 20 75 73 65 64 20 66 6f 72  rnesses used for
1510: 20 74 65 73 74 69 6e 67 20 74 68 65 20 0a 63 6f   testing the .co
1520: 72 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  re SQLite librar
1530: 79 2e 0a 45 61 63 68 20 74 65 73 74 20 68 61 72  y..Each test har
1540: 6e 65 73 73 20 69 73 20 64 65 73 69 67 6e 65 64  ness is designed
1550: 2c 20 6d 61 69 6e 74 61 69 6e 65 64 2c 20 61 6e  , maintained, an
1560: 64 20 6d 61 6e 61 67 65 64 20 73 65 70 61 72 61  d managed separa
1570: 74 65 6c 79 0a 66 72 6f 6d 20 74 68 65 20 6f 74  tely.from the ot
1580: 68 65 72 73 2e 0a 3c 2f 70 3e 0a 0a 3c 6f 6c 3e  hers..</p>..<ol>
1590: 0a 3c 6c 69 3e 3c 70 3e 0a 3c 74 63 6c 3e 68 64  .<li><p>.<tcl>hd
15a0: 5f 66 72 61 67 6d 65 6e 74 20 74 63 6c 20 7b 54  _fragment tcl {T
15b0: 43 4c 20 74 65 73 74 20 73 75 69 74 65 7d 3c 2f  CL test suite}</
15c0: 74 63 6c 3e 0a 54 68 65 20 3c 62 3e 54 43 4c 20  tcl>.The <b>TCL 
15d0: 54 65 73 74 73 3c 2f 62 3e 20 61 72 65 20 74 68  Tests</b> are th
15e0: 65 20 6f 6c 64 65 73 74 20 73 65 74 20 6f 66 20  e oldest set of 
15f0: 74 65 73 74 73 20 66 6f 72 20 53 51 4c 69 74 65  tests for SQLite
1600: 2e 20 20 0a 54 68 65 79 20 61 72 65 20 63 6f 6e  .  .They are con
1610: 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 73 61  tained in the sa
1620: 6d 65 20 73 6f 75 72 63 65 20 74 72 65 65 20 61  me source tree a
1630: 73 20 74 68 65 0a 53 51 4c 69 74 65 20 63 6f 72  s the.SQLite cor
1640: 65 20 61 6e 64 20 6c 69 6b 65 20 74 68 65 20 53  e and like the S
1650: 51 4c 69 74 65 20 63 6f 72 65 20 61 72 65 20 69  QLite core are i
1660: 6e 20 74 68 65 20 70 75 62 6c 69 63 20 64 6f 6d  n the public dom
1670: 61 69 6e 2e 20 20 54 68 65 0a 54 43 4c 20 74 65  ain.  The.TCL te
1680: 73 74 73 20 61 72 65 20 74 68 65 20 70 72 69 6d  sts are the prim
1690: 61 72 79 20 74 65 73 74 73 20 75 73 65 64 20 64  ary tests used d
16a0: 75 72 69 6e 67 20 64 65 76 65 6c 6f 70 6d 65 6e  uring developmen
16b0: 74 2e 0a 54 68 65 20 54 43 4c 20 74 65 73 74 73  t..The TCL tests
16c0: 20 61 72 65 20 77 72 69 74 74 65 6e 20 75 73 69   are written usi
16d0: 6e 67 20 74 68 65 20 0a 5b 68 74 74 70 3a 2f 2f  ng the .[http://
16e0: 77 77 77 2e 74 63 6c 2e 74 6b 2f 20 7c 20 54 43  www.tcl.tk/ | TC
16f0: 4c 20 73 63 72 69 70 74 69 6e 67 20 6c 61 6e 67  L scripting lang
1700: 75 61 67 65 5d 2e 0a 54 68 65 20 54 43 4c 20 74  uage]..The TCL t
1710: 65 73 74 20 68 61 72 6e 65 73 73 20 69 74 73 65  est harness itse
1720: 6c 66 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 3c  lf consists of <
1730: 74 63 6c 3e 4b 42 20 7b 24 73 74 61 74 28 74 63  tcl>KB {$stat(tc
1740: 6c 63 53 4c 4f 43 29 7d 3c 2f 74 63 6c 3e 20 4b  lcSLOC)}</tcl> K
1750: 53 4c 4f 43 20 0a 6f 66 20 43 20 63 6f 64 65 20  SLOC .of C code 
1760: 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 74  used to create t
1770: 68 65 20 54 43 4c 20 69 6e 74 65 72 66 61 63 65  he TCL interface
1780: 2e 20 20 54 68 65 20 74 65 73 74 20 73 63 72 69  .  The test scri
1790: 70 74 73 20 61 72 65 20 63 6f 6e 74 61 69 6e 65  pts are containe
17a0: 64 0a 69 6e 20 3c 74 63 6c 3e 4e 20 7b 24 73 74  d.in <tcl>N {$st
17b0: 61 74 28 74 63 6c 73 4e 46 69 6c 65 29 7d 3c 2f  at(tclsNFile)}</
17c0: 74 63 6c 3e 20 66 69 6c 65 73 20 74 6f 74 61 6c  tcl> files total
17d0: 69 6e 67 20 0a 3c 74 63 6c 3e 4d 69 42 20 7b 24  ing .<tcl>MiB {$
17e0: 73 74 61 74 28 74 63 6c 73 4e 42 79 74 65 29 7d  stat(tclsNByte)}
17f0: 3c 2f 74 63 6c 3e 4d 42 20 69 6e 20 73 69 7a 65  </tcl>MB in size
1800: 2e 20 20 54 68 65 72 65 20 61 72 65 0a 3c 74 63  .  There are.<tc
1810: 6c 3e 4e 20 7b 24 73 74 61 74 28 74 63 6c 4e 54  l>N {$stat(tclNT
1820: 65 73 74 29 7d 3c 2f 74 63 6c 3e 20 64 69 73 74  est)}</tcl> dist
1830: 69 6e 63 74 20 74 65 73 74 20 63 61 73 65 73 2c  inct test cases,
1840: 20 62 75 74 20 6d 61 6e 79 20 6f 66 20 74 68 65   but many of the
1850: 20 74 65 73 74 0a 63 61 73 65 73 20 61 72 65 20   test.cases are 
1860: 70 61 72 61 6d 65 74 65 72 69 7a 65 64 20 61 6e  parameterized an
1870: 64 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 74  d run multiple t
1880: 69 6d 65 73 20 28 77 69 74 68 20 64 69 66 66 65  imes (with diffe
1890: 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 29  rent parameters)
18a0: 0a 73 6f 20 74 68 61 74 20 6f 6e 20 61 20 66 75  .so that on a fu
18b0: 6c 6c 20 74 65 73 74 20 72 75 6e 2c 20 61 62 6f  ll test run, abo
18c0: 75 74 20 3c 74 63 6c 3e 4d 42 20 7b 24 73 74 61  ut <tcl>MB {$sta
18d0: 74 28 74 63 6c 4e 45 76 61 6c 29 7d 3c 2f 74 63  t(tclNEval)}</tc
18e0: 6c 3e 20 6d 69 6c 6c 69 6f 6e 20 0a 73 65 70 61  l> million .sepa
18f0: 72 61 74 65 20 74 65 73 74 73 20 61 72 65 20 70  rate tests are p
1900: 65 72 66 6f 72 6d 65 64 2e 0a 3c 2f 70 3e 0a 3c  erformed..</p>.<
1910: 2f 6c 69 3e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 54 68  /li>..<li><p>.Th
1920: 65 20 3c 62 3e 5b 54 48 33 5d 3c 2f 62 3e 20 74  e <b>[TH3]</b> t
1930: 65 73 74 20 68 61 72 6e 65 73 73 20 69 73 20 61  est harness is a
1940: 20 73 65 74 20 6f 66 20 70 72 6f 70 72 69 65 74   set of propriet
1950: 61 72 79 20 74 65 73 74 73 2c 20 77 72 69 74 74  ary tests, writt
1960: 65 6e 20 69 6e 0a 43 20 74 68 61 74 20 70 72 6f  en in.C that pro
1970: 76 69 64 65 20 31 30 30 25 20 62 72 61 6e 63 68  vide 100% branch
1980: 20 74 65 73 74 20 63 6f 76 65 72 61 67 65 20 28   test coverage (
1990: 61 6e 64 20 31 30 30 25 20 4d 43 2f 44 43 20 74  and 100% MC/DC t
19a0: 65 73 74 20 63 6f 76 65 72 61 67 65 29 20 74 6f  est coverage) to
19b0: 0a 74 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65  .the core SQLite
19c0: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 54   library.  The T
19d0: 48 33 20 74 65 73 74 73 20 61 72 65 20 64 65 73  H3 tests are des
19e0: 69 67 6e 65 64 20 74 6f 20 72 75 6e 0a 6f 6e 20  igned to run.on 
19f0: 65 6d 62 65 64 64 65 64 20 61 6e 64 20 73 70 65  embedded and spe
1a00: 63 69 61 6c 69 7a 65 64 20 70 6c 61 74 66 6f 72  cialized platfor
1a10: 6d 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6e 6f  ms that would no
1a20: 74 20 65 61 73 69 6c 79 20 73 75 70 70 6f 72 74  t easily support
1a30: 0a 54 43 4c 20 6f 72 20 6f 74 68 65 72 20 77 6f  .TCL or other wo
1a40: 72 6b 73 74 61 74 69 6f 6e 20 73 65 72 76 69 63  rkstation servic
1a50: 65 73 2e 20 20 54 48 33 20 74 65 73 74 73 20 75  es.  TH3 tests u
1a60: 73 65 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  se only the publ
1a70: 69 73 68 65 64 20 0a 53 51 4c 69 74 65 20 69 6e  ished .SQLite in
1a80: 74 65 72 66 61 63 65 73 2e 20 20 54 48 33 20 69  terfaces.  TH3 i
1a90: 73 20 66 72 65 65 20 74 6f 20 5b 53 51 4c 69 74  s free to [SQLit
1aa0: 65 20 43 6f 6e 73 6f 72 74 69 75 6d 5d 20 6d 65  e Consortium] me
1ab0: 6d 62 65 72 73 20 0a 61 6e 64 20 69 73 20 61 76  mbers .and is av
1ac0: 61 69 6c 61 62 6c 65 20 62 79 20 6c 69 63 65 6e  ailable by licen
1ad0: 73 65 20 74 6f 20 6f 74 68 65 72 73 2e 20 20 54  se to others.  T
1ae0: 48 33 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61  H3 consists of a
1af0: 62 6f 75 74 0a 3c 74 63 6c 3e 4d 42 20 7b 24 73  bout.<tcl>MB {$s
1b00: 74 61 74 28 74 68 33 4e 42 79 74 65 29 7d 3c 2f  tat(th3NByte)}</
1b10: 74 63 6c 3e 20 4d 42 20 6f 72 20 3c 74 63 6c 3e  tcl> MB or <tcl>
1b20: 4b 42 20 7b 24 73 74 61 74 28 74 68 33 53 4c 4f  KB {$stat(th3SLO
1b30: 43 29 7d 3c 2f 74 63 6c 3e 20 4b 53 4c 4f 43 0a  C)}</tcl> KSLOC.
1b40: 6f 66 20 43 20 63 6f 64 65 20 69 6d 70 6c 65 6d  of C code implem
1b50: 65 6e 74 69 6e 67 20 3c 74 63 6c 3e 4e 20 7b 24  enting <tcl>N {$
1b60: 73 74 61 74 28 74 68 33 4e 54 65 73 74 29 7d 3c  stat(th3NTest)}<
1b70: 2f 74 63 6c 3e 20 64 69 73 74 69 6e 63 74 20 74  /tcl> distinct t
1b80: 65 73 74 20 63 61 73 65 73 2e 0a 54 48 33 20 74  est cases..TH3 t
1b90: 65 73 74 73 20 61 72 65 20 68 65 61 76 69 6c 79  ests are heavily
1ba0: 20 70 61 72 61 6d 65 74 65 72 69 7a 65 64 2c 20   parameterized, 
1bb0: 74 68 6f 75 67 68 2c 20 73 6f 20 61 20 66 75 6c  though, so a ful
1bc0: 6c 2d 63 6f 76 65 72 61 67 65 20 74 65 73 74 20  l-coverage test 
1bd0: 72 75 6e 73 0a 61 62 6f 75 74 20 3c 74 63 6c 3e  runs.about <tcl>
1be0: 4d 42 20 7b 24 73 74 61 74 28 74 68 33 4e 45 43  MB {$stat(th3NEC
1bf0: 6f 76 29 7d 3c 2f 74 63 6c 3e 20 6d 69 6c 6c 69  ov)}</tcl> milli
1c00: 6f 6e 20 64 69 66 66 65 72 65 6e 74 20 74 65 73  on different tes
1c10: 74 0a 69 6e 73 74 61 6e 63 65 73 2e 20 20 54 68  t.instances.  Th
1c20: 65 20 63 61 73 65 73 20 74 68 61 74 20 70 72 6f  e cases that pro
1c30: 76 69 64 65 20 31 30 30 25 20 62 72 61 6e 63 68  vide 100% branch
1c40: 20 74 65 73 74 20 63 6f 76 65 72 61 67 65 20 63   test coverage c
1c50: 6f 6e 73 74 69 74 75 74 65 0a 61 20 73 75 62 73  onstitute.a subs
1c60: 65 74 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  et of the total 
1c70: 54 48 33 20 74 65 73 74 20 73 75 69 74 65 2e 20  TH3 test suite. 
1c80: 20 41 20 73 6f 61 6b 20 74 65 73 74 0a 70 72 69   A soak test.pri
1c90: 6f 72 20 74 6f 20 72 65 6c 65 61 73 65 20 64 6f  or to release do
1ca0: 65 73 20 68 75 6e 64 72 65 64 73 20 6f 66 20 6d  es hundreds of m
1cb0: 69 6c 6c 69 6f 6e 73 20 6f 66 20 74 65 73 74 73  illions of tests
1cc0: 2e 0a 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  ..Additional inf
1cd0: 6f 72 6d 61 74 69 6f 6e 20 6f 6e 20 54 48 33 20  ormation on TH3 
1ce0: 69 73 20 5b 54 48 33 20 7c 20 61 76 61 69 6c 61  is [TH3 | availa
1cf0: 62 6c 65 20 73 65 70 61 72 61 74 65 6c 79 5d 2e  ble separately].
1d00: 3c 2f 70 3e 3c 2f 6c 69 3e 0a 0a 3c 6c 69 3e 3c  </p></li>..<li><
1d10: 70 3e 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  p>.<tcl>hd_fragm
1d20: 65 6e 74 20 73 6c 74 20 7b 53 4c 54 7d 20 7b 53  ent slt {SLT} {S
1d30: 51 4c 20 4c 6f 67 69 63 20 54 65 73 74 73 7d 3c  QL Logic Tests}<
1d40: 2f 74 63 6c 3e 0a 54 68 65 20 3c 61 20 68 72 65  /tcl>.The <a hre
1d50: 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71  f="http://www.sq
1d60: 6c 69 74 65 2e 6f 72 67 2f 73 71 6c 6c 6f 67 69  lite.org/sqllogi
1d70: 63 74 65 73 74 22 3e 3c 62 3e 53 51 4c 20 4c 6f  ctest"><b>SQL Lo
1d80: 67 69 63 20 54 65 73 74 3c 2f 62 3e 3c 2f 61 3e  gic Test</b></a>
1d90: 0a 6f 72 20 53 4c 54 20 74 65 73 74 20 68 61 72  .or SLT test har
1da0: 6e 65 73 73 20 69 73 20 75 73 65 64 20 74 6f 20  ness is used to 
1db0: 72 75 6e 20 68 75 67 65 20 6e 75 6d 62 65 72 73  run huge numbers
1dc0: 0a 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .of SQL statemen
1dd0: 74 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 20  ts against both 
1de0: 53 51 4c 69 74 65 20 61 6e 64 20 73 65 76 65 72  SQLite and sever
1df0: 61 6c 20 6f 74 68 65 72 20 53 51 4c 20 64 61 74  al other SQL dat
1e00: 61 62 61 73 65 20 65 6e 67 69 6e 65 73 0a 61 6e  abase engines.an
1e10: 64 20 76 65 72 69 66 79 20 74 68 61 74 20 74 68  d verify that th
1e20: 65 79 20 61 6c 6c 20 67 65 74 20 74 68 65 20 73  ey all get the s
1e30: 61 6d 65 20 61 6e 73 77 65 72 73 2e 20 20 53 4c  ame answers.  SL
1e40: 54 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6d 70  T currently comp
1e50: 61 72 65 73 0a 53 51 4c 69 74 65 20 61 67 61 69  ares.SQLite agai
1e60: 6e 73 74 20 50 6f 73 74 67 72 65 53 51 4c 2c 20  nst PostgreSQL, 
1e70: 4d 79 53 51 4c 2c 20 4d 69 63 72 6f 73 6f 66 74  MySQL, Microsoft
1e80: 20 53 51 4c 20 53 65 72 76 65 72 2c 20 61 6e 64   SQL Server, and
1e90: 20 4f 72 61 63 6c 65 20 31 30 67 2e 0a 53 4c 54   Oracle 10g..SLT
1ea0: 20 72 75 6e 73 20 3c 74 63 6c 3e 4d 42 20 7b 24   runs <tcl>MB {$
1eb0: 73 74 61 74 28 73 6c 74 4e 54 65 73 74 29 7d 3c  stat(sltNTest)}<
1ec0: 2f 74 63 6c 3e 20 6d 69 6c 6c 69 6f 6e 20 71 75  /tcl> million qu
1ed0: 65 72 69 65 73 20 63 6f 6d 70 72 69 73 69 6e 67  eries comprising
1ee0: 0a 3c 74 63 6c 3e 47 42 20 7b 24 73 74 61 74 28  .<tcl>GB {$stat(
1ef0: 73 6c 74 73 4e 42 79 74 65 29 7d 3c 2f 74 63 6c  sltsNByte)}</tcl
1f00: 3e 47 42 20 6f 66 20 74 65 73 74 20 64 61 74 61  >GB of test data
1f10: 2e 0a 3c 2f 70 3e 3c 2f 6c 69 3e 0a 3c 2f 6f 6c  ..</p></li>.</ol
1f20: 3e 0a 0a 3c 70 3e 41 6c 6c 20 6f 66 20 74 68 65  >..<p>All of the
1f30: 20 74 65 73 74 73 20 61 62 6f 76 65 20 6d 75 73   tests above mus
1f40: 74 20 72 75 6e 20 73 75 63 63 65 73 73 66 75 6c  t run successful
1f50: 6c 79 2c 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 20  ly, on multiple 
1f60: 70 6c 61 74 66 6f 72 6d 73 0a 61 6e 64 20 75 6e  platforms.and un
1f70: 64 65 72 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d  der multiple com
1f80: 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 66 69 67  pile-time config
1f90: 75 72 61 74 69 6f 6e 73 2c 0a 62 65 66 6f 72 65  urations,.before
1fa0: 20 65 61 63 68 20 72 65 6c 65 61 73 65 20 6f 66   each release of
1fb0: 20 53 51 4c 69 74 65 2e 3c 2f 70 3e 0a 0a 3c 70   SQLite.</p>..<p
1fc0: 3e 50 72 69 6f 72 20 74 6f 20 65 61 63 68 20 63  >Prior to each c
1fd0: 68 65 63 6b 2d 69 6e 20 74 6f 20 74 68 65 20 53  heck-in to the S
1fe0: 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65  QLite source tre
1ff0: 65 2c 20 64 65 76 65 6c 6f 70 65 72 73 0a 74 79  e, developers.ty
2000: 70 69 63 61 6c 6c 79 20 72 75 6e 20 61 20 73 75  pically run a su
2010: 62 73 65 74 20 28 63 61 6c 6c 65 64 20 22 76 65  bset (called "ve
2020: 72 79 71 75 69 63 6b 22 29 20 6f 66 20 74 68 65  ryquick") of the
2030: 20 54 63 6c 20 74 65 73 74 73 0a 63 6f 6e 73 69   Tcl tests.consi
2040: 73 74 69 6e 67 20 6f 66 20 61 62 6f 75 74 20 0a  sting of about .
2050: 3c 74 63 6c 3e 4b 42 20 7b 24 73 74 61 74 28 76  <tcl>KB {$stat(v
2060: 71 4e 45 76 61 6c 29 7d 3c 2f 74 63 6c 3e 20 74  qNEval)}</tcl> t
2070: 68 6f 75 73 61 6e 64 20 74 65 73 74 20 63 61 73  housand test cas
2080: 65 73 2e 0a 54 68 65 20 76 65 72 79 71 75 69 63  es..The veryquic
2090: 6b 20 74 65 73 74 73 20 69 6e 63 6c 75 64 65 20  k tests include 
20a0: 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
20b0: 74 20 74 68 65 20 61 6e 6f 6d 61 6c 79 2c 20 66  t the anomaly, f
20c0: 75 7a 7a 2c 20 61 6e 64 20 0a 73 6f 61 6b 20 74  uzz, and .soak t
20d0: 65 73 74 73 2e 20 20 54 68 65 20 69 64 65 61 20  ests.  The idea 
20e0: 62 65 68 69 6e 64 20 74 68 65 20 76 65 72 79 71  behind the veryq
20f0: 75 69 63 6b 20 74 65 73 74 73 20 61 72 65 20 74  uick tests are t
2100: 68 61 74 20 74 68 65 79 20 61 72 65 0a 73 75 66  hat they are.suf
2110: 66 69 63 69 65 6e 74 20 74 6f 20 63 61 74 63 68  ficient to catch
2120: 20 6d 6f 73 74 20 65 72 72 6f 72 73 2c 20 62 75   most errors, bu
2130: 74 20 61 6c 73 6f 20 72 75 6e 20 69 6e 20 6f 6e  t also run in on
2140: 6c 79 20 61 20 66 65 77 20 6d 69 6e 75 74 65 73  ly a few minutes
2150: 0a 69 6e 73 74 65 61 64 20 6f 66 20 61 20 66 65  .instead of a fe
2160: 77 20 68 6f 75 72 73 2e 3c 2f 70 3e 0a 0a 3c 74  w hours.</p>..<t
2170: 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 61  cl>hd_fragment a
2180: 6e 6f 6d 6f 6c 79 3c 2f 74 63 6c 3e 0a 3c 68 32  nomoly</tcl>.<h2
2190: 3e 33 2e 30 20 41 6e 6f 6d 61 6c 79 20 54 65 73  >3.0 Anomaly Tes
21a0: 74 69 6e 67 3c 2f 68 32 3e 0a 0a 3c 70 3e 41 6e  ting</h2>..<p>An
21b0: 6f 6d 61 6c 79 20 74 65 73 74 73 20 61 72 65 20  omaly tests are 
21c0: 74 65 73 74 73 20 64 65 73 69 67 6e 65 64 20 74  tests designed t
21d0: 6f 20 76 65 72 69 66 79 20 74 68 65 20 63 6f 72  o verify the cor
21e0: 72 65 63 74 20 62 65 68 61 76 69 6f 72 0a 6f 66  rect behavior.of
21f0: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 73 6f 6d   SQLite when som
2200: 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ething goes wron
2210: 67 2e 20 20 49 74 20 69 73 20 28 72 65 6c 61 74  g.  It is (relat
2220: 69 76 65 6c 79 29 20 65 61 73 79 20 74 6f 20 62  ively) easy to b
2230: 75 69 6c 64 0a 61 6e 20 53 51 4c 20 64 61 74 61  uild.an SQL data
2240: 62 61 73 65 20 65 6e 67 69 6e 65 20 74 68 61 74  base engine that
2250: 20 62 65 68 61 76 65 73 20 63 6f 72 72 65 63 74   behaves correct
2260: 6c 79 20 6f 6e 20 77 65 6c 6c 2d 66 6f 72 6d 65  ly on well-forme
2270: 64 20 69 6e 70 75 74 73 0a 6f 6e 20 61 20 66 75  d inputs.on a fu
2280: 6c 6c 79 20 66 75 6e 63 74 69 6f 6e 61 6c 20 63  lly functional c
2290: 6f 6d 70 75 74 65 72 2e 20 20 49 74 20 69 73 20  omputer.  It is 
22a0: 6d 6f 72 65 20 64 69 66 66 69 63 75 6c 74 20 74  more difficult t
22b0: 6f 20 62 75 69 6c 64 20 61 20 73 79 73 74 65 6d  o build a system
22c0: 0a 74 68 61 74 20 72 65 73 70 6f 6e 64 73 20 73  .that responds s
22d0: 61 6e 65 6c 79 20 74 6f 20 69 6e 76 61 6c 69 64  anely to invalid
22e0: 20 69 6e 70 75 74 73 20 61 6e 64 20 63 6f 6e 74   inputs and cont
22f0: 69 6e 75 65 73 20 74 6f 20 66 75 6e 63 74 69 6f  inues to functio
2300: 6e 20 66 6f 6c 6c 6f 77 69 6e 67 0a 73 79 73 74  n following.syst
2310: 65 6d 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 73 2e  em malfunctions.
2320: 20 20 54 68 65 20 61 6e 6f 6d 61 6c 79 20 74 65    The anomaly te
2330: 73 74 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  sts are designed
2340: 20 74 6f 20 76 65 72 69 66 79 20 74 68 65 20 6c   to verify the l
2350: 61 74 74 65 72 0a 62 65 68 61 76 69 6f 72 2e 3c  atter.behavior.<
2360: 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  /p>..<tcl>hd_fra
2370: 67 6d 65 6e 74 20 6f 6f 6d 74 65 73 74 69 6e 67  gment oomtesting
2380: 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 33 2e 31 20 4f  </tcl>.<h3>3.1 O
2390: 75 74 2d 4f 66 2d 4d 65 6d 6f 72 79 20 54 65 73  ut-Of-Memory Tes
23a0: 74 69 6e 67 3c 2f 68 33 3e 0a 0a 3c 70 3e 53 51  ting</h3>..<p>SQ
23b0: 4c 69 74 65 2c 20 6c 69 6b 65 20 61 6c 6c 20 53  Lite, like all S
23c0: 51 4c 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  QL database engi
23d0: 6e 65 73 2c 20 6d 61 6b 65 73 20 65 78 74 65 6e  nes, makes exten
23e0: 73 69 76 65 20 75 73 65 20 6f 66 0a 6d 61 6c 6c  sive use of.mall
23f0: 6f 63 28 29 20 20 28 53 65 65 20 74 68 65 20 73  oc()  (See the s
2400: 65 70 61 72 61 74 65 20 72 65 70 6f 72 74 20 6f  eparate report o
2410: 6e 0a 5b 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  n.[memory alloca
2420: 74 69 6f 6e 20 7c 20 64 79 6e 61 6d 69 63 20 6d  tion | dynamic m
2430: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2440: 20 69 6e 20 53 51 4c 69 74 65 5d 20 66 6f 72 0a   in SQLite] for.
2450: 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69  additional detai
2460: 6c 2e 29 0a 4f 6e 20 73 65 72 76 65 72 73 20 61  l.).On servers a
2470: 6e 64 20 77 6f 72 6b 73 74 61 74 69 6f 6e 73 2c  nd workstations,
2480: 20 6d 61 6c 6c 6f 63 28 29 20 6e 65 76 65 72 20   malloc() never 
2490: 66 61 69 6c 73 20 69 6e 20 70 72 61 63 74 69 63  fails in practic
24a0: 65 20 61 6e 64 20 73 6f 20 63 6f 72 72 65 63 74  e and so correct
24b0: 0a 68 61 6e 64 6c 69 6e 67 20 6f 66 20 6f 75 74  .handling of out
24c0: 2d 6f 66 2d 6d 65 6d 6f 72 79 20 28 4f 4f 4d 29  -of-memory (OOM)
24d0: 20 65 72 72 6f 72 73 20 69 73 20 6e 6f 74 20 70   errors is not p
24e0: 61 72 74 69 63 75 6c 61 72 6c 79 20 69 6d 70 6f  articularly impo
24f0: 72 74 61 6e 74 2e 0a 42 75 74 20 6f 6e 20 65 6d  rtant..But on em
2500: 62 65 64 64 65 64 20 64 65 76 69 63 65 73 2c 20  bedded devices, 
2510: 4f 4f 4d 20 65 72 72 6f 72 73 20 61 72 65 20 66  OOM errors are f
2520: 72 69 67 68 74 65 6e 69 6e 67 6c 79 20 63 6f 6d  righteningly com
2530: 6d 6f 6e 20 61 6e 64 20 73 69 6e 63 65 0a 53 51  mon and since.SQ
2540: 4c 69 74 65 20 69 73 20 66 72 65 71 75 65 6e 74  Lite is frequent
2550: 6c 79 20 75 73 65 64 20 6f 6e 20 65 6d 62 65 64  ly used on embed
2560: 64 65 64 20 64 65 76 69 63 65 73 2c 20 69 74 20  ded devices, it 
2570: 69 73 20 69 6d 70 6f 72 74 61 6e 74 20 74 68 61  is important tha
2580: 74 0a 53 51 4c 69 74 65 20 62 65 20 61 62 6c 65  t.SQLite be able
2590: 20 74 6f 20 67 72 61 63 65 66 75 6c 6c 79 20 68   to gracefully h
25a0: 61 6e 64 6c 65 20 4f 4f 4d 20 65 72 72 6f 72 73  andle OOM errors
25b0: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 4f 4f 4d 20 74 65  .</p>..<p>OOM te
25c0: 73 74 69 6e 67 20 69 73 20 61 63 63 6f 6d 70 6c  sting is accompl
25d0: 69 73 68 65 64 20 62 79 20 73 69 6d 75 6c 61 74  ished by simulat
25e0: 69 6e 67 20 4f 4f 4d 20 65 72 72 6f 72 73 2e 0a  ing OOM errors..
25f0: 53 51 4c 69 74 65 20 61 6c 6c 6f 77 73 20 61 6e  SQLite allows an
2600: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
2610: 73 75 62 73 74 69 74 75 74 65 20 61 6e 20 61 6c  substitute an al
2620: 74 65 72 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  ternative malloc
2630: 28 29 0a 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ().implementatio
2640: 6e 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  n using the [sql
2650: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
2660: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
2670: 4f 43 5d 2c 2e 2e 2e 29 0a 69 6e 74 65 72 66 61  OC],...).interfa
2680: 63 65 2e 20 20 54 68 65 20 54 43 4c 20 61 6e 64  ce.  The TCL and
2690: 20 54 48 33 20 74 65 73 74 20 68 61 72 6e 65 73   TH3 test harnes
26a0: 73 65 73 20 61 72 65 20 62 6f 74 68 20 63 61 70  ses are both cap
26b0: 61 62 6c 65 20 6f 66 0a 69 6e 73 65 72 74 69 6e  able of.insertin
26c0: 67 20 61 20 6d 6f 64 69 66 69 65 64 20 76 65 72  g a modified ver
26d0: 73 69 6f 6e 20 6f 66 20 6d 61 6c 6c 6f 63 28 29  sion of malloc()
26e0: 20 74 68 61 74 20 63 61 6e 20 62 65 20 72 69 67   that can be rig
26f0: 67 65 64 20 74 6f 20 66 61 69 6c 20 0a 61 66 74  ged to fail .aft
2700: 65 72 20 61 20 63 65 72 74 61 69 6e 20 6e 75 6d  er a certain num
2710: 62 65 72 20 6f 66 20 61 6c 6c 6f 63 61 74 69 6f  ber of allocatio
2720: 6e 73 2e 20 20 54 68 65 73 65 20 69 6e 73 74 72  ns.  These instr
2730: 75 6d 65 6e 74 65 64 20 6d 61 6c 6c 6f 63 73 0a  umented mallocs.
2740: 63 61 6e 20 62 65 20 73 65 74 20 74 6f 20 66 61  can be set to fa
2750: 69 6c 20 6f 6e 6c 79 20 6f 6e 63 65 20 61 6e 64  il only once and
2760: 20 74 68 65 6e 20 73 74 61 72 74 20 77 6f 72 6b   then start work
2770: 69 6e 67 20 61 67 61 69 6e 2c 20 6f 72 20 74 6f  ing again, or to
2780: 0a 63 6f 6e 74 69 6e 75 65 20 66 61 69 6c 69 6e  .continue failin
2790: 67 20 61 66 74 65 72 20 74 68 65 20 66 69 72 73  g after the firs
27a0: 74 20 66 61 69 6c 75 72 65 2e 20 20 4f 4f 4d 20  t failure.  OOM 
27b0: 74 65 73 74 73 20 61 72 65 20 64 6f 6e 65 20 69  tests are done i
27c0: 6e 20 61 0a 6c 6f 6f 70 2e 20 20 4f 6e 20 74 68  n a.loop.  On th
27d0: 65 20 66 69 72 73 74 20 69 74 65 72 61 74 69 6f  e first iteratio
27e0: 6e 20 6f 66 20 74 68 65 20 6c 6f 6f 70 2c 20 74  n of the loop, t
27f0: 68 65 20 69 6e 73 74 72 75 6d 65 6e 74 65 64 20  he instrumented 
2800: 6d 61 6c 6c 6f 63 0a 69 73 20 72 69 67 67 65 64  malloc.is rigged
2810: 20 74 6f 20 66 61 69 6c 20 6f 6e 20 74 68 65 20   to fail on the 
2820: 66 69 72 73 74 20 61 6c 6c 6f 63 61 74 69 6f 6e  first allocation
2830: 2e 20 20 54 68 65 6e 20 73 6f 6d 65 20 53 51 4c  .  Then some SQL
2840: 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 0a 69 73  ite operation.is
2850: 20 63 61 72 72 69 65 64 20 6f 75 74 20 61 6e 64   carried out and
2860: 20 63 68 65 63 6b 73 20 61 72 65 20 64 6f 6e 65   checks are done
2870: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 53 51   to make sure SQ
2880: 4c 69 74 65 20 68 61 6e 64 6c 65 64 20 74 68 65  Lite handled the
2890: 0a 4f 4f 4d 20 65 72 72 6f 72 20 63 6f 72 72 65  .OOM error corre
28a0: 63 74 6c 79 2e 20 20 54 68 65 6e 20 74 68 65 20  ctly.  Then the 
28b0: 74 69 6d 65 2d 74 6f 2d 66 61 69 6c 75 72 65 20  time-to-failure 
28c0: 63 6f 75 6e 74 65 72 0a 6f 6e 20 74 68 65 20 69  counter.on the i
28d0: 6e 73 74 72 75 6d 65 6e 74 65 64 20 6d 61 6c 6c  nstrumented mall
28e0: 6f 63 20 69 73 20 69 6e 63 72 65 61 73 65 64 20  oc is increased 
28f0: 62 79 20 6f 6e 65 20 61 6e 64 20 74 68 65 20 74  by one and the t
2900: 65 73 74 20 69 73 0a 72 65 70 65 61 74 65 64 2e  est is.repeated.
2910: 20 20 54 68 65 20 6c 6f 6f 70 20 63 6f 6e 74 69    The loop conti
2920: 6e 75 65 73 20 75 6e 74 69 6c 20 74 68 65 20 65  nues until the e
2930: 6e 74 69 72 65 20 6f 70 65 72 61 74 69 6f 6e 20  ntire operation 
2940: 72 75 6e 73 20 74 6f 0a 63 6f 6d 70 6c 65 74 69  runs to.completi
2950: 6f 6e 20 77 69 74 68 6f 75 74 20 65 76 65 72 20  on without ever 
2960: 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 20 73  encountering a s
2970: 69 6d 75 6c 61 74 65 64 20 4f 4f 4d 20 66 61 69  imulated OOM fai
2980: 6c 75 72 65 2e 0a 54 65 73 74 73 20 6c 69 6b 65  lure..Tests like
2990: 20 74 68 69 73 20 61 72 65 20 72 75 6e 20 74 77   this are run tw
29a0: 69 63 65 2c 20 6f 6e 63 65 20 77 69 74 68 20 74  ice, once with t
29b0: 68 65 20 69 6e 73 74 72 75 6d 65 6e 74 65 64 20  he instrumented 
29c0: 6d 61 6c 6c 6f 63 0a 73 65 74 20 74 6f 20 66 61  malloc.set to fa
29d0: 69 6c 20 6f 6e 6c 79 20 6f 6e 63 65 2c 20 61 6e  il only once, an
29e0: 64 20 61 67 61 69 6e 20 77 69 74 68 20 74 68 65  d again with the
29f0: 20 69 6e 73 74 72 75 6d 65 6e 74 65 64 20 6d 61   instrumented ma
2a00: 6c 6c 6f 63 20 73 65 74 0a 74 6f 20 66 61 69 6c  lloc set.to fail
2a10: 20 63 6f 6e 74 69 6e 75 6f 75 73 6c 79 20 61 66   continuously af
2a20: 74 65 72 20 74 68 65 20 66 69 72 73 74 20 66 61  ter the first fa
2a30: 69 6c 75 72 65 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c  ilure.</p>..<tcl
2a40: 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 69 6f 65  >hd_fragment ioe
2a50: 72 72 74 65 73 74 69 6e 67 3c 2f 74 63 6c 3e 0a  rrtesting</tcl>.
2a60: 3c 68 33 3e 33 2e 32 20 49 2f 4f 20 45 72 72 6f  <h3>3.2 I/O Erro
2a70: 72 20 54 65 73 74 69 6e 67 3c 2f 68 33 3e 0a 0a  r Testing</h3>..
2a80: 3c 70 3e 49 2f 4f 20 65 72 72 6f 72 20 74 65 73  <p>I/O error tes
2a90: 74 69 6e 67 20 73 65 65 6b 73 20 74 6f 20 76 65  ting seeks to ve
2aa0: 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
2ab0: 20 72 65 73 70 6f 6e 64 73 20 73 61 6e 65 6c 79   responds sanely
2ac0: 0a 74 6f 20 66 61 69 6c 65 64 20 49 2f 4f 20 6f  .to failed I/O o
2ad0: 70 65 72 61 74 69 6f 6e 73 2e 20 20 49 2f 4f 20  perations.  I/O 
2ae0: 65 72 72 6f 72 73 20 6d 69 67 68 74 20 72 65 73  errors might res
2af0: 75 6c 74 20 66 72 6f 6d 20 61 20 66 75 6c 6c 20  ult from a full 
2b00: 64 69 73 6b 20 64 72 69 76 65 2c 0a 6d 61 6c 66  disk drive,.malf
2b10: 75 6e 63 74 69 6f 6e 69 6e 67 20 64 69 73 6b 20  unctioning disk 
2b20: 68 61 72 64 77 61 72 65 2c 20 6e 65 74 77 6f 72  hardware, networ
2b30: 6b 20 6f 75 74 61 67 65 73 20 77 68 65 6e 20 75  k outages when u
2b40: 73 69 6e 67 20 61 20 6e 65 74 77 6f 72 6b 0a 66  sing a network.f
2b50: 69 6c 65 20 73 79 73 74 65 6d 2c 20 73 79 73 74  ile system, syst
2b60: 65 6d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  em configuration
2b70: 20 6f 72 20 70 65 72 6d 69 73 73 69 6f 6e 20 63   or permission c
2b80: 68 61 6e 67 65 73 20 74 68 61 74 20 6f 63 63 75  hanges that occu
2b90: 72 20 69 6e 20 74 68 65 20 0a 6d 69 64 64 6c 65  r in the .middle
2ba0: 20 6f 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61   of an SQL opera
2bb0: 74 69 6f 6e 2c 20 6f 72 20 6f 74 68 65 72 20 68  tion, or other h
2bc0: 61 72 64 77 61 72 65 20 6f 72 20 6f 70 65 72 61  ardware or opera
2bd0: 74 69 6e 67 20 73 79 73 74 65 6d 20 0a 6d 61 6c  ting system .mal
2be0: 66 75 6e 63 74 69 6f 6e 73 2e 20 20 57 68 61 74  functions.  What
2bf0: 65 76 65 72 20 74 68 65 20 63 61 75 73 65 2c 20  ever the cause, 
2c00: 69 74 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 20  it is important 
2c10: 74 68 61 74 20 53 51 4c 69 74 65 20 62 65 20 61  that SQLite be a
2c20: 62 6c 65 0a 74 6f 20 72 65 73 70 6f 6e 64 20 63  ble.to respond c
2c30: 6f 72 72 65 63 74 6c 79 20 74 6f 20 74 68 65 73  orrectly to thes
2c40: 65 20 65 72 72 6f 72 73 20 61 6e 64 20 49 2f 4f  e errors and I/O
2c50: 20 65 72 72 6f 72 20 74 65 73 74 69 6e 67 20 73   error testing s
2c60: 65 65 6b 73 20 74 6f 0a 76 65 72 69 66 79 20 74  eeks to.verify t
2c70: 68 61 74 20 69 74 20 64 6f 65 73 2e 3c 2f 70 3e  hat it does.</p>
2c80: 0a 0a 3c 70 3e 49 2f 4f 20 65 72 72 6f 72 20 74  ..<p>I/O error t
2c90: 65 73 74 69 6e 67 20 69 73 20 73 69 6d 69 6c 61  esting is simila
2ca0: 72 20 69 6e 20 63 6f 6e 63 65 70 74 20 74 6f 20  r in concept to 
2cb0: 4f 4f 4d 20 74 65 73 74 69 6e 67 3b 20 49 2f 4f  OOM testing; I/O
2cc0: 20 65 72 72 6f 72 73 0a 61 72 65 20 73 69 6d 75   errors.are simu
2cd0: 6c 61 74 65 64 20 61 6e 64 20 63 68 65 63 6b 73  lated and checks
2ce0: 20 61 72 65 20 6d 61 64 65 20 74 6f 20 76 65 72   are made to ver
2cf0: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
2d00: 72 65 73 70 6f 6e 64 73 0a 63 6f 72 72 65 63 74  responds.correct
2d10: 6c 79 20 74 6f 20 74 68 65 20 73 69 6d 75 6c 61  ly to the simula
2d20: 74 65 64 20 65 72 72 6f 72 73 2e 20 20 49 2f 4f  ted errors.  I/O
2d30: 20 65 72 72 6f 72 73 20 61 72 65 20 73 69 6d 75   errors are simu
2d40: 6c 61 74 65 64 20 69 6e 20 62 6f 74 68 0a 74 68  lated in both.th
2d50: 65 20 54 43 4c 20 61 6e 64 20 54 48 33 20 74 65  e TCL and TH3 te
2d60: 73 74 20 68 61 72 6e 65 73 73 65 73 20 62 79 20  st harnesses by 
2d70: 69 6e 73 65 72 74 69 6e 67 20 61 20 6e 65 77 0a  inserting a new.
2d80: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
2d90: 69 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74  irtual File Syst
2da0: 65 6d 20 6f 62 6a 65 63 74 5d 20 74 68 61 74 20  em object] that 
2db0: 69 73 20 73 70 65 63 69 61 6c 6c 79 20 72 69 67  is specially rig
2dc0: 67 65 64 0a 74 6f 20 73 69 6d 75 6c 61 74 65 20  ged.to simulate 
2dd0: 61 6e 20 49 2f 4f 20 65 72 72 6f 72 20 61 66 74  an I/O error aft
2de0: 65 72 20 61 20 73 65 74 20 6e 75 6d 62 65 72 20  er a set number 
2df0: 6f 66 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  of I/O operation
2e00: 73 2e 0a 41 73 20 77 69 74 68 20 4f 4f 4d 20 65  s..As with OOM e
2e10: 72 72 6f 72 20 74 65 73 74 69 6e 67 2c 20 74 68  rror testing, th
2e20: 65 20 49 2f 4f 20 65 72 72 6f 72 20 73 69 6d 75  e I/O error simu
2e30: 6c 61 74 6f 72 73 20 63 61 6e 20 62 65 20 73 65  lators can be se
2e40: 74 20 74 6f 0a 66 61 69 6c 20 6a 75 73 74 20 6f  t to.fail just o
2e50: 6e 63 65 2c 20 6f 72 20 74 6f 20 66 61 69 6c 20  nce, or to fail 
2e60: 63 6f 6e 74 69 6e 75 6f 75 73 6c 79 20 61 66 74  continuously aft
2e70: 65 72 20 74 68 65 20 66 69 72 73 74 20 66 61 69  er the first fai
2e80: 6c 75 72 65 2e 0a 54 65 73 74 73 20 61 72 65 20  lure..Tests are 
2e90: 72 75 6e 20 69 6e 20 61 20 6c 6f 6f 70 2c 20 73  run in a loop, s
2ea0: 6c 6f 77 6c 79 20 69 6e 63 72 65 61 73 69 6e 67  lowly increasing
2eb0: 20 74 68 65 20 70 6f 69 6e 74 20 6f 66 20 66 61   the point of fa
2ec0: 69 6c 75 72 65 20 75 6e 74 69 6c 0a 74 68 65 20  ilure until.the 
2ed0: 74 65 73 74 20 63 61 73 65 20 72 75 6e 73 20 74  test case runs t
2ee0: 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 77 69 74  o completion wit
2ef0: 68 6f 75 74 20 65 72 72 6f 72 2e 20 20 54 68 65  hout error.  The
2f00: 20 6c 6f 6f 70 20 69 73 20 72 75 6e 20 74 77 69   loop is run twi
2f10: 63 65 2c 0a 6f 6e 63 65 20 77 69 74 68 20 74 68  ce,.once with th
2f20: 65 20 49 2f 4f 20 65 72 72 6f 72 20 73 69 6d 75  e I/O error simu
2f30: 6c 61 74 6f 72 20 73 65 74 20 74 6f 20 73 69 6d  lator set to sim
2f40: 75 6c 61 74 65 20 6f 6e 6c 79 20 61 20 73 69 6e  ulate only a sin
2f50: 67 6c 65 20 66 61 69 6c 75 72 65 0a 61 6e 64 20  gle failure.and 
2f60: 61 20 73 65 63 6f 6e 64 20 74 69 6d 65 20 77 69  a second time wi
2f70: 74 68 20 69 74 20 73 65 74 20 74 6f 20 66 61 69  th it set to fai
2f80: 6c 20 61 6c 6c 20 49 2f 4f 20 6f 70 65 72 61 74  l all I/O operat
2f90: 69 6f 6e 73 20 61 66 74 65 72 20 74 68 65 20 66  ions after the f
2fa0: 69 72 73 74 0a 66 61 69 6c 75 72 65 2e 3c 2f 70  irst.failure.</p
2fb0: 3e 0a 0a 3c 70 3e 49 6e 20 49 2f 4f 20 65 72 72  >..<p>In I/O err
2fc0: 6f 72 20 74 65 73 74 73 2c 20 61 66 74 65 72 20  or tests, after 
2fd0: 74 68 65 20 49 2f 4f 20 65 72 72 6f 72 20 73 69  the I/O error si
2fe0: 6d 75 6c 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  mulation failure
2ff0: 20 6d 65 63 68 61 6e 69 73 6d 0a 69 73 20 64 69   mechanism.is di
3000: 73 61 62 6c 65 64 2c 20 74 68 65 20 64 61 74 61  sabled, the data
3010: 62 61 73 65 20 69 73 20 65 78 61 6d 69 6e 65 64  base is examined
3020: 20 75 73 69 6e 67 0a 5b 50 52 41 47 4d 41 20 69   using.[PRAGMA i
3030: 6e 74 65 67 72 69 74 79 5f 63 68 65 63 6b 5d 20  ntegrity_check] 
3040: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
3050: 74 20 74 68 65 20 49 2f 4f 20 65 72 72 6f 72 20  t the I/O error 
3060: 68 61 73 20 6e 6f 74 0a 69 6e 74 72 6f 64 75 63  has not.introduc
3070: 65 64 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ed database corr
3080: 75 70 74 69 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 74 63  uption.</p>..<tc
3090: 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 63 72  l>hd_fragment cr
30a0: 61 73 68 74 65 73 74 69 6e 67 3c 2f 74 63 6c 3e  ashtesting</tcl>
30b0: 0a 3c 68 33 3e 33 2e 33 20 43 72 61 73 68 20 54  .<h3>3.3 Crash T
30c0: 65 73 74 69 6e 67 3c 2f 68 33 3e 0a 0a 3c 70 3e  esting</h3>..<p>
30d0: 43 72 61 73 68 20 74 65 73 74 69 6e 67 20 73 65  Crash testing se
30e0: 65 6b 73 20 74 6f 20 64 65 6d 6f 6e 73 74 72 61  eks to demonstra
30f0: 74 65 20 74 68 61 74 20 61 6e 20 53 51 4c 69 74  te that an SQLit
3100: 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
3110: 6e 6f 74 0a 67 6f 20 63 6f 72 72 75 70 74 20 69  not.go corrupt i
3120: 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
3130: 6e 20 6f 72 20 6f 70 65 72 61 74 69 6e 67 20 73  n or operating s
3140: 79 73 74 65 6d 20 63 72 61 73 68 65 73 20 6f 72  ystem crashes or
3150: 20 69 66 20 74 68 65 72 65 0a 69 73 20 61 20 70   if there.is a p
3160: 6f 77 65 72 20 66 61 69 6c 75 72 65 20 69 6e 20  ower failure in 
3170: 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20  the middle of a 
3180: 64 61 74 61 62 61 73 65 20 75 70 64 61 74 65 2e  database update.
3190: 20 20 41 20 73 65 70 61 72 61 74 65 0a 77 68 69    A separate.whi
31a0: 74 65 2d 70 61 70 65 72 20 74 69 74 6c 65 64 0a  te-paper titled.
31b0: 3c 61 20 68 72 65 66 3d 22 61 74 6f 6d 69 63 63  <a href="atomicc
31c0: 6f 6d 6d 69 74 2e 68 74 6d 6c 22 3e 41 74 6f 6d  ommit.html">Atom
31d0: 69 63 20 43 6f 6d 6d 69 74 20 69 6e 20 53 51 4c  ic Commit in SQL
31e0: 69 74 65 3c 2f 61 3e 20 64 65 73 63 72 69 62 65  ite</a> describe
31f0: 73 20 74 68 65 0a 64 65 66 65 6e 73 69 76 65 20  s the.defensive 
3200: 6d 65 61 73 75 72 65 20 53 51 4c 69 74 65 20 74  measure SQLite t
3210: 61 6b 65 73 20 74 6f 20 70 72 65 76 65 6e 74 20  akes to prevent 
3220: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
3230: 69 6f 6e 20 66 6f 6c 6c 6f 77 69 6e 67 0a 61 20  ion following.a 
3240: 63 72 61 73 68 2e 20 20 43 72 61 73 68 20 74 65  crash.  Crash te
3250: 73 74 73 20 73 74 72 69 76 65 20 74 6f 20 76 65  sts strive to ve
3260: 72 69 66 79 20 74 68 61 74 20 74 68 6f 73 65 20  rify that those 
3270: 64 65 66 65 6e 73 69 76 65 20 6d 65 61 73 75 72  defensive measur
3280: 65 73 0a 61 72 65 20 77 6f 72 6b 69 6e 67 20 63  es.are working c
3290: 6f 72 72 65 63 74 6c 79 2e 3c 2f 70 3e 0a 0a 3c  orrectly.</p>..<
32a0: 70 3e 49 74 20 69 73 20 69 6d 70 72 61 63 74 69  p>It is impracti
32b0: 63 61 6c 20 74 6f 20 64 6f 20 63 72 61 73 68 20  cal to do crash 
32c0: 74 65 73 74 69 6e 67 20 75 73 69 6e 67 20 72 65  testing using re
32d0: 61 6c 20 70 6f 77 65 72 20 66 61 69 6c 75 72 65  al power failure
32e0: 73 2c 20 6f 66 0a 63 6f 75 72 73 65 2c 20 61 6e  s, of.course, an
32f0: 64 20 73 6f 20 63 72 61 73 68 20 74 65 73 74 69  d so crash testi
3300: 6e 67 20 69 73 20 64 6f 6e 65 20 69 6e 20 73 69  ng is done in si
3310: 6d 75 6c 61 74 69 6f 6e 2e 20 20 41 6e 20 61 6c  mulation.  An al
3320: 74 65 72 6e 61 74 69 76 65 0a 5b 73 71 6c 69 74  ternative.[sqlit
3330: 65 33 5f 76 66 73 20 7c 20 56 69 72 74 75 61 6c  e3_vfs | Virtual
3340: 20 46 69 6c 65 20 53 79 73 74 65 6d 5d 20 69 73   File System] is
3350: 20 69 6e 73 65 72 74 65 64 20 74 68 61 74 20 61   inserted that a
3360: 6c 6c 6f 77 73 20 74 68 65 20 74 65 73 74 0a 68  llows the test.h
3370: 61 72 6e 65 73 73 20 74 6f 20 73 69 6d 75 6c 61  arness to simula
3380: 74 65 20 74 68 65 20 73 74 61 74 65 20 6f 66 20  te the state of 
3390: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
33a0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72  e following a cr
33b0: 61 73 68 2e 3c 2f 70 3e 0a 0a 3c 70 3e 49 6e 20  ash.</p>..<p>In 
33c0: 74 68 65 20 54 43 4c 20 74 65 73 74 20 68 61 72  the TCL test har
33d0: 6e 65 73 73 2c 20 74 68 65 20 63 72 61 73 68 20  ness, the crash 
33e0: 73 69 6d 75 6c 61 74 69 6f 6e 20 69 73 20 64 6f  simulation is do
33f0: 6e 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65  ne in a separate
3400: 0a 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 6d  .process.  The m
3410: 61 69 6e 20 74 65 73 74 69 6e 67 20 70 72 6f 63  ain testing proc
3420: 65 73 73 20 73 70 61 77 6e 73 20 61 20 63 68 69  ess spawns a chi
3430: 6c 64 20 70 72 6f 63 65 73 73 20 77 68 69 63 68  ld process which
3440: 20 72 75 6e 73 0a 73 6f 6d 65 20 53 51 4c 69 74   runs.some SQLit
3450: 65 20 6f 70 65 72 61 74 69 6f 6e 20 61 6e 64 20  e operation and 
3460: 72 61 6e 64 6f 6d 6c 79 20 63 72 61 73 68 65 73  randomly crashes
3470: 20 73 6f 6d 65 77 68 65 72 65 20 69 6e 20 74 68   somewhere in th
3480: 65 20 6d 69 64 64 6c 65 20 6f 66 0a 61 20 77 72  e middle of.a wr
3490: 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ite operation.  
34a0: 41 20 73 70 65 63 69 61 6c 20 5b 56 46 53 5d 20  A special [VFS] 
34b0: 72 61 6e 64 6f 6d 6c 79 20 72 65 6f 72 64 65 72  randomly reorder
34c0: 73 20 61 6e 64 20 63 6f 72 72 75 70 74 73 0a 74  s and corrupts.t
34d0: 68 65 20 75 6e 73 79 6e 63 68 72 6f 6e 69 7a 65  he unsynchronize
34e0: 64 0a 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f  d.write operatio
34f0: 6e 73 20 74 6f 20 73 69 6d 75 6c 61 74 65 20 74  ns to simulate t
3500: 68 65 20 65 66 66 65 63 74 20 6f 66 20 62 75 66  he effect of buf
3510: 66 65 72 65 64 20 66 69 6c 65 73 79 73 74 65 6d  fered filesystem
3520: 73 2e 20 20 41 66 74 65 72 0a 74 68 65 20 63 68  s.  After.the ch
3530: 69 6c 64 20 64 69 65 73 2c 20 74 68 65 20 6f 72  ild dies, the or
3540: 69 67 69 6e 61 6c 20 74 65 73 74 20 70 72 6f 63  iginal test proc
3550: 65 73 73 20 6f 70 65 6e 73 20 61 6e 64 20 72 65  ess opens and re
3560: 61 64 73 20 74 68 65 20 74 65 73 74 0a 64 61 74  ads the test.dat
3570: 61 62 61 73 65 20 61 6e 64 20 76 65 72 69 66 69  abase and verifi
3580: 65 73 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  es that the chan
3590: 67 65 73 20 61 74 74 65 6d 70 74 65 64 20 62 79  ges attempted by
35a0: 20 74 68 65 20 63 68 69 6c 64 20 65 69 74 68 65   the child eithe
35b0: 72 0a 63 6f 6d 70 6c 65 74 65 64 20 73 75 63 63  r.completed succ
35c0: 65 73 73 66 75 6c 6c 79 20 6f 72 20 65 6c 73 65  essfully or else
35d0: 20 77 65 72 65 20 63 6f 6d 70 6c 65 74 65 6c 79   were completely
35e0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 20 20 54   rolled back.  T
35f0: 68 65 0a 5b 69 6e 74 65 67 72 69 74 79 5f 63 68  he.[integrity_ch
3600: 65 63 6b 5d 20 5b 50 52 41 47 4d 41 5d 20 69 73  eck] [PRAGMA] is
3610: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 73 75   used to make su
3620: 72 65 20 6e 6f 20 64 61 74 61 62 61 73 65 20 63  re no database c
3630: 6f 72 72 75 70 74 69 6f 6e 0a 6f 63 63 75 72 73  orruption.occurs
3640: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 54 48  .</p>..<p>The TH
3650: 33 20 74 65 73 74 20 68 61 72 6e 65 73 73 20 6e  3 test harness n
3660: 65 65 64 73 20 74 6f 20 72 75 6e 20 6f 6e 20 65  eeds to run on e
3670: 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 20  mbedded systems 
3680: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 6e 65 63 65  that do not.nece
3690: 73 73 61 72 69 6c 79 20 68 61 76 65 20 74 68 65  ssarily have the
36a0: 20 61 62 69 6c 69 74 79 20 74 6f 20 73 70 61 77   ability to spaw
36b0: 6e 20 63 68 69 6c 64 20 70 72 6f 63 65 73 73 65  n child processe
36c0: 73 2c 20 73 6f 20 69 74 20 75 73 65 73 0a 61 6e  s, so it uses.an
36d0: 20 69 6e 2d 6d 65 6d 6f 72 79 20 5b 56 46 53 5d   in-memory [VFS]
36e0: 20 74 6f 20 73 69 6d 75 6c 61 74 65 20 63 72 61   to simulate cra
36f0: 73 68 65 73 2e 20 20 54 68 65 20 69 6e 2d 6d 65  shes.  The in-me
3700: 6d 6f 72 79 20 5b 56 46 53 5d 20 63 61 6e 20 62  mory [VFS] can b
3710: 65 20 72 69 67 67 65 64 0a 74 6f 20 6d 61 6b 65  e rigged.to make
3720: 20 61 20 73 6e 61 70 73 68 6f 74 20 6f 66 20 74   a snapshot of t
3730: 68 65 20 65 6e 74 69 72 65 20 66 69 6c 65 73 79  he entire filesy
3740: 73 74 65 6d 20 61 66 74 65 72 20 61 20 73 65 74  stem after a set
3750: 20 6e 75 6d 62 65 72 20 6f 66 20 49 2f 4f 0a 6f   number of I/O.o
3760: 70 65 72 61 74 69 6f 6e 73 2e 20 20 43 72 61 73  perations.  Cras
3770: 68 20 74 65 73 74 73 20 72 75 6e 20 69 6e 20 61  h tests run in a
3780: 20 6c 6f 6f 70 2e 20 20 4f 6e 20 65 61 63 68 20   loop.  On each 
3790: 69 74 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  iteration of the
37a0: 20 6c 6f 6f 70 2c 0a 74 68 65 20 70 6f 69 6e 74   loop,.the point
37b0: 20 61 74 20 77 68 69 63 68 20 61 20 73 6e 61 70   at which a snap
37c0: 73 68 6f 74 20 69 73 20 6d 61 64 65 20 69 73 20  shot is made is 
37d0: 61 64 76 61 6e 63 65 64 20 75 6e 74 69 6c 20 74  advanced until t
37e0: 68 65 20 53 51 4c 69 74 65 0a 6f 70 65 72 61 74  he SQLite.operat
37f0: 69 6f 6e 73 20 62 65 69 6e 67 20 74 65 73 74 65  ions being teste
3800: 64 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  d run to complet
3810: 69 6f 6e 20 77 69 74 68 6f 75 74 20 65 76 65 72  ion without ever
3820: 20 68 69 74 74 69 6e 67 20 61 0a 73 6e 61 70 73   hitting a.snaps
3830: 68 6f 74 2e 20 20 57 69 74 68 69 6e 20 74 68 65  hot.  Within the
3840: 20 6c 6f 6f 70 2c 20 61 66 74 65 72 20 74 68 65   loop, after the
3850: 20 53 51 4c 69 74 65 20 6f 70 65 72 61 74 69 6f   SQLite operatio
3860: 6e 20 75 6e 64 65 72 20 74 65 73 74 20 68 61 73  n under test has
3870: 0a 63 6f 6d 70 6c 65 74 65 64 2c 20 74 68 65 20  .completed, the 
3880: 66 69 6c 65 73 79 73 74 65 6d 20 69 73 20 72 65  filesystem is re
3890: 76 65 72 74 65 64 20 74 6f 20 74 68 65 20 73 6e  verted to the sn
38a0: 61 70 73 68 6f 74 20 61 6e 64 20 72 61 6e 64 6f  apshot and rando
38b0: 6d 20 66 69 6c 65 0a 64 61 6d 61 67 65 20 69 73  m file.damage is
38c0: 20 69 6e 74 72 6f 64 75 63 65 64 20 74 68 61 74   introduced that
38d0: 20 69 73 20 63 68 61 72 61 63 74 65 72 69 73 74   is characterist
38e0: 69 63 20 6f 66 20 74 68 65 20 6b 69 6e 64 73 20  ic of the kinds 
38f0: 6f 66 20 64 61 6d 61 67 65 0a 6f 6e 65 20 65 78  of damage.one ex
3900: 70 65 63 74 73 20 74 6f 20 73 65 65 20 66 6f 6c  pects to see fol
3910: 6c 6f 77 69 6e 67 20 61 20 70 6f 77 65 72 20 6c  lowing a power l
3920: 6f 73 73 2e 20 20 54 68 65 6e 20 74 68 65 20 64  oss.  Then the d
3930: 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
3940: 64 0a 61 6e 64 20 63 68 65 63 6b 73 20 61 72 65  d.and checks are
3950: 20 6d 61 64 65 20 74 6f 20 65 6e 73 75 72 65 20   made to ensure 
3960: 74 68 61 74 20 69 74 20 69 73 20 77 65 6c 6c 2d  that it is well-
3970: 66 6f 72 6d 65 64 20 61 6e 64 20 74 68 61 74 20  formed and that 
3980: 74 68 65 0a 74 72 61 6e 73 61 63 74 69 6f 6e 20  the.transaction 
3990: 65 69 74 68 65 72 20 72 61 6e 20 74 6f 20 63 6f  either ran to co
39a0: 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 77 61 73 20  mpletion or was 
39b0: 63 6f 6d 70 6c 65 74 65 6c 79 20 72 6f 6c 6c 65  completely rolle
39c0: 64 20 62 61 63 6b 2e 0a 54 68 65 20 69 6e 74 65  d back..The inte
39d0: 72 69 6f 72 20 6f 66 20 74 68 65 20 6c 6f 6f 70  rior of the loop
39e0: 20 69 73 20 72 65 70 65 61 74 65 64 20 6d 75 6c   is repeated mul
39f0: 74 69 70 6c 65 20 74 69 6d 65 73 20 66 6f 72 20  tiple times for 
3a00: 65 61 63 68 0a 73 6e 61 70 73 68 6f 74 20 77 69  each.snapshot wi
3a10: 74 68 20 64 69 66 66 65 72 65 6e 74 20 72 61 6e  th different ran
3a20: 64 6f 6d 20 64 61 6d 61 67 65 20 65 61 63 68 20  dom damage each 
3a30: 74 69 6d 65 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e  time.</p>..<tcl>
3a40: 68 64 5f 66 72 61 67 6d 65 6e 74 20 6d 75 6c 74  hd_fragment mult
3a50: 69 66 61 69 6c 3c 2f 74 63 6c 3e 0a 3c 68 33 3e  ifail</tcl>.<h3>
3a60: 33 2e 34 20 43 6f 6d 70 6f 75 6e 64 20 66 61 69  3.4 Compound fai
3a70: 6c 75 72 65 20 74 65 73 74 73 3c 2f 68 33 3e 0a  lure tests</h3>.
3a80: 0a 3c 70 3e 54 68 65 20 74 65 73 74 20 73 75 69  .<p>The test sui
3a90: 74 65 73 20 66 6f 72 20 53 51 4c 69 74 65 20 61  tes for SQLite a
3aa0: 6c 73 6f 20 65 78 70 6c 6f 72 65 20 74 68 65 20  lso explore the 
3ab0: 72 65 73 75 6c 74 20 6f 66 20 73 74 61 63 6b 69  result of stacki
3ac0: 6e 67 0a 6d 75 6c 74 69 70 6c 65 20 66 61 69 6c  ng.multiple fail
3ad0: 75 72 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  ures.  For examp
3ae0: 6c 65 2c 20 74 65 73 74 73 20 61 72 65 20 72 75  le, tests are ru
3af0: 6e 20 74 6f 20 65 6e 73 75 72 65 20 63 6f 72 72  n to ensure corr
3b00: 65 63 74 20 62 65 68 61 76 69 6f 72 0a 77 68 65  ect behavior.whe
3b10: 6e 20 61 6e 20 49 2f 4f 20 65 72 72 6f 72 20 6f  n an I/O error o
3b20: 72 20 4f 4f 4d 20 66 61 75 6c 74 20 6f 63 63 75  r OOM fault occu
3b30: 72 73 20 77 68 69 6c 65 20 74 72 79 69 6e 67 20  rs while trying 
3b40: 74 6f 20 72 65 63 6f 76 65 72 20 66 72 6f 6d 20  to recover from 
3b50: 61 0a 70 72 69 6f 72 20 63 72 61 73 68 2e 0a 0a  a.prior crash...
3b60: 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
3b70: 20 66 75 7a 7a 74 65 73 74 69 6e 67 3c 2f 74 63   fuzztesting</tc
3b80: 6c 3e 0a 3c 68 32 3e 34 2e 30 20 46 75 7a 7a 20  l>.<h2>4.0 Fuzz 
3b90: 54 65 73 74 69 6e 67 3c 2f 68 32 3e 0a 0a 3c 70  Testing</h2>..<p
3ba0: 3e 5b 68 74 74 70 3a 2f 2f 65 6e 2e 77 69 6b 69  >[http://en.wiki
3bb0: 70 65 64 69 61 2e 6f 72 67 2f 77 69 6b 69 2f 46  pedia.org/wiki/F
3bc0: 75 7a 7a 5f 74 65 73 74 69 6e 67 20 7c 20 46 75  uzz_testing | Fu
3bd0: 7a 7a 20 74 65 73 74 69 6e 67 5d 0a 73 65 65 6b  zz testing].seek
3be0: 73 20 74 6f 20 65 73 74 61 62 6c 69 73 68 20 74  s to establish t
3bf0: 68 61 74 20 53 51 4c 69 74 65 20 72 65 73 70 6f  hat SQLite respo
3c00: 6e 64 73 20 63 6f 72 72 65 63 74 6c 79 20 74 6f  nds correctly to
3c10: 20 69 6e 76 61 6c 69 64 2c 20 6f 75 74 2d 6f 66   invalid, out-of
3c20: 2d 72 61 6e 67 65 2c 0a 6f 72 20 6d 61 6c 66 6f  -range,.or malfo
3c30: 72 6d 65 64 20 69 6e 70 75 74 73 2e 3c 2f 70 3e  rmed inputs.</p>
3c40: 0a 0a 3c 68 33 3e 34 2e 31 20 53 51 4c 20 46 75  ..<h3>4.1 SQL Fu
3c50: 7a 7a 3c 2f 68 33 3e 0a 0a 3c 70 3e 53 51 4c 20  zz</h3>..<p>SQL 
3c60: 66 75 7a 7a 20 74 65 73 74 69 6e 67 20 63 6f 6e  fuzz testing con
3c70: 73 69 73 74 73 20 6f 66 20 63 72 65 61 74 69 6e  sists of creatin
3c80: 67 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  g syntactically 
3c90: 63 6f 72 72 65 63 74 20 79 65 74 0a 77 69 6c 64  correct yet.wild
3ca0: 6c 79 20 6e 6f 6e 73 65 6e 73 69 63 61 6c 20 53  ly nonsensical S
3cb0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6e  QL statements an
3cc0: 64 20 66 65 65 64 69 6e 67 20 74 68 65 6d 20 74  d feeding them t
3cd0: 6f 20 53 51 4c 69 74 65 20 74 6f 20 73 65 65 0a  o SQLite to see.
3ce0: 77 68 61 74 20 69 74 20 77 69 6c 6c 20 64 6f 20  what it will do 
3cf0: 77 69 74 68 20 74 68 65 6d 2e 20 20 55 73 75 61  with them.  Usua
3d00: 6c 6c 79 20 73 6f 6d 65 20 6b 69 6e 64 20 6f 66  lly some kind of
3d10: 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
3d20: 65 64 0a 28 73 75 63 68 20 61 73 20 22 6e 6f 20  ed.(such as "no 
3d30: 73 75 63 68 20 74 61 62 6c 65 22 29 2e 20 20 53  such table").  S
3d40: 6f 6d 65 74 69 6d 65 73 2c 20 70 75 72 65 6c 79  ometimes, purely
3d50: 20 62 79 20 63 68 61 6e 63 65 2c 20 74 68 65 20   by chance, the 
3d60: 53 51 4c 0a 73 74 61 74 65 6d 65 6e 74 20 61 6c  SQL.statement al
3d70: 73 6f 20 68 61 70 70 65 6e 73 20 74 6f 20 62 65  so happens to be
3d80: 20 73 65 6d 61 6e 74 69 63 61 6c 6c 79 20 63 6f   semantically co
3d90: 72 72 65 63 74 2e 20 20 49 6e 20 74 68 61 74 20  rrect.  In that 
3da0: 63 61 73 65 2c 20 74 68 65 0a 72 65 73 75 6c 74  case, the.result
3db0: 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74 61  ing prepared sta
3dc0: 74 65 6d 65 6e 74 20 69 73 20 72 75 6e 20 74 6f  tement is run to
3dd0: 20 6d 61 6b 65 20 73 75 72 65 20 69 74 20 67 69   make sure it gi
3de0: 76 65 73 20 61 20 72 65 61 73 6f 6e 61 62 6c 65  ves a reasonable
3df0: 0a 72 65 73 75 6c 74 2e 3c 2f 70 3e 0a 0a 3c 70  .result.</p>..<p
3e00: 3e 54 68 65 20 53 51 4c 20 66 75 7a 7a 20 67 65  >The SQL fuzz ge
3e10: 6e 65 72 61 74 6f 72 20 74 65 73 74 73 20 61 72  nerator tests ar
3e20: 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 54 43  e part of the TC
3e30: 4c 20 74 65 73 74 20 73 75 69 74 65 2e 0a 44 75  L test suite..Du
3e40: 72 69 6e 67 20 61 20 66 75 6c 6c 20 74 65 73 74  ring a full test
3e50: 20 72 75 6e 2c 20 61 62 6f 75 74 20 3c 74 63 6c   run, about <tcl
3e60: 3e 4b 42 20 7b 24 73 74 61 74 28 6e 53 71 6c 46  >KB {$stat(nSqlF
3e70: 75 7a 7a 29 7d 3c 2f 74 63 6c 3e 20 0a 74 68 6f  uzz)}</tcl> .tho
3e80: 75 73 61 6e 64 20 66 75 7a 7a 20 53 51 4c 20 73  usand fuzz SQL s
3e90: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 67 65  tatements are.ge
3ea0: 6e 65 72 61 74 65 64 20 61 6e 64 20 74 65 73 74  nerated and test
3eb0: 65 64 2e 3c 2f 70 3e 0a 0a 3c 68 33 3e 34 2e 32  ed.</p>..<h3>4.2
3ec0: 20 4d 61 6c 66 6f 72 6d 65 64 20 44 61 74 61 62   Malformed Datab
3ed0: 61 73 65 20 46 69 6c 65 73 3c 2f 68 33 3e 0a 0a  ase Files</h3>..
3ee0: 3c 70 3e 54 68 65 72 65 20 61 72 65 20 6e 75 6d  <p>There are num
3ef0: 65 72 6f 75 73 20 74 65 73 74 20 63 61 73 65 73  erous test cases
3f00: 20 74 68 61 74 20 76 65 72 69 66 79 20 74 68 61   that verify tha
3f10: 74 20 53 51 4c 69 74 65 20 69 73 20 61 62 6c 65  t SQLite is able
3f20: 20 74 6f 0a 64 65 61 6c 20 77 69 74 68 20 6d 61   to.deal with ma
3f30: 6c 66 6f 72 6d 65 64 20 64 61 74 61 62 61 73 65  lformed database
3f40: 20 66 69 6c 65 73 2e 0a 54 68 65 73 65 20 74 65   files..These te
3f50: 73 74 73 20 66 69 72 73 74 20 62 75 69 6c 64 20  sts first build 
3f60: 61 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 64 61  a well-formed da
3f70: 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65  tabase file, the
3f80: 6e 20 61 64 64 0a 63 6f 72 72 75 70 74 69 6f 6e  n add.corruption
3f90: 20 62 79 20 63 68 61 6e 67 69 6e 67 20 6f 6e 65   by changing one
3fa0: 20 6f 72 20 6d 6f 72 65 20 62 79 74 65 73 20 69   or more bytes i
3fb0: 6e 20 74 68 65 20 66 69 6c 65 20 62 79 20 73 6f  n the file by so
3fc0: 6d 65 20 6d 65 61 6e 73 0a 6f 74 68 65 72 20 74  me means.other t
3fd0: 68 61 6e 20 53 51 4c 69 74 65 2e 20 20 54 68 65  han SQLite.  The
3fe0: 6e 20 53 51 4c 69 74 65 20 69 73 20 75 73 65 64  n SQLite is used
3ff0: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74   to read the dat
4000: 61 62 61 73 65 2e 0a 49 6e 20 73 6f 6d 65 20 63  abase..In some c
4010: 61 73 65 73 2c 20 74 68 65 20 62 79 74 65 73 20  ases, the bytes 
4020: 63 68 61 6e 67 65 73 20 61 72 65 20 69 6e 20 74  changes are in t
4030: 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 64 61 74  he middle of dat
4040: 61 2e 0a 54 68 69 73 20 63 61 75 73 65 73 20 74  a..This causes t
4050: 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
4060: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 63 68  e database to ch
4070: 61 6e 67 65 20 77 68 69 6c 65 20 6b 65 65 70 69  ange while keepi
4080: 6e 67 20 74 68 65 0a 64 61 74 61 62 61 73 65 20  ng the.database 
4090: 77 65 6c 6c 2d 66 6f 72 6d 65 64 2e 0a 49 6e 20  well-formed..In 
40a0: 6f 74 68 65 72 20 63 61 73 65 73 2c 20 75 6e 75  other cases, unu
40b0: 73 65 64 20 62 79 74 65 73 20 6f 66 20 74 68 65  sed bytes of the
40c0: 20 66 69 6c 65 20 61 72 65 20 6d 6f 64 69 66 69   file are modifi
40d0: 65 64 2c 20 77 68 69 63 68 20 68 61 73 0a 6e 6f  ed, which has.no
40e0: 20 65 66 66 65 63 74 20 6f 6e 20 74 68 65 20 69   effect on the i
40f0: 6e 74 65 67 72 69 74 79 20 6f 66 20 74 68 65 20  ntegrity of the 
4100: 64 61 74 61 62 61 73 65 2e 0a 54 68 65 20 69 6e  database..The in
4110: 74 65 72 65 73 74 69 6e 67 20 63 61 73 65 73 20  teresting cases 
4120: 61 72 65 20 77 68 65 6e 20 62 79 74 65 73 20 6f  are when bytes o
4130: 66 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 0a  f the file that.
4140: 64 65 66 69 6e 65 20 64 61 74 61 62 61 73 65 20  define database 
4150: 73 74 72 75 63 74 75 72 65 20 67 65 74 20 63 68  structure get ch
4160: 61 6e 67 65 64 2e 20 20 54 68 65 20 6d 61 6c 66  anged.  The malf
4170: 6f 72 6d 65 64 20 64 61 74 61 62 61 73 65 20 74  ormed database t
4180: 65 73 74 73 0a 76 65 72 69 66 79 20 74 68 61 74  ests.verify that
4190: 20 53 51 4c 69 74 65 20 66 69 6e 64 73 20 74 68   SQLite finds th
41a0: 65 20 66 69 6c 65 20 66 6f 72 6d 61 74 20 65 72  e file format er
41b0: 72 6f 72 73 20 61 6e 64 20 72 65 70 6f 72 74 73  rors and reports
41c0: 20 74 68 65 6d 0a 75 73 69 6e 67 20 74 68 65 20   them.using the 
41d0: 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
41e0: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 77 69 74   return code wit
41f0: 68 6f 75 74 20 6f 76 65 72 66 6c 6f 77 69 6e 67  hout overflowing
4200: 0a 62 75 66 66 65 72 73 2c 20 64 65 72 65 66 65  .buffers, derefe
4210: 72 65 6e 63 69 6e 67 20 4e 55 4c 4c 20 70 6f 69  rencing NULL poi
4220: 6e 74 65 72 73 2c 20 6f 72 20 70 65 72 66 6f 72  nters, or perfor
4230: 6d 69 6e 67 20 6f 74 68 65 72 0a 75 6e 77 68 6f  ming other.unwho
4240: 6c 65 73 6f 6d 65 20 61 63 74 69 6f 6e 73 2e 3c  lesome actions.<
4250: 2f 70 3e 0a 0a 3c 68 33 3e 34 2e 33 20 42 6f 75  /p>..<h3>4.3 Bou
4260: 6e 64 61 72 79 20 56 61 6c 75 65 20 54 65 73 74  ndary Value Test
4270: 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 53 51 4c 69 74  s</h3>..<p>SQLit
4280: 65 20 64 65 66 69 6e 65 73 20 63 65 72 74 61 69  e defines certai
4290: 6e 20 5b 6c 69 6d 69 74 73 5d 20 6f 6e 20 69 74  n [limits] on it
42a0: 73 20 6f 70 65 72 61 74 69 6f 6e 2c 20 73 75 63  s operation, suc
42b0: 68 20 61 73 20 74 68 65 0a 6d 61 78 69 6d 75 6d  h as the.maximum
42c0: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
42d0: 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 2c 20 74  ns in a table, t
42e0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
42f0: 68 20 6f 66 20 61 6e 20 0a 53 51 4c 20 73 74 61  h of an .SQL sta
4300: 74 65 6d 65 6e 74 2c 20 6f 72 20 74 68 65 20 6d  tement, or the m
4310: 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20  aximum value of 
4320: 61 6e 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65  an integer.  The
4330: 20 54 43 4c 20 61 6e 64 20 54 48 33 20 74 65 73   TCL and TH3 tes
4340: 74 0a 73 75 69 74 65 73 20 62 6f 74 68 20 63 6f  t.suites both co
4350: 6e 74 61 69 6e 73 20 6e 75 6d 65 72 6f 75 73 20  ntains numerous 
4360: 74 65 73 74 73 20 74 68 61 74 20 70 75 73 68 20  tests that push 
4370: 53 51 4c 69 74 65 20 72 69 67 68 74 20 74 6f 20  SQLite right to 
4380: 74 68 65 20 65 64 67 65 0a 6f 66 20 69 74 73 20  the edge.of its 
4390: 64 65 66 69 6e 65 64 20 6c 69 6d 69 74 73 20 61  defined limits a
43a0: 6e 64 20 76 65 72 69 66 79 20 74 68 61 74 20 69  nd verify that i
43b0: 74 20 70 65 72 66 6f 72 6d 73 20 63 6f 72 72 65  t performs corre
43c0: 63 74 6c 79 20 66 6f 72 0a 61 6c 6c 20 61 6c 6c  ctly for.all all
43d0: 6f 77 65 64 20 76 61 6c 75 65 73 2e 20 20 41 64  owed values.  Ad
43e0: 64 69 74 69 6f 6e 61 6c 20 74 65 73 74 73 20 67  ditional tests g
43f0: 6f 20 62 65 79 6f 6e 64 20 74 68 65 20 64 65 66  o beyond the def
4400: 69 6e 65 64 20 6c 69 6d 69 74 73 0a 61 6e 64 20  ined limits.and 
4410: 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69  verify that SQLi
4420: 74 65 20 63 6f 72 72 65 63 74 6c 79 20 72 65 74  te correctly ret
4430: 75 72 6e 73 20 65 72 72 6f 72 73 2e 20 20 54 68  urns errors.  Th
4440: 65 20 73 6f 75 72 63 65 20 63 6f 64 65 0a 63 6f  e source code.co
4450: 6e 74 61 69 6e 73 20 5b 74 65 73 74 63 61 73 65  ntains [testcase
4460: 20 6d 61 63 72 6f 73 5d 20 74 6f 20 76 65 72 69   macros] to veri
4470: 66 79 20 74 68 61 74 20 62 6f 74 68 20 73 69 64  fy that both sid
4480: 65 73 20 6f 66 20 65 61 63 68 20 62 6f 75 6e 64  es of each bound
4490: 61 72 79 0a 68 61 76 65 20 62 65 65 6e 20 74 65  ary.have been te
44a0: 73 74 65 64 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e  sted.</p>..<tcl>
44b0: 68 64 5f 66 72 61 67 6d 65 6e 74 20 72 65 67 72  hd_fragment regr
44c0: 65 73 73 69 6f 6e 74 65 73 74 69 6e 67 3c 2f 74  essiontesting</t
44d0: 63 6c 3e 0a 3c 68 32 3e 35 2e 30 20 52 65 67 72  cl>.<h2>5.0 Regr
44e0: 65 73 73 69 6f 6e 20 54 65 73 74 69 6e 67 3c 2f  ession Testing</
44f0: 68 32 3e 0a 0a 3c 70 3e 57 68 65 6e 65 76 65 72  h2>..<p>Whenever
4500: 20 61 20 62 75 67 20 69 73 20 72 65 70 6f 72 74   a bug is report
4510: 65 64 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74  ed against SQLit
4520: 65 2c 20 74 68 61 74 20 62 75 67 20 69 73 20 6e  e, that bug is n
4530: 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 0a 66 69  ot considered.fi
4540: 78 65 64 20 75 6e 74 69 6c 20 6e 65 77 20 74 65  xed until new te
4550: 73 74 20 63 61 73 65 73 20 68 61 76 65 20 62 65  st cases have be
4560: 65 6e 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  en added to the 
4570: 54 43 4c 20 74 65 73 74 20 73 75 69 74 65 20 77  TCL test suite w
4580: 68 69 63 68 0a 77 6f 75 6c 64 20 65 78 68 69 62  hich.would exhib
4590: 69 74 20 74 68 65 20 62 75 67 20 69 6e 20 61 6e  it the bug in an
45a0: 20 75 6e 70 61 74 63 68 65 64 20 76 65 72 73 69   unpatched versi
45b0: 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 4f  on of SQLite.  O
45c0: 76 65 72 20 74 68 65 20 79 65 61 72 73 2c 0a 74  ver the years,.t
45d0: 68 69 73 20 68 61 73 20 72 65 73 75 6c 74 65 64  his has resulted
45e0: 20 69 6e 20 74 68 6f 75 73 61 6e 64 73 20 61 6e   in thousands an
45f0: 64 20 74 68 6f 75 73 61 6e 64 73 20 6f 66 20 6e  d thousands of n
4600: 65 77 20 74 65 73 74 73 20 62 65 69 6e 67 20 61  ew tests being a
4610: 64 64 65 64 0a 74 6f 20 74 68 65 20 54 43 4c 20  dded.to the TCL 
4620: 74 65 73 74 20 73 75 69 74 65 2e 20 20 54 68 65  test suite.  The
4630: 73 65 20 72 65 67 72 65 73 73 69 6f 6e 20 74 65  se regression te
4640: 73 74 73 20 65 6e 73 75 72 65 20 74 68 61 74 20  sts ensure that 
4650: 62 75 67 73 20 74 68 61 74 20 68 61 76 65 0a 62  bugs that have.b
4660: 65 65 6e 20 66 69 78 65 64 20 69 6e 20 74 68 65  een fixed in the
4670: 20 70 61 73 74 20 61 72 65 20 6e 6f 74 20 72 65   past are not re
4680: 69 6e 74 72 6f 64 75 63 65 64 20 69 6e 74 6f 20  introduced into 
4690: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
46a0: 6f 66 0a 53 51 4c 69 74 65 2e 3c 2f 70 3e 0a 0a  of.SQLite.</p>..
46b0: 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
46c0: 20 6c 65 61 6b 63 68 65 63 6b 3c 2f 74 63 6c 3e   leakcheck</tcl>
46d0: 0a 3c 68 32 3e 36 2e 30 20 41 75 74 6f 6d 61 74  .<h2>6.0 Automat
46e0: 69 63 20 52 65 73 6f 75 72 63 65 20 4c 65 61 6b  ic Resource Leak
46f0: 20 44 65 74 65 63 74 69 6f 6e 3c 2f 68 32 3e 0a   Detection</h2>.
4700: 0a 3c 70 3e 52 65 73 6f 75 72 63 65 20 6c 65 61  .<p>Resource lea
4710: 6b 20 6f 63 63 75 72 73 20 77 68 65 6e 20 73 79  k occurs when sy
4720: 73 74 65 6d 20 72 65 73 6f 75 72 63 65 73 0a 61  stem resources.a
4730: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 64  re allocated and
4740: 20 6e 65 76 65 72 20 66 72 65 65 64 2e 20 20 54   never freed.  T
4750: 68 65 20 6d 6f 73 74 20 74 72 6f 75 62 6c 65 73  he most troubles
4760: 6f 6d 65 20 72 65 73 6f 75 72 63 65 20 6c 65 61  ome resource lea
4770: 6b 73 0a 69 6e 20 6d 61 6e 79 20 61 70 70 6c 69  ks.in many appli
4780: 63 61 74 69 6f 6e 73 20 61 72 65 20 6d 65 6d 6f  cations are memo
4790: 72 79 20 6c 65 61 6b 73 20 2d 20 77 68 65 6e 20  ry leaks - when 
47a0: 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
47b0: 74 65 64 20 75 73 69 6e 67 0a 6d 61 6c 6c 6f 63  ted using.malloc
47c0: 28 29 20 62 75 74 20 6e 65 76 65 72 20 72 65 6c  () but never rel
47d0: 65 61 73 65 64 20 75 73 69 6e 67 20 66 72 65 65  eased using free
47e0: 28 29 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6b  ().  But other k
47f0: 69 6e 64 73 20 6f 66 20 72 65 73 6f 75 72 63 65  inds of resource
4800: 73 0a 63 61 6e 20 61 6c 73 6f 20 62 65 20 6c 65  s.can also be le
4810: 61 6b 65 64 3a 20 20 66 69 6c 65 20 64 65 73 63  aked:  file desc
4820: 72 69 70 74 6f 72 73 2c 20 74 68 72 65 61 64 73  riptors, threads
4830: 2c 20 6d 75 74 65 78 65 73 2c 20 65 74 63 2e 3c  , mutexes, etc.<
4840: 2f 70 3e 0a 0a 3c 70 3e 42 6f 74 68 20 74 68 65  /p>..<p>Both the
4850: 20 54 43 4c 20 61 6e 64 20 54 48 33 20 74 65 73   TCL and TH3 tes
4860: 74 20 68 61 72 6e 65 73 73 65 73 20 61 75 74 6f  t harnesses auto
4870: 6d 61 74 69 63 61 6c 6c 79 20 74 72 61 63 6b 20  matically track 
4880: 73 79 73 74 65 6d 0a 72 65 73 6f 75 72 63 65 73  system.resources
4890: 20 61 6e 64 20 72 65 70 6f 72 74 20 72 65 73 6f   and report reso
48a0: 75 72 63 65 20 6c 65 61 6b 73 20 6f 6e 20 3c 75  urce leaks on <u
48b0: 3e 65 76 65 72 79 3c 2f 75 3e 20 74 65 73 74 20  >every</u> test 
48c0: 72 75 6e 2e 0a 4e 6f 20 73 70 65 63 69 61 6c 20  run..No special 
48d0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 72  configuration or
48e0: 20 73 65 74 75 70 20 69 73 20 72 65 71 75 69 72   setup is requir
48f0: 65 64 2e 20 20 20 54 68 65 20 74 65 73 74 20 68  ed.   The test h
4900: 61 72 6e 65 73 73 65 73 0a 61 72 65 20 65 73 70  arnesses.are esp
4910: 65 63 69 61 6c 6c 79 20 76 69 67 69 6c 61 6e 74  ecially vigilant
4920: 20 77 69 74 68 20 72 65 67 61 72 64 20 74 6f 20   with regard to 
4930: 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2e 20 20 49  memory leaks.  I
4940: 66 20 61 20 63 68 61 6e 67 65 0a 63 61 75 73 65  f a change.cause
4950: 73 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c  s a memory leak,
4960: 20 74 68 65 20 74 65 73 74 20 68 61 72 6e 65 73   the test harnes
4970: 73 65 73 20 77 69 6c 6c 20 72 65 63 6f 67 6e 69  ses will recogni
4980: 7a 65 20 74 68 69 73 0a 71 75 69 63 6b 6c 79 2e  ze this.quickly.
4990: 20 20 53 51 4c 69 74 65 20 69 73 20 64 65 73 69    SQLite is desi
49a0: 67 6e 65 64 20 74 6f 20 6e 65 76 65 72 20 6c 65  gned to never le
49b0: 61 6b 20 6d 65 6d 6f 72 79 2c 20 65 76 65 6e 20  ak memory, even 
49c0: 61 66 74 65 72 0a 61 6e 20 65 78 63 65 70 74 69  after.an excepti
49d0: 6f 6e 20 73 75 63 68 20 61 73 20 61 6e 20 4f 4f  on such as an OO
49e0: 4d 20 65 72 72 6f 72 20 6f 72 20 64 69 73 6b 20  M error or disk 
49f0: 49 2f 4f 20 65 72 72 6f 72 2e 20 20 54 68 65 20  I/O error.  The 
4a00: 74 65 73 74 0a 68 61 72 6e 65 73 73 65 73 20 61  test.harnesses a
4a10: 72 65 20 7a 65 61 6c 6f 75 73 20 74 6f 20 65 6e  re zealous to en
4a20: 66 6f 72 63 65 20 74 68 69 73 2e 3c 2f 70 3e 0a  force this.</p>.
4a30: 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
4a40: 74 20 63 6f 76 65 72 61 67 65 20 7b 74 65 73 74  t coverage {test
4a50: 20 63 6f 76 65 72 61 67 65 7d 3c 2f 74 63 6c 3e   coverage}</tcl>
4a60: 0a 3c 68 32 3e 37 2e 30 20 54 65 73 74 20 43 6f  .<h2>7.0 Test Co
4a70: 76 65 72 61 67 65 3c 2f 68 32 3e 0a 0a 3c 70 3e  verage</h2>..<p>
4a80: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
4a90: 68 61 73 20 31 30 30 25 20 62 72 61 6e 63 68 20  has 100% branch 
4aa0: 74 65 73 74 20 63 6f 76 65 72 61 67 65 20 75 6e  test coverage un
4ab0: 64 65 72 20 5b 54 48 33 5d 20 61 73 20 6f 66 0a  der [TH3] as of.
4ac0: 32 30 30 39 2d 30 37 2d 32 35 2c 20 69 6e 20 69  2009-07-25, in i
4ad0: 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  ts default confi
4ae0: 67 75 72 61 74 69 6f 6e 20 61 73 20 6d 65 61 73  guration as meas
4af0: 75 72 65 64 20 62 79 0a 5b 68 74 74 70 3a 2f 2f  ured by.[http://
4b00: 67 63 63 2e 67 6e 75 2e 6f 72 67 2f 6f 6e 6c 69  gcc.gnu.org/onli
4b10: 6e 65 64 6f 63 73 2f 67 63 63 2f 47 63 6f 76 2e  nedocs/gcc/Gcov.
4b20: 68 74 6d 6c 20 7c 20 67 63 6f 76 5d 0a 75 74 69  html | gcov].uti
4b30: 6c 69 74 79 20 6f 6e 20 53 75 53 45 20 4c 69 6e  lity on SuSE Lin
4b40: 75 78 20 31 30 2e 31 20 6f 6e 20 78 38 36 20 68  ux 10.1 on x86 h
4b50: 61 72 64 77 61 72 65 20 77 69 74 68 20 74 68 65  ardware with the
4b60: 20 47 43 43 20 34 2e 30 2e 31 20 63 6f 6d 70 69   GCC 4.0.1 compi
4b70: 6c 65 72 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65  ler.</p>..<p>The
4b80: 20 22 53 51 4c 69 74 65 20 63 6f 72 65 22 20 69   "SQLite core" i
4b90: 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
4ba0: 61 72 61 67 72 61 70 68 20 65 78 63 6c 75 64 65  aragraph exclude
4bb0: 73 20 74 68 65 0a 6f 70 65 72 61 74 69 6e 67 2d  s the.operating-
4bc0: 73 79 73 74 65 6d 20 64 65 70 65 6e 64 65 6e 74  system dependent
4bd0: 20 5b 56 46 53 5d 20 62 61 63 6b 65 6e 64 73 2c   [VFS] backends,
4be0: 20 73 69 6e 63 65 20 69 74 20 69 73 0a 6e 6f 74   since it is.not
4bf0: 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 77 72 69   possible to wri
4c00: 74 65 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72  te cross-platfor
4c10: 6d 20 74 65 73 74 73 20 66 6f 72 20 74 68 6f 73  m tests for thos
4c20: 65 20 6d 6f 64 75 6c 65 73 2e 20 20 45 78 74 65  e modules.  Exte
4c30: 6e 73 69 6f 6e 73 0a 73 75 63 68 20 61 73 20 46  nsions.such as F
4c40: 54 53 33 20 61 6e 64 20 52 54 72 65 65 20 61 72  TS3 and RTree ar
4c50: 65 20 61 6c 73 6f 20 65 78 63 6c 75 64 65 64 20  e also excluded 
4c60: 66 72 6f 6d 20 74 68 65 20 61 6e 61 6c 79 73 69  from the analysi
4c70: 73 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f  s.</p>..<tcl>hd_
4c80: 66 72 61 67 6d 65 6e 74 20 73 74 6d 74 76 62 72  fragment stmtvbr
4c90: 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 37 2e 31 20 53  </tcl>.<h3>7.1 S
4ca0: 74 61 74 65 6d 65 6e 74 20 76 65 72 73 75 73 20  tatement versus 
4cb0: 62 72 61 6e 63 68 20 63 6f 76 65 72 61 67 65 3c  branch coverage<
4cc0: 2f 68 33 3e 0a 0a 3c 70 3e 54 68 65 72 65 20 61  /h3>..<p>There a
4cd0: 72 65 20 6d 61 6e 79 20 77 61 79 73 20 74 6f 20  re many ways to 
4ce0: 6d 65 61 73 75 72 65 20 74 65 73 74 20 63 6f 76  measure test cov
4cf0: 65 72 61 67 65 2e 20 20 54 68 65 20 6d 6f 73 74  erage.  The most
4d00: 20 70 6f 70 75 6c 61 72 0a 6d 65 74 72 69 63 20   popular.metric 
4d10: 69 73 20 22 73 74 61 74 65 6d 65 6e 74 20 63 6f  is "statement co
4d20: 76 65 72 61 67 65 22 2e 20 20 57 68 65 6e 20 79  verage".  When y
4d30: 6f 75 20 68 65 61 72 20 73 6f 6d 65 6f 6e 65 20  ou hear someone 
4d40: 73 61 79 20 74 68 61 74 20 74 68 65 69 72 0a 70  say that their.p
4d50: 72 6f 67 72 61 6d 20 61 73 20 22 58 58 25 20 74  rogram as "XX% t
4d60: 65 73 74 20 63 6f 76 65 72 61 67 65 22 20 77 69  est coverage" wi
4d70: 74 68 6f 75 74 20 66 75 72 74 68 65 72 20 65 78  thout further ex
4d80: 70 6c 61 6e 61 74 69 6f 6e 2c 20 74 68 65 79 20  planation, they 
4d90: 75 73 75 61 6c 6c 79 0a 6d 65 61 6e 20 73 74 61  usually.mean sta
4da0: 74 65 6d 65 6e 74 20 63 6f 76 65 72 61 67 65 2e  tement coverage.
4db0: 20 20 53 74 61 74 65 6d 65 6e 74 20 63 6f 76 65    Statement cove
4dc0: 72 61 67 65 20 6d 65 61 73 75 72 65 73 20 77 68  rage measures wh
4dd0: 61 74 20 70 65 72 63 65 6e 74 61 67 65 0a 6f 66  at percentage.of
4de0: 20 6c 69 6e 65 73 20 6f 66 20 63 6f 64 65 20 61   lines of code a
4df0: 72 65 20 65 78 65 63 75 74 65 64 20 61 74 20 6c  re executed at l
4e00: 65 61 73 74 20 6f 6e 63 65 20 62 79 20 74 68 65  east once by the
4e10: 20 74 65 73 74 20 73 75 69 74 65 2e 3c 2f 70 3e   test suite.</p>
4e20: 0a 0a 3c 70 3e 42 72 61 6e 63 68 20 63 6f 76 65  ..<p>Branch cove
4e30: 72 61 67 65 20 69 73 20 6d 6f 72 65 20 72 69 67  rage is more rig
4e40: 6f 72 6f 75 73 20 74 68 61 6e 20 73 74 61 74 65  orous than state
4e50: 6d 65 6e 74 20 63 6f 76 65 72 61 67 65 2e 20 20  ment coverage.  
4e60: 42 72 61 6e 63 68 0a 63 6f 76 65 72 61 67 65 20  Branch.coverage 
4e70: 6d 65 61 73 75 72 65 73 20 74 68 65 20 6e 75 6d  measures the num
4e80: 62 65 72 20 6f 66 20 6d 61 63 68 69 6e 65 2d 63  ber of machine-c
4e90: 6f 64 65 20 62 72 61 6e 63 68 20 69 6e 73 74 72  ode branch instr
4ea0: 75 63 74 69 6f 6e 73 20 74 68 61 74 0a 61 72 65  uctions that.are
4eb0: 20 65 76 61 6c 75 61 74 65 64 20 61 74 20 6c 65   evaluated at le
4ec0: 61 73 74 20 6f 6e 63 65 20 6f 6e 20 62 6f 74 68  ast once on both
4ed0: 20 64 69 72 65 63 74 69 6f 6e 73 2e 3c 2f 70 3e   directions.</p>
4ee0: 0a 0a 3c 70 3e 54 6f 20 69 6c 6c 75 73 74 72 61  ..<p>To illustra
4ef0: 74 65 20 74 68 65 20 64 69 66 66 65 72 65 6e 63  te the differenc
4f00: 65 20 62 65 74 77 65 65 6e 20 73 74 61 74 65 6d  e between statem
4f10: 65 6e 74 20 63 6f 76 65 72 61 67 65 20 61 6e 64  ent coverage and
4f20: 0a 62 72 61 6e 63 68 20 63 6f 76 65 72 61 67 65  .branch coverage
4f30: 2c 20 63 6f 6e 73 69 64 65 72 20 74 68 65 20 66  , consider the f
4f40: 6f 6c 6c 6f 77 69 6e 67 20 68 79 70 6f 74 68 65  ollowing hypothe
4f50: 74 69 63 61 6c 0a 6c 69 6e 65 20 6f 66 20 43 20  tical.line of C 
4f60: 63 6f 64 65 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63  code:</p>..<bloc
4f70: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 69 66 28  kquote><pre>.if(
4f80: 20 61 3e 62 20 26 26 20 63 21 3d 32 35 20 29 7b   a>b && c!=25 ){
4f90: 20 64 2b 2b 3b 20 7d 0a 3c 2f 70 72 65 3e 3c 2f   d++; }.</pre></
4fa0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e  blockquote>..<p>
4fb0: 53 75 63 68 20 61 20 6c 69 6e 65 20 6f 66 20 43  Such a line of C
4fc0: 20 63 6f 64 65 20 6d 69 67 68 74 20 67 65 6e 65   code might gene
4fd0: 72 61 74 65 20 61 20 64 6f 7a 65 6e 20 73 65 70  rate a dozen sep
4fe0: 61 72 61 74 65 20 6d 61 63 68 69 6e 65 20 63 6f  arate machine co
4ff0: 64 65 0a 69 6e 73 74 72 75 63 74 69 6f 6e 73 2e  de.instructions.
5000: 20 20 49 66 20 61 6e 79 20 6f 6e 65 20 6f 66 20    If any one of 
5010: 74 68 6f 73 65 20 69 6e 73 74 72 75 63 74 69 6f  those instructio
5020: 6e 73 20 69 73 20 65 76 65 72 20 65 76 61 6c 75  ns is ever evalu
5030: 61 74 65 64 2c 20 74 68 65 6e 0a 77 65 20 73 61  ated, then.we sa
5040: 79 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  y that the state
5050: 6d 65 6e 74 20 68 61 73 20 62 65 65 6e 20 74 65  ment has been te
5060: 73 74 65 64 2e 20 20 53 6f 2c 20 66 6f 72 20 65  sted.  So, for e
5070: 78 61 6d 70 6c 65 2c 20 69 74 20 6d 69 67 68 74  xample, it might
5080: 0a 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61  .be the case tha
5090: 74 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 61  t the conditiona
50a0: 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 0a  l expression is.
50b0: 61 6c 77 61 79 73 20 66 61 6c 73 65 20 61 6e 64  always false and
50c0: 20 74 68 65 20 22 64 22 20 76 61 72 69 61 62 6c   the "d" variabl
50d0: 65 20 69 73 0a 6e 65 76 65 72 20 69 6e 63 72 65  e is.never incre
50e0: 6d 65 6e 74 65 64 2e 20 20 45 76 65 6e 20 73 6f  mented.  Even so
50f0: 2c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 76 65  , statement cove
5100: 72 61 67 65 20 63 6f 75 6e 74 73 20 74 68 69 73  rage counts this
5110: 20 6c 69 6e 65 20 6f 66 0a 63 6f 64 65 20 61 73   line of.code as
5120: 20 68 61 76 69 6e 67 20 62 65 65 6e 20 74 65 73   having been tes
5130: 74 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 42 72 61  ted.</p>..<p>Bra
5140: 6e 63 68 20 63 6f 76 65 72 61 67 65 20 69 73 20  nch coverage is 
5150: 6d 6f 72 65 20 73 74 72 69 63 74 2e 20 20 57 69  more strict.  Wi
5160: 74 68 20 62 72 61 6e 63 68 20 63 6f 76 65 72 61  th branch covera
5170: 67 65 2c 20 65 61 63 68 20 74 65 73 74 20 61 6e  ge, each test an
5180: 64 0a 65 61 63 68 20 73 75 62 62 6c 6f 63 6b 20  d.each subblock 
5190: 77 69 74 68 69 6e 20 74 68 65 20 73 74 61 74 65  within the state
51a0: 6d 65 6e 74 20 69 73 20 63 6f 6e 73 69 64 65 72  ment is consider
51b0: 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
51c0: 49 6e 20 6f 72 64 65 72 0a 74 6f 20 61 63 68 69  In order.to achi
51d0: 65 76 65 20 31 30 30 25 20 62 72 61 6e 63 68 20  eve 100% branch 
51e0: 63 6f 76 65 72 61 67 65 20 69 6e 20 74 68 65 20  coverage in the 
51f0: 65 78 61 6d 70 6c 65 20 61 62 6f 76 65 2c 20 74  example above, t
5200: 68 65 72 65 20 6d 75 73 74 20 62 65 20 61 74 0a  here must be at.
5210: 6c 65 61 73 74 20 74 68 72 65 65 20 74 65 73 74  least three test
5220: 20 63 61 73 65 73 3a 3c 2f 70 3e 0a 0a 3c 70 3e   cases:</p>..<p>
5230: 3c 75 6c 3e 0a 3c 6c 69 3e 20 61 3c 3d 62 0a 3c  <ul>.<li> a<=b.<
5240: 6c 69 3e 20 61 3e 62 20 26 26 20 63 3d 3d 32 35  li> a>b && c==25
5250: 0a 3c 6c 69 3e 20 61 3e 62 20 26 26 20 63 21 3d  .<li> a>b && c!=
5260: 32 35 0a 3c 2f 75 6c 3e 3c 2f 70 3e 0a 0a 3c 70  25.</ul></p>..<p
5270: 3e 41 6e 79 20 6f 6e 65 20 6f 66 20 74 68 65 20  >Any one of the 
5280: 61 62 6f 76 65 20 74 65 73 74 20 63 61 73 65 73  above test cases
5290: 20 77 6f 75 6c 64 20 70 72 6f 76 69 64 65 20 31   would provide 1
52a0: 30 30 25 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  00% statement co
52b0: 76 65 72 61 67 65 0a 62 75 74 20 61 6c 6c 20 74  verage.but all t
52c0: 68 72 65 65 20 61 72 65 20 72 65 71 75 69 72 65  hree are require
52d0: 64 20 66 6f 72 20 31 30 30 25 20 62 72 61 6e 63  d for 100% branc
52e0: 68 20 63 6f 76 65 72 61 67 65 2e 20 20 47 65 6e  h coverage.  Gen
52f0: 65 72 61 6c 6c 79 20 73 70 65 61 6b 69 6e 67 2c  erally speaking,
5300: 0a 31 30 30 25 20 62 72 61 6e 63 68 20 63 6f 76  .100% branch cov
5310: 65 72 61 67 65 20 69 6d 70 6c 69 65 73 20 31 30  erage implies 10
5320: 30 25 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 76  0% statement cov
5330: 65 72 61 67 65 2c 20 62 75 74 20 74 68 65 20 63  erage, but the c
5340: 6f 6e 76 65 72 73 65 20 69 73 0a 6e 6f 74 20 74  onverse is.not t
5350: 72 75 65 2e 20 20 54 6f 20 72 65 65 6d 70 68 61  rue.  To reempha
5360: 73 69 7a 65 2c 20 74 68 65 0a 5b 54 48 33 5d 20  size, the.[TH3] 
5370: 74 65 73 74 20 68 61 72 6e 65 73 73 20 66 6f 72  test harness for
5380: 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
5390: 20 74 68 65 20 73 74 72 6f 6e 67 65 72 20 66 6f   the stronger fo
53a0: 72 6d 20 6f 66 0a 74 65 73 74 20 63 6f 76 65 72  rm of.test cover
53b0: 61 67 65 20 2d 20 31 30 30 25 20 62 72 61 6e 63  age - 100% branc
53c0: 68 20 74 65 73 74 20 63 6f 76 65 72 61 67 65 2e  h test coverage.
53d0: 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72  </p>..<tcl>hd_fr
53e0: 61 67 6d 65 6e 74 20 64 65 66 65 6e 73 69 76 65  agment defensive
53f0: 63 6f 64 65 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 37  code</tcl>.<h3>7
5400: 2e 32 20 43 6f 76 65 72 61 67 65 20 74 65 73 74  .2 Coverage test
5410: 69 6e 67 20 6f 66 20 64 65 66 65 6e 73 69 76 65  ing of defensive
5420: 20 63 6f 64 65 3c 2f 68 33 3e 0a 0a 3c 70 3e 41   code</h3>..<p>A
5430: 20 77 65 6c 6c 2d 77 72 69 74 74 65 6e 20 43 20   well-written C 
5440: 70 72 6f 67 72 61 6d 20 77 69 6c 6c 20 74 79 70  program will typ
5450: 69 63 61 6c 6c 79 20 63 6f 6e 74 61 69 6e 20 73  ically contain s
5460: 6f 6d 65 20 64 65 66 65 6e 73 69 76 65 20 74 65  ome defensive te
5470: 73 74 73 0a 77 68 69 63 68 20 69 6e 20 70 72 61  sts.which in pra
5480: 63 74 69 63 65 20 61 72 65 20 61 6c 77 61 79 73  ctice are always
5490: 20 74 72 75 65 20 6f 72 20 61 6c 77 61 79 73 20   true or always 
54a0: 66 61 6c 73 65 2e 20 20 54 68 69 73 20 6c 65 61  false.  This lea
54b0: 64 73 20 74 6f 20 61 20 0a 70 72 6f 67 72 61 6d  ds to a .program
54c0: 6d 69 6e 67 20 64 69 6c 65 6d 6d 61 3a 20 20 44  ming dilemma:  D
54d0: 6f 65 73 20 6f 6e 65 20 72 65 6d 6f 76 65 20 64  oes one remove d
54e0: 65 66 65 6e 73 69 76 65 20 63 6f 64 65 20 69 6e  efensive code in
54f0: 20 6f 72 64 65 72 20 74 6f 20 6f 62 74 61 69 6e   order to obtain
5500: 0a 31 30 30 25 20 62 72 61 6e 63 68 20 63 6f 76  .100% branch cov
5510: 65 72 61 67 65 3f 3c 2f 70 3e 0a 0a 3c 70 3e 49  erage?</p>..<p>I
5520: 6e 20 53 51 4c 69 74 65 2c 20 74 68 65 20 61 6e  n SQLite, the an
5530: 73 77 65 72 20 74 6f 20 74 68 65 20 70 72 65 76  swer to the prev
5540: 69 6f 75 73 20 71 75 65 73 74 69 6f 6e 20 69 73  ious question is
5550: 20 22 6e 6f 22 2e 0a 46 6f 72 20 74 65 73 74 69   "no"..For testi
5560: 6e 67 20 70 75 72 70 6f 73 65 73 2c 20 74 68 65  ng purposes, the
5570: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
5580: 6f 64 65 20 64 65 66 69 6e 65 73 0a 6d 61 63 72  ode defines.macr
5590: 6f 73 20 63 61 6c 6c 65 64 20 41 4c 57 41 59 53  os called ALWAYS
55a0: 28 29 20 61 6e 64 20 4e 45 56 45 52 28 29 2e 20  () and NEVER(). 
55b0: 20 20 54 68 65 20 41 4c 57 41 59 53 28 29 20 6d    The ALWAYS() m
55c0: 61 63 72 6f 0a 73 75 72 72 6f 75 6e 64 73 20 63  acro.surrounds c
55d0: 6f 6e 64 69 74 69 6f 6e 73 0a 77 68 69 63 68 20  onditions.which 
55e0: 61 72 65 20 65 78 70 65 63 74 65 64 20 74 6f 20  are expected to 
55f0: 61 6c 77 61 79 73 20 65 76 61 6c 75 61 74 65 20  always evaluate 
5600: 61 73 20 74 72 75 65 20 61 6e 64 20 4e 45 56 45  as true and NEVE
5610: 52 28 29 20 73 75 72 72 6f 75 6e 64 73 0a 63 6f  R() surrounds.co
5620: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 61 72  nditions that ar
5630: 65 20 61 6c 77 61 79 73 20 65 76 61 6c 75 61 74  e always evaluat
5640: 65 64 20 74 6f 20 66 61 6c 73 65 2e 20 20 54 68  ed to false.  Th
5650: 65 73 65 20 6d 61 63 72 6f 73 20 73 65 72 76 65  ese macros serve
5660: 20 61 73 0a 63 6f 6d 6d 65 6e 74 73 20 74 6f 20   as.comments to 
5670: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 74 68  indicate that th
5680: 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 61 72 65  e conditions are
5690: 20 64 65 66 65 6e 73 69 76 65 20 63 6f 64 65 2e   defensive code.
56a0: 0a 46 6f 72 20 73 74 61 6e 64 61 72 64 20 62 75  .For standard bu
56b0: 69 6c 64 73 2c 20 74 68 65 73 65 20 6d 61 63 72  ilds, these macr
56c0: 6f 73 20 61 72 65 20 70 61 73 73 2d 74 68 72 6f  os are pass-thro
56d0: 75 67 68 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63  ughs:</p>..<bloc
56e0: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 23 64 65  kquote><pre>.#de
56f0: 66 69 6e 65 20 41 4c 57 41 59 53 28 58 29 20 20  fine ALWAYS(X)  
5700: 28 58 29 0a 23 64 65 66 69 6e 65 20 4e 45 56 45  (X).#define NEVE
5710: 52 28 58 29 20 20 20 28 58 29 0a 3c 2f 70 72 65  R(X)   (X).</pre
5720: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  ></blockquote>..
5730: 3c 70 3e 44 75 72 69 6e 67 20 6d 6f 73 74 20 74  <p>During most t
5740: 65 73 74 69 6e 67 2c 20 68 6f 77 65 76 65 72 2c  esting, however,
5750: 20 74 68 65 73 65 20 6d 61 63 72 6f 73 20 77 69   these macros wi
5760: 6c 6c 20 74 68 72 6f 77 20 61 6e 20 61 73 73 65  ll throw an asse
5770: 72 74 69 6f 6e 0a 66 61 75 6c 74 20 69 66 20 74  rtion.fault if t
5780: 68 65 69 72 20 61 72 67 75 6d 65 6e 74 20 64 6f  heir argument do
5790: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 68 65 20  es not have the 
57a0: 65 78 70 65 63 74 65 64 20 74 72 75 74 68 20 76  expected truth v
57b0: 61 6c 75 65 2e 20 20 54 68 69 73 0a 61 6c 65 72  alue.  This.aler
57c0: 74 73 20 74 68 65 20 64 65 76 65 6c 6f 70 65 72  ts the developer
57d0: 73 20 71 75 69 63 6b 6c 79 20 74 6f 20 69 6e 63  s quickly to inc
57e0: 6f 72 72 65 63 74 20 64 65 73 69 67 6e 20 61 73  orrect design as
57f0: 73 75 6d 70 74 69 6f 6e 73 2e 0a 0a 3c 62 6c 6f  sumptions...<blo
5800: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 23 64  ckquote><pre>.#d
5810: 65 66 69 6e 65 20 41 4c 57 41 59 53 28 58 29 20  efine ALWAYS(X) 
5820: 20 28 28 58 29 3f 31 3a 61 73 73 65 72 74 28 30   ((X)?1:assert(0
5830: 29 2c 30 29 0a 23 64 65 66 69 6e 65 20 4e 45 56  ),0).#define NEV
5840: 45 52 28 58 29 20 20 20 28 28 58 29 3f 61 73 73  ER(X)   ((X)?ass
5850: 65 72 74 28 30 29 2c 31 3a 30 29 0a 3c 2f 70 72  ert(0),1:0).</pr
5860: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
5870: 0a 3c 70 3e 57 68 65 6e 20 6d 65 61 73 75 72 69  .<p>When measuri
5880: 6e 67 20 74 65 73 74 20 63 6f 76 65 72 61 67 65  ng test coverage
5890: 2c 20 74 68 65 73 65 20 6d 61 63 72 6f 73 20 61  , these macros a
58a0: 72 65 20 64 65 66 69 6e 65 64 20 74 6f 20 62 65  re defined to be
58b0: 20 63 6f 6e 73 74 61 6e 74 0a 74 72 75 74 68 20   constant.truth 
58c0: 76 61 6c 75 65 73 20 73 6f 20 74 68 61 74 20 74  values so that t
58d0: 68 65 79 20 64 6f 20 6e 6f 74 20 67 65 6e 65 72  hey do not gener
58e0: 61 74 65 20 61 73 73 65 6d 62 6c 79 20 6c 61 6e  ate assembly lan
58f0: 67 75 61 67 65 20 62 72 61 6e 63 68 0a 69 6e 73  guage branch.ins
5900: 74 72 75 63 74 69 6f 6e 73 2c 20 61 6e 64 20 68  tructions, and h
5910: 65 6e 63 65 20 64 6f 20 6e 6f 74 20 63 6f 6d 65  ence do not come
5920: 20 69 6e 74 6f 20 70 6c 61 79 20 77 68 65 6e 20   into play when 
5930: 63 61 6c 63 75 6c 61 74 69 6e 67 20 74 68 65 0a  calculating the.
5940: 62 72 61 6e 63 68 20 63 6f 76 65 72 61 67 65 3a  branch coverage:
5950: 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  </p>..<blockquot
5960: 65 3e 3c 70 72 65 3e 0a 23 64 65 66 69 6e 65 20  e><pre>.#define 
5970: 41 4c 57 41 59 53 28 58 29 20 20 28 31 29 0a 23  ALWAYS(X)  (1).#
5980: 64 65 66 69 6e 65 20 4e 45 56 45 52 28 58 29 20  define NEVER(X) 
5990: 20 20 28 30 29 0a 3c 2f 70 72 65 3e 3c 2f 62 6c    (0).</pre></bl
59a0: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68  ockquote>..<p>Th
59b0: 65 20 74 65 73 74 20 73 75 69 74 65 20 69 73 20  e test suite is 
59c0: 64 65 73 69 67 6e 65 64 20 74 6f 20 62 65 20 72  designed to be r
59d0: 75 6e 20 74 68 72 65 65 20 74 69 6d 65 73 2c 20  un three times, 
59e0: 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 6f 66  once for each of
59f0: 0a 74 68 65 20 41 4c 57 41 59 53 28 29 20 61 6e  .the ALWAYS() an
5a00: 64 20 4e 45 56 45 52 28 29 20 64 65 66 69 6e 69  d NEVER() defini
5a10: 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
5a20: 65 2e 20 20 41 6c 6c 20 74 68 72 65 65 20 74 65  e.  All three te
5a30: 73 74 20 72 75 6e 73 0a 73 68 6f 75 6c 64 20 79  st runs.should y
5a40: 69 65 6c 64 20 65 78 61 63 74 6c 79 20 74 68 65  ield exactly the
5a50: 20 73 61 6d 65 20 72 65 73 75 6c 74 2e 20 20 54   same result.  T
5a60: 68 65 72 65 20 69 73 20 61 20 72 75 6e 2d 74 69  here is a run-ti
5a70: 6d 65 20 74 65 73 74 20 75 73 69 6e 67 0a 74 68  me test using.th
5a80: 65 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f  e [sqlite3_test_
5a90: 63 6f 6e 74 72 6f 6c 5d 28 5b 53 51 4c 49 54 45  control]([SQLITE
5aa0: 5f 54 45 53 54 43 54 52 4c 5f 41 4c 57 41 59 53  _TESTCTRL_ALWAYS
5ab0: 5d 2c 20 2e 2e 2e 29 20 69 6e 74 65 72 66 61 63  ], ...) interfac
5ac0: 65 20 74 68 61 74 0a 63 61 6e 20 62 65 20 75 73  e that.can be us
5ad0: 65 64 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  ed to verify tha
5ae0: 74 20 74 68 65 20 6d 61 63 72 6f 73 20 61 72 65  t the macros are
5af0: 20 63 6f 72 72 65 63 74 6c 79 20 73 65 74 20 74   correctly set t
5b00: 6f 20 74 68 65 20 66 69 72 73 74 0a 66 6f 72 6d  o the first.form
5b10: 20 28 74 68 65 20 70 61 73 73 2d 74 68 72 6f 75   (the pass-throu
5b20: 67 68 20 66 6f 72 6d 29 20 66 6f 72 20 64 65 70  gh form) for dep
5b30: 6c 6f 79 6d 65 6e 74 2e 3c 2f 70 3e 0a 0a 3c 74  loyment.</p>..<t
5b40: 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 7b  cl>hd_fragment {
5b50: 74 65 73 74 63 61 73 65 7d 20 7b 74 65 73 74 63  testcase} {testc
5b60: 61 73 65 20 6d 61 63 72 6f 73 7d 3c 2f 74 63 6c  ase macros}</tcl
5b70: 3e 0a 3c 68 33 3e 37 2e 33 20 46 6f 72 63 69 6e  >.<h3>7.3 Forcin
5b80: 67 20 63 6f 76 65 72 61 67 65 20 6f 66 20 62 6f  g coverage of bo
5b90: 75 6e 64 61 72 79 20 76 61 6c 75 65 73 20 61 6e  undary values an
5ba0: 64 20 62 6f 6f 6c 65 61 6e 20 76 65 63 74 6f 72  d boolean vector
5bb0: 20 74 65 73 74 73 3c 2f 68 33 3e 0a 0a 3c 70 3e   tests</h3>..<p>
5bc0: 41 6e 6f 74 68 65 72 20 6d 61 63 72 6f 20 75 73  Another macro us
5bd0: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
5be0: 6e 20 77 69 74 68 20 74 65 73 74 20 63 6f 76 65  n with test cove
5bf0: 72 61 67 65 20 6d 65 61 73 75 72 65 6d 65 6e 74  rage measurement
5c00: 20 69 73 0a 74 68 65 20 3c 74 74 3e 74 65 73 74   is.the <tt>test
5c10: 63 61 73 65 28 29 3c 2f 74 74 3e 20 6d 61 63 72  case()</tt> macr
5c20: 6f 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  o.  The argument
5c30: 20 69 73 20 61 20 63 6f 6e 64 69 74 69 6f 6e 20   is a condition 
5c40: 66 6f 72 20 77 68 69 63 68 0a 77 65 20 77 61 6e  for which.we wan
5c50: 74 20 74 65 73 74 20 63 61 73 65 73 20 74 68 61  t test cases tha
5c60: 74 20 65 76 61 6c 75 61 74 65 20 74 6f 20 62 6f  t evaluate to bo
5c70: 74 68 20 74 72 75 65 20 61 6e 64 20 66 61 6c 73  th true and fals
5c80: 65 2e 0a 49 6e 20 6e 6f 6e 2d 63 6f 76 65 72 61  e..In non-covera
5c90: 67 65 20 62 75 69 6c 64 73 20 28 74 68 61 74 20  ge builds (that 
5ca0: 69 73 20 74 6f 20 73 61 79 2c 20 69 6e 20 72 65  is to say, in re
5cb0: 6c 65 61 73 65 20 62 75 69 6c 64 73 29 20 74 68  lease builds) th
5cc0: 65 0a 3c 74 74 3e 74 65 73 74 63 61 73 65 28 29  e.<tt>testcase()
5cd0: 3c 2f 74 74 3e 20 6d 61 63 72 6f 20 69 73 20 61  </tt> macro is a
5ce0: 20 6e 6f 2d 6f 70 3a 3c 2f 70 3e 0a 0a 3c 62 6c   no-op:</p>..<bl
5cf0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 23  ockquote><pre>.#
5d00: 64 65 66 69 6e 65 20 74 65 73 74 63 61 73 65 28  define testcase(
5d10: 58 29 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  X).</pre></block
5d20: 71 75 6f 74 65 3e 0a 0a 3c 70 3e 42 75 74 20 69  quote>..<p>But i
5d30: 6e 20 61 20 63 6f 76 65 72 61 67 65 20 6d 65 61  n a coverage mea
5d40: 73 75 72 69 6e 67 20 62 75 69 6c 64 2c 20 74 68  suring build, th
5d50: 65 20 3c 74 74 3e 74 65 73 74 63 61 73 65 28 29  e <tt>testcase()
5d60: 3c 2f 74 74 3e 20 6d 61 63 72 6f 0a 67 65 6e 65  </tt> macro.gene
5d70: 72 61 74 65 73 20 63 6f 64 65 20 74 68 61 74 20  rates code that 
5d80: 65 76 61 6c 75 61 74 65 73 20 74 68 65 20 63 6f  evaluates the co
5d90: 6e 64 69 74 69 6f 6e 61 6c 20 65 78 70 72 65 73  nditional expres
5da0: 73 69 6f 6e 20 69 6e 20 69 74 73 20 61 72 67 75  sion in its argu
5db0: 6d 65 6e 74 2e 20 20 0a 54 68 65 6e 20 64 75 72  ment.  .Then dur
5dc0: 69 6e 67 20 61 6e 61 6c 79 73 69 73 2c 20 61 20  ing analysis, a 
5dd0: 63 68 65 63 6b 0a 69 73 20 6d 61 64 65 20 74 6f  check.is made to
5de0: 20 65 6e 73 75 72 65 20 74 65 73 74 73 20 65 78   ensure tests ex
5df0: 69 73 74 20 74 68 61 74 20 65 76 61 6c 75 61 74  ist that evaluat
5e00: 65 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 61  e the conditiona
5e10: 6c 20 74 6f 20 62 6f 74 68 20 74 72 75 65 0a 61  l to both true.a
5e20: 6e 64 20 66 61 6c 73 65 2e 20 20 3c 74 74 3e 54  nd false.  <tt>T
5e30: 65 73 74 63 61 73 65 28 29 3c 2f 74 74 3e 20 6d  estcase()</tt> m
5e40: 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 2c 20  acros are used, 
5e50: 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20  for example, to 
5e60: 68 65 6c 70 20 76 65 72 69 66 79 0a 74 68 61 74  help verify.that
5e70: 20 62 6f 75 6e 64 61 72 79 20 76 61 6c 75 65 73   boundary values
5e80: 20 61 72 65 20 74 65 73 74 65 64 2e 20 20 46 6f   are tested.  Fo
5e90: 72 20 65 78 61 6d 70 6c 65 3a 3c 2f 70 3e 0a 0a  r example:</p>..
5ea0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
5eb0: 3e 0a 74 65 73 74 63 61 73 65 28 20 61 3d 3d 62  >.testcase( a==b
5ec0: 20 29 3b 0a 74 65 73 74 63 61 73 65 28 20 61 3d   );.testcase( a=
5ed0: 3d 62 2b 31 20 29 3b 0a 69 66 28 20 61 3e 62 20  =b+1 );.if( a>b 
5ee0: 26 26 20 63 21 3d 32 35 20 29 7b 20 64 2b 2b 3b  && c!=25 ){ d++;
5ef0: 20 7d 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b   }.</pre></block
5f00: 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 65 73 74 63  quote>..<p>Testc
5f10: 61 73 65 20 6d 61 63 72 6f 73 20 61 72 65 20 61  ase macros are a
5f20: 6c 73 6f 20 75 73 65 64 20 77 68 65 6e 20 74 77  lso used when tw
5f30: 6f 20 6f 72 20 6d 6f 72 65 20 63 61 73 65 73 20  o or more cases 
5f40: 6f 66 20 61 20 73 77 69 74 63 68 0a 73 74 61 74  of a switch.stat
5f50: 65 6d 65 6e 74 20 67 6f 20 74 6f 20 74 68 65 20  ement go to the 
5f60: 73 61 6d 65 20 62 6c 6f 63 6b 20 6f 66 20 63 6f  same block of co
5f70: 64 65 2c 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  de, to make sure
5f80: 20 74 68 61 74 20 74 68 65 20 63 6f 64 65 20 77   that the code w
5f90: 61 73 0a 72 65 61 63 68 65 64 20 66 6f 72 20 61  as.reached for a
5fa0: 6c 6c 20 63 61 73 65 73 3a 3c 2f 70 3e 0a 0a 3c  ll cases:</p>..<
5fb0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
5fc0: 0a 73 77 69 74 63 68 28 20 6f 70 20 29 7b 0a 20  .switch( op ){. 
5fd0: 20 63 61 73 65 20 4f 50 5f 41 64 64 3a 0a 20 20   case OP_Add:.  
5fe0: 63 61 73 65 20 4f 50 5f 53 75 62 74 72 61 63 74  case OP_Subtract
5ff0: 3a 20 7b 0a 20 20 20 20 74 65 73 74 63 61 73 65  : {.    testcase
6000: 28 20 6f 70 3d 3d 4f 50 5f 41 64 64 20 29 3b 0a  ( op==OP_Add );.
6010: 20 20 20 20 74 65 73 74 63 61 73 65 28 20 6f 70      testcase( op
6020: 3d 3d 4f 50 5f 53 75 62 74 72 61 63 74 20 29 3b  ==OP_Subtract );
6030: 0a 20 20 20 20 2f 2a 20 2e 2e 2e 20 2a 2f 0a 20  .    /* ... */. 
6040: 20 20 20 62 72 65 61 6b 3b 0a 20 20 7d 0a 20 20     break;.  }.  
6050: 2f 2a 20 2e 2e 2e 20 2a 2f 0a 7d 0a 3c 2f 70 72  /* ... */.}.</pr
6060: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
6070: 0a 3c 70 3e 46 6f 72 20 62 69 74 6d 61 73 6b 20  .<p>For bitmask 
6080: 74 65 73 74 73 2c 20 3c 74 74 3e 74 65 73 74 63  tests, <tt>testc
6090: 61 73 65 28 29 3c 2f 74 74 3e 20 6d 61 63 72 6f  ase()</tt> macro
60a0: 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 76 65  s are used to ve
60b0: 72 69 66 79 20 74 68 61 74 20 65 76 65 72 79 0a  rify that every.
60c0: 62 69 74 20 6f 66 20 74 68 65 20 62 69 74 6d 61  bit of the bitma
60d0: 73 6b 20 61 66 66 65 63 74 73 20 74 68 65 20 74  sk affects the t
60e0: 65 73 74 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  est.  For exampl
60f0: 65 2c 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  e, in the follow
6100: 69 6e 67 20 62 6c 6f 63 6b 0a 6f 66 20 63 6f 64  ing block.of cod
6110: 65 2c 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e  e, the condition
6120: 20 69 73 20 74 72 75 65 20 69 66 20 74 68 65 20   is true if the 
6130: 6d 61 73 6b 20 63 6f 6e 74 61 69 6e 73 20 65 69  mask contains ei
6140: 74 68 65 72 20 6f 66 20 74 77 6f 20 62 69 74 73  ther of two bits
6150: 0a 69 6e 64 69 63 61 74 69 6e 67 20 65 69 74 68  .indicating eith
6160: 65 72 20 61 20 4d 41 49 4e 5f 44 42 20 6f 72 20  er a MAIN_DB or 
6170: 61 20 54 45 4d 50 5f 44 42 20 69 73 20 62 65 69  a TEMP_DB is bei
6180: 6e 67 20 6f 70 65 6e 65 64 2e 20 20 0a 54 68 65  ng opened.  .The
6190: 20 3c 74 74 3e 74 65 73 74 63 61 73 65 28 29 3c   <tt>testcase()<
61a0: 2f 74 74 3e 0a 6d 61 63 72 6f 73 20 74 68 61 74  /tt>.macros that
61b0: 20 70 72 65 63 65 64 65 20 74 68 65 20 69 66 20   precede the if 
61c0: 73 74 61 74 65 6d 65 6e 74 20 76 65 72 69 66 79  statement verify
61d0: 20 74 68 61 74 20 62 6f 74 68 20 63 61 73 65 73   that both cases
61e0: 20 61 72 65 20 74 65 73 74 65 64 3a 3c 2f 70 3e   are tested:</p>
61f0: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  ..<blockquote><p
6200: 72 65 3e 0a 74 65 73 74 63 61 73 65 28 20 6d 61  re>.testcase( ma
6210: 73 6b 20 26 20 53 51 4c 49 54 45 5f 4f 50 45 4e  sk & SQLITE_OPEN
6220: 5f 4d 41 49 4e 5f 44 42 20 29 3b 0a 74 65 73 74  _MAIN_DB );.test
6230: 63 61 73 65 28 20 6d 61 73 6b 20 26 20 53 51 4c  case( mask & SQL
6240: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
6250: 20 29 3b 0a 69 66 28 20 28 6d 61 73 6b 20 26 20   );.if( (mask & 
6260: 28 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  (SQLITE_OPEN_MAI
6270: 4e 5f 44 42 7c 53 51 4c 49 54 45 5f 4f 50 45 4e  N_DB|SQLITE_OPEN
6280: 5f 54 45 4d 50 5f 44 42 29 29 21 3d 30 20 29 7b  _TEMP_DB))!=0 ){
6290: 20 2e 2e 2e 20 7d 0a 3c 2f 70 72 65 3e 3c 2f 62   ... }.</pre></b
62a0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54  lockquote>..<p>T
62b0: 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  he SQLite source
62c0: 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 3c   code contains <
62d0: 74 63 6c 3e 4e 20 7b 24 73 74 61 74 28 6e 54 65  tcl>N {$stat(nTe
62e0: 73 74 63 61 73 65 29 7d 3c 2f 74 63 6c 3e 0a 75  stcase)}</tcl>.u
62f0: 73 65 73 20 6f 66 20 74 68 65 20 3c 74 74 3e 74  ses of the <tt>t
6300: 65 73 74 63 61 73 65 28 29 3c 2f 74 74 3e 20 6d  estcase()</tt> m
6310: 61 63 72 6f 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e  acro.</p>..<tcl>
6320: 68 64 5f 66 72 61 67 6d 65 6e 74 20 7b 6d 63 64  hd_fragment {mcd
6330: 63 7d 20 2a 4d 43 2f 44 43 20 7b 4d 43 2f 44 43  c} *MC/DC {MC/DC
6340: 20 74 65 73 74 69 6e 67 7d 3c 2f 74 63 6c 3e 0a   testing}</tcl>.
6350: 3c 68 33 3e 37 2e 34 20 42 72 61 6e 63 68 20 63  <h3>7.4 Branch c
6360: 6f 76 65 72 61 67 65 20 76 65 72 73 75 73 20 4d  overage versus M
6370: 43 2f 44 43 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 77  C/DC</h3>..<p>Tw
6380: 6f 20 6d 65 74 68 6f 64 73 20 6f 66 20 6d 65 61  o methods of mea
6390: 73 75 72 69 6e 67 20 74 65 73 74 20 63 6f 76 65  suring test cove
63a0: 72 61 67 65 20 77 65 72 65 20 64 65 73 63 72 69  rage were descri
63b0: 62 65 64 20 61 62 6f 76 65 3a 0a 22 73 74 61 74  bed above:."stat
63c0: 65 6d 65 6e 74 22 20 61 6e 64 20 22 62 72 61 6e  ement" and "bran
63d0: 63 68 22 20 63 6f 76 65 72 61 67 65 2e 20 20 54  ch" coverage.  T
63e0: 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74  here are many ot
63f0: 68 65 72 20 74 65 73 74 20 63 6f 76 65 72 61 67  her test coverag
6400: 65 0a 6d 65 74 72 69 63 73 20 62 65 73 69 64 65  e.metrics beside
6410: 73 20 74 68 65 73 65 20 74 77 6f 2e 20 20 41 6e  s these two.  An
6420: 6f 74 68 65 72 20 70 6f 70 75 6c 61 72 20 6d 65  other popular me
6430: 74 72 69 63 20 69 73 20 22 4d 6f 64 69 66 69 65  tric is "Modifie
6440: 64 0a 43 6f 6e 64 69 74 69 6f 6e 2f 44 65 63 69  d.Condition/Deci
6450: 73 69 6f 6e 20 43 6f 76 65 72 61 67 65 22 20 6f  sion Coverage" o
6460: 72 20 4d 43 2f 44 43 2e 20 20 0a 5b 68 74 74 70  r MC/DC.  .[http
6470: 3a 2f 2f 65 6e 2e 77 69 6b 69 70 65 64 69 61 2e  ://en.wikipedia.
6480: 6f 72 67 2f 77 69 6b 69 2f 4d 6f 64 69 66 69 65  org/wiki/Modifie
6490: 64 5f 43 6f 6e 64 69 74 69 6f 6e 2f 44 65 63 69  d_Condition/Deci
64a0: 73 69 6f 6e 5f 43 6f 76 65 72 61 67 65 20 7c 20  sion_Coverage | 
64b0: 57 69 6b 69 70 65 64 69 61 5d 0a 64 65 66 69 6e  Wikipedia].defin
64c0: 65 73 20 4d 43 2f 44 43 20 61 73 20 66 6f 6c 6c  es MC/DC as foll
64d0: 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c 75 6c 3e 0a 3c  ows:</p>..<ul>.<
64e0: 6c 69 3e 20 45 61 63 68 20 64 65 63 69 73 69 6f  li> Each decisio
64f0: 6e 20 74 72 69 65 73 20 65 76 65 72 79 20 70 6f  n tries every po
6500: 73 73 69 62 6c 65 20 6f 75 74 63 6f 6d 65 2e 0a  ssible outcome..
6510: 3c 6c 69 3e 20 45 61 63 68 20 63 6f 6e 64 69 74  <li> Each condit
6520: 69 6f 6e 20 69 6e 20 61 20 64 65 63 69 73 69 6f  ion in a decisio
6530: 6e 20 74 61 6b 65 73 20 6f 6e 20 65 76 65 72 79  n takes on every
6540: 20 70 6f 73 73 69 62 6c 65 20 6f 75 74 63 6f 6d   possible outcom
6550: 65 2e 0a 3c 6c 69 3e 20 45 61 63 68 20 65 6e 74  e..<li> Each ent
6560: 72 79 20 61 6e 64 20 65 78 69 74 20 70 6f 69 6e  ry and exit poin
6570: 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 3c 6c  t is invoked..<l
6580: 69 3e 20 45 61 63 68 20 63 6f 6e 64 69 74 69 6f  i> Each conditio
6590: 6e 20 69 6e 20 61 20 64 65 63 69 73 69 6f 6e 20  n in a decision 
65a0: 69 73 20 73 68 6f 77 6e 20 74 6f 20 69 6e 64 65  is shown to inde
65b0: 70 65 6e 64 65 6e 74 6c 79 0a 20 20 20 20 20 61  pendently.     a
65c0: 66 66 65 63 74 20 74 68 65 20 6f 75 74 63 6f 6d  ffect the outcom
65d0: 65 20 6f 66 20 74 68 65 20 64 65 63 69 73 69 6f  e of the decisio
65e0: 6e 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 49 6e 20  n..</ul>..<p>In 
65f0: 74 68 65 20 43 20 70 72 6f 67 72 61 6d 6d 69 6e  the C programmin
6600: 67 20 6c 61 6e 67 75 61 67 65 20 0a 77 68 65 72  g language .wher
6610: 65 20 3c 62 3e 3c 74 74 3e 26 61 6d 70 3b 26 61  e <b><tt>&amp;&a
6620: 6d 70 3b 3c 2f 74 74 3e 3c 2f 62 3e 20 61 6e 64  mp;</tt></b> and
6630: 20 3c 62 3e 3c 74 74 3e 7c 7c 3c 2f 74 74 3e 3c   <b><tt>||</tt><
6640: 2f 62 3e 0a 61 72 65 20 22 73 68 6f 72 74 2d 63  /b>.are "short-c
6650: 69 72 63 75 69 74 22 20 6f 70 65 72 61 74 6f 72  ircuit" operator
6660: 73 2c 20 4d 43 2f 44 43 20 61 6e 64 20 62 72 61  s, MC/DC and bra
6670: 6e 63 68 20 63 6f 76 65 72 61 67 65 20 61 72 65  nch coverage are
6680: 20 76 65 72 79 20 6e 65 61 72 6c 79 0a 74 68 65   very nearly.the
6690: 20 73 61 6d 65 20 74 68 69 6e 67 2e 20 20 54 68   same thing.  Th
66a0: 65 20 70 72 69 6d 61 72 79 20 64 69 66 66 65 72  e primary differ
66b0: 65 6e 63 65 20 69 73 20 69 6e 20 62 6f 6f 6c 65  ence is in boole
66c0: 61 6e 20 76 65 63 74 6f 72 20 74 65 73 74 73 2e  an vector tests.
66d0: 0a 4f 6e 65 20 63 61 6e 20 74 65 73 74 20 66 6f  .One can test fo
66e0: 72 20 61 6e 79 20 6f 66 20 73 65 76 65 72 61 6c  r any of several
66f0: 20 62 69 74 73 20 69 6e 20 62 69 74 2d 76 65 63   bits in bit-vec
6700: 74 6f 72 20 61 6e 64 20 73 74 69 6c 6c 20 6f 62  tor and still ob
6710: 74 61 69 6e 0a 31 30 30 25 20 62 72 61 6e 63 68  tain.100% branch
6720: 20 74 65 73 74 20 63 6f 76 65 72 61 67 65 20 65   test coverage e
6730: 76 65 6e 20 74 68 6f 75 67 68 20 74 68 65 20 73  ven though the s
6740: 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66  econd element of
6750: 20 4d 43 2f 44 43 20 2d 20 74 68 65 0a 72 65 71   MC/DC - the.req
6760: 75 69 72 65 6d 65 6e 74 20 74 68 61 74 20 65 61  uirement that ea
6770: 63 68 20 63 6f 6e 64 69 74 69 6f 6e 20 69 6e 20  ch condition in 
6780: 61 20 64 65 63 69 73 69 6f 6e 20 74 61 6b 65 20  a decision take 
6790: 6f 6e 20 65 76 65 72 79 20 70 6f 73 73 69 62 6c  on every possibl
67a0: 65 20 6f 75 74 63 6f 6d 65 20 2d 0a 6d 69 67 68  e outcome -.migh
67b0: 74 20 6e 6f 74 20 62 65 20 73 61 74 69 73 66 69  t not be satisfi
67c0: 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 53 51 4c 69  ed.</p>..<p>SQLi
67d0: 74 65 20 75 73 65 73 20 3c 74 74 3e 74 65 73 74  te uses <tt>test
67e0: 63 61 73 65 28 29 3c 2f 74 74 3e 20 6d 61 63 72  case()</tt> macr
67f0: 6f 73 20 61 73 20 64 65 73 63 72 69 62 65 64 20  os as described 
6800: 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  in the previous.
6810: 73 75 62 73 65 63 74 69 6f 6e 20 74 6f 20 6d 61  subsection to ma
6820: 6b 65 20 73 75 72 65 20 74 68 61 74 20 65 76 65  ke sure that eve
6830: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 20 69 6e 20  ry condition in 
6840: 61 20 62 69 74 2d 76 65 63 74 6f 72 20 64 65 63  a bit-vector dec
6850: 69 73 69 6f 6e 20 74 61 6b 65 73 0a 6f 6e 20 65  ision takes.on e
6860: 76 65 72 79 20 70 6f 73 73 69 62 6c 65 20 6f 75  very possible ou
6870: 74 63 6f 6d 65 2e 20 20 49 6e 20 74 68 69 73 20  tcome.  In this 
6880: 77 61 79 2c 20 53 51 4c 69 74 65 20 61 6c 73 6f  way, SQLite also
6890: 20 61 63 68 69 65 76 65 73 20 31 30 30 25 20 4d   achieves 100% M
68a0: 43 2f 44 43 0a 69 6e 20 61 64 64 69 74 69 6f 6e  C/DC.in addition
68b0: 20 74 6f 20 31 30 30 25 20 62 72 61 6e 63 68 20   to 100% branch 
68c0: 63 6f 76 65 72 61 67 65 2e 3c 2f 70 3e 0a 0a 3c  coverage.</p>..<
68d0: 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
68e0: 74 68 6f 75 67 68 74 73 31 3c 2f 74 63 6c 3e 0a  thoughts1</tcl>.
68f0: 3c 68 33 3e 37 2e 35 20 45 78 70 65 72 69 65 6e  <h3>7.5 Experien
6900: 63 65 20 77 69 74 68 20 66 75 6c 6c 20 74 65 73  ce with full tes
6910: 74 20 63 6f 76 65 72 61 67 65 3c 2f 68 33 3e 0a  t coverage</h3>.
6920: 0a 3c 70 3e 54 68 65 20 64 65 76 65 6c 6f 70 65  .<p>The develope
6930: 72 73 20 6f 66 20 53 51 4c 69 74 65 20 68 61 76  rs of SQLite hav
6940: 65 20 66 6f 75 6e 64 20 74 68 61 74 20 66 75 6c  e found that ful
6950: 6c 20 63 6f 76 65 72 61 67 65 20 74 65 73 74 69  l coverage testi
6960: 6e 67 20 69 73 20 61 6e 0a 65 78 74 72 65 6d 65  ng is an.extreme
6970: 6c 79 20 70 72 6f 64 75 63 74 69 76 65 20 6d 65  ly productive me
6980: 74 68 6f 64 20 66 6f 72 20 70 72 65 76 65 6e 74  thod for prevent
6990: 69 6e 67 20 74 68 65 20 69 6e 74 72 6f 64 75 63  ing the introduc
69a0: 74 69 6f 6e 20 6f 66 20 6e 65 77 20 62 75 67 73  tion of new bugs
69b0: 0a 61 73 20 74 68 65 20 73 79 73 74 65 6d 20 65  .as the system e
69c0: 76 6f 6c 76 65 73 2e 20 20 42 65 63 61 75 73 65  volves.  Because
69d0: 20 65 76 65 72 79 20 73 69 6e 67 6c 65 20 62 72   every single br
69e0: 61 6e 63 68 0a 69 6e 73 74 72 75 63 74 69 6f 6e  anch.instruction
69f0: 20 69 6e 20 53 51 4c 69 74 65 20 63 6f 72 65 20   in SQLite core 
6a00: 63 6f 64 65 20 69 73 20 63 6f 76 65 72 65 64 20  code is covered 
6a10: 62 79 20 74 65 73 74 20 63 61 73 65 73 2c 20 74  by test cases, t
6a20: 68 65 20 64 65 76 65 6c 6f 70 65 72 73 0a 63 61  he developers.ca
6a30: 6e 20 62 65 20 63 6f 6e 66 69 64 65 6e 74 20 74  n be confident t
6a40: 68 61 74 20 63 68 61 6e 67 65 73 20 74 68 65 79  hat changes they
6a50: 20 6d 61 6b 65 20 69 6e 20 6f 6e 65 20 70 61 72   make in one par
6a60: 74 20 6f 66 20 74 68 65 20 63 6f 64 65 0a 64 6f  t of the code.do
6a70: 20 6e 6f 74 20 68 61 76 65 20 75 6e 69 6e 74 65   not have uninte
6a80: 6e 64 65 64 20 63 6f 6e 73 65 71 75 65 6e 63 65  nded consequence
6a90: 73 20 69 6e 20 6f 74 68 65 72 20 70 61 72 74 73  s in other parts
6aa0: 20 6f 66 20 74 68 65 20 63 6f 64 65 2e 0a 49 74   of the code..It
6ab0: 20 77 6f 75 6c 64 20 62 65 20 65 78 74 72 65 6d   would be extrem
6ac0: 65 6c 79 20 64 69 66 66 69 63 75 6c 74 20 6d 61  ely difficult ma
6ad0: 69 6e 74 61 69 6e 20 74 68 65 20 71 75 61 6c 69  intain the quali
6ae0: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 77 69 74  ty of SQLite wit
6af0: 68 6f 75 74 20 73 75 63 68 0a 61 73 73 75 72 61  hout such.assura
6b00: 6e 63 65 73 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e  nces.</p>..<tcl>
6b10: 68 64 5f 66 72 61 67 6d 65 6e 74 20 64 79 6e 61  hd_fragment dyna
6b20: 6d 69 63 61 6e 61 6c 79 73 69 73 3c 2f 74 63 6c  micanalysis</tcl
6b30: 3e 0a 3c 68 32 3e 38 2e 30 20 44 79 6e 61 6d 69  >.<h2>8.0 Dynami
6b40: 63 20 41 6e 61 6c 79 73 69 73 3c 2f 68 32 3e 0a  c Analysis</h2>.
6b50: 0a 3c 70 3e 44 79 6e 61 6d 69 63 20 61 6e 61 6c  .<p>Dynamic anal
6b60: 79 73 69 73 20 72 65 66 65 72 73 20 74 6f 20 69  ysis refers to i
6b70: 6e 74 65 72 6e 61 6c 20 61 6e 64 20 65 78 74 65  nternal and exte
6b80: 72 6e 61 6c 20 63 68 65 63 6b 73 20 6f 6e 20 74  rnal checks on t
6b90: 68 65 0a 53 51 4c 69 74 65 20 63 6f 64 65 20 77  he.SQLite code w
6ba0: 68 69 63 68 20 61 72 65 20 70 65 72 66 6f 72 6d  hich are perform
6bb0: 65 64 20 77 68 69 6c 65 20 74 68 65 20 63 6f 64  ed while the cod
6bc0: 65 20 69 73 20 6c 69 76 65 20 61 6e 64 20 72 75  e is live and ru
6bd0: 6e 6e 69 6e 67 2e 0a 44 79 6e 61 6d 69 63 20 61  nning..Dynamic a
6be0: 6e 61 6c 79 73 69 73 20 68 61 73 20 70 72 6f 76  nalysis has prov
6bf0: 65 6e 20 74 6f 20 62 65 20 61 20 67 72 65 61 74  en to be a great
6c00: 20 68 65 6c 70 20 69 6e 20 6d 61 69 6e 74 61 69   help in maintai
6c10: 6e 69 6e 67 20 74 68 65 0a 71 75 61 6c 69 74 79  ning the.quality
6c20: 20 6f 66 20 53 51 4c 69 74 65 2e 3c 2f 70 3e 0a   of SQLite.</p>.
6c30: 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
6c40: 74 20 61 73 73 65 72 74 73 3c 2f 74 63 6c 3e 0a  t asserts</tcl>.
6c50: 3c 68 33 3e 38 2e 31 20 41 73 73 65 72 74 3c 2f  <h3>8.1 Assert</
6c60: 68 33 3e 0a 0a 3c 70 3e 54 68 65 20 53 51 4c 69  h3>..<p>The SQLi
6c70: 74 65 20 63 6f 72 65 20 63 6f 6e 74 61 69 6e 73  te core contains
6c80: 20 3c 74 63 6c 3e 4e 20 7b 24 73 74 61 74 28 6e   <tcl>N {$stat(n
6c90: 41 73 73 65 72 74 29 7d 3c 2f 74 63 6c 3e 20 3c  Assert)}</tcl> <
6ca0: 74 74 3e 61 73 73 65 72 74 28 29 3c 2f 74 74 3e  tt>assert()</tt>
6cb0: 0a 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74  .statements that
6cc0: 20 76 65 72 69 66 79 20 66 75 6e 63 74 69 6f 6e   verify function
6cd0: 20 70 72 65 63 6f 6e 64 69 74 69 6f 6e 73 20 61   preconditions a
6ce0: 6e 64 20 70 6f 73 74 63 6f 6e 64 69 74 69 6f 6e  nd postcondition
6cf0: 73 20 61 6e 64 0a 6c 6f 6f 70 20 69 6e 76 61 72  s and.loop invar
6d00: 69 61 6e 74 73 2e 20 20 41 73 73 65 72 74 28 29  iants.  Assert()
6d10: 20 69 73 20 61 20 6d 61 63 72 6f 20 77 68 69 63   is a macro whic
6d20: 68 20 69 73 20 61 20 73 74 61 6e 64 61 72 64 20  h is a standard 
6d30: 70 61 72 74 20 6f 66 0a 41 4e 53 49 2d 43 2e 20  part of.ANSI-C. 
6d40: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
6d50: 20 61 20 62 6f 6f 6c 65 61 6e 20 76 61 6c 75 65   a boolean value
6d60: 20 74 68 61 74 20 69 73 20 61 73 73 75 6d 65 64   that is assumed
6d70: 20 74 6f 20 61 6c 77 61 79 73 20 62 65 0a 74 72   to always be.tr
6d80: 75 65 2e 20 20 49 66 20 74 68 65 20 61 73 73 65  ue.  If the asse
6d90: 72 74 69 6f 6e 20 69 73 20 66 61 6c 73 65 2c 20  rtion is false, 
6da0: 74 68 65 20 70 72 6f 67 72 61 6d 20 70 72 69 6e  the program prin
6db0: 74 73 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  ts an error mess
6dc0: 61 67 65 0a 61 6e 64 20 68 61 6c 74 73 2e 3c 2f  age.and halts.</
6dd0: 70 3e 0a 0a 3c 70 3e 41 73 73 65 72 74 28 29 20  p>..<p>Assert() 
6de0: 6d 61 63 72 6f 73 20 61 72 65 20 64 69 73 61 62  macros are disab
6df0: 6c 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  led by compiling
6e00: 20 77 69 74 68 20 74 68 65 20 4e 44 45 42 55 47   with the NDEBUG
6e10: 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 0a   macro defined..
6e20: 49 6e 20 6d 6f 73 74 20 73 79 73 74 65 6d 73 2c  In most systems,
6e30: 20 61 73 73 65 72 74 73 20 61 72 65 20 65 6e 61   asserts are ena
6e40: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
6e50: 20 20 42 75 74 20 69 6e 20 53 51 4c 69 74 65 2c    But in SQLite,
6e60: 20 74 68 65 0a 61 73 73 65 72 74 73 20 61 72 65   the.asserts are
6e70: 20 73 6f 20 6e 75 6d 65 72 6f 75 73 20 61 6e 64   so numerous and
6e80: 20 61 72 65 20 69 6e 20 73 75 63 68 20 70 65 72   are in such per
6e90: 66 6f 72 6d 61 6e 63 65 20 63 72 69 74 69 63 61  formance critica
6ea0: 6c 20 70 6c 61 63 65 73 2c 20 74 68 61 74 0a 74  l places, that.t
6eb0: 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
6ec0: 6e 65 20 72 75 6e 73 20 61 62 6f 75 74 20 74 68  ne runs about th
6ed0: 72 65 65 20 74 69 6d 65 73 20 73 6c 6f 77 65 72  ree times slower
6ee0: 20 77 68 65 6e 20 61 73 73 65 72 74 73 20 61 72   when asserts ar
6ef0: 65 20 65 6e 61 62 6c 65 64 2e 0a 48 65 6e 63 65  e enabled..Hence
6f00: 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20 28 70  , the default (p
6f10: 72 6f 64 75 63 74 69 6f 6e 29 20 62 75 69 6c 64  roduction) build
6f20: 20 6f 66 20 53 51 4c 69 74 65 20 64 69 73 61 62   of SQLite disab
6f30: 6c 65 73 20 61 73 73 65 72 74 73 2e 20 20 0a 41  les asserts.  .A
6f40: 73 73 65 72 74 20 73 74 61 74 65 6d 65 6e 74 73  ssert statements
6f50: 20 61 72 65 20 6f 6e 6c 79 20 65 6e 61 62 6c 65   are only enable
6f60: 64 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  d when SQLite is
6f70: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
6f80: 68 65 0a 53 51 4c 49 54 45 5f 44 45 42 55 47 20  he.SQLITE_DEBUG 
6f90: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
6fa0: 72 6f 20 64 65 66 69 6e 65 64 2e 3c 2f 70 3e 0a  ro defined.</p>.
6fb0: 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
6fc0: 74 20 76 61 6c 67 72 69 6e 64 3c 2f 74 63 6c 3e  t valgrind</tcl>
6fd0: 0a 3c 68 33 3e 38 2e 32 20 56 61 6c 67 72 69 6e  .<h3>8.2 Valgrin
6fe0: 64 3c 2f 68 33 3e 0a 0a 3c 70 3e 5b 68 74 74 70  d</h3>..<p>[http
6ff0: 3a 2f 2f 76 61 6c 67 72 69 6e 64 2e 6f 72 67 2f  ://valgrind.org/
7000: 20 7c 20 56 61 6c 67 72 69 6e 64 5d 20 69 73 20   | Valgrind] is 
7010: 70 65 72 68 61 70 73 20 74 68 65 20 6d 6f 73 74  perhaps the most
7020: 20 61 6d 61 7a 69 6e 67 0a 61 6e 64 20 75 73 65   amazing.and use
7030: 66 75 6c 20 64 65 76 65 6c 6f 70 65 72 20 74 6f  ful developer to
7040: 6f 6c 20 69 6e 20 74 68 65 20 77 6f 72 6c 64 2e  ol in the world.
7050: 20 20 56 61 6c 67 72 69 6e 64 20 69 73 20 61 20    Valgrind is a 
7060: 73 69 6d 75 6c 61 74 6f 72 20 2d 20 69 74 20 73  simulator - it s
7070: 69 6d 75 6c 61 74 65 73 0a 61 6e 20 78 38 36 20  imulates.an x86 
7080: 72 75 6e 6e 69 6e 67 20 61 20 4c 69 6e 75 78 20  running a Linux 
7090: 62 69 6e 61 72 79 2e 20 20 28 50 6f 72 74 73 20  binary.  (Ports 
70a0: 6f 66 20 56 61 6c 67 72 69 6e 64 20 66 6f 72 20  of Valgrind for 
70b0: 70 6c 61 74 66 6f 72 6d 73 20 6f 74 68 65 72 0a  platforms other.
70c0: 74 68 61 6e 20 4c 69 6e 75 78 20 61 72 65 20 69  than Linux are i
70d0: 6e 20 64 65 76 65 6c 6f 70 6d 65 6e 74 2c 20 62  n development, b
70e0: 75 74 20 61 73 20 6f 66 20 74 68 69 73 20 77 72  ut as of this wr
70f0: 69 74 69 6e 67 2c 20 56 61 6c 67 72 69 6e 64 20  iting, Valgrind 
7100: 6f 6e 6c 79 0a 77 6f 72 6b 73 20 72 65 6c 69 61  only.works relia
7110: 62 6c 79 20 6f 6e 20 4c 69 6e 75 78 2c 20 77 68  bly on Linux, wh
7120: 69 63 68 20 69 6e 20 74 68 65 20 6f 70 69 6e 69  ich in the opini
7130: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
7140: 20 64 65 76 65 6c 6f 70 65 72 73 20 0a 6d 65 61   developers .mea
7150: 6e 73 20 74 68 61 74 20 4c 69 6e 75 78 20 73 68  ns that Linux sh
7160: 6f 75 6c 64 20 62 65 20 74 68 65 20 70 72 65 66  ould be the pref
7170: 65 72 72 65 64 20 70 6c 61 74 66 6f 72 6d 20 66  erred platform f
7180: 6f 72 20 61 6c 6c 20 73 6f 66 74 77 61 72 65 20  or all software 
7190: 64 65 76 65 6c 6f 70 6d 65 6e 74 2e 29 0a 41 73  development.).As
71a0: 20 56 61 6c 67 72 69 6e 64 20 72 75 6e 73 20 61   Valgrind runs a
71b0: 20 4c 69 6e 75 78 20 62 69 6e 61 72 79 2c 20 69   Linux binary, i
71c0: 74 20 6c 6f 6f 6b 73 20 66 6f 72 20 61 6c 6c 20  t looks for all 
71d0: 6b 69 6e 64 73 20 6f 66 20 69 6e 74 65 72 65 73  kinds of interes
71e0: 74 69 6e 67 0a 65 72 72 6f 72 73 20 73 75 63 68  ting.errors such
71f0: 20 61 73 20 61 72 72 61 79 20 6f 76 65 72 72 75   as array overru
7200: 6e 73 2c 20 72 65 61 64 69 6e 67 20 66 72 6f 6d  ns, reading from
7210: 20 75 6e 69 6e 69 74 69 61 6c 69 7a 65 64 20 6d   uninitialized m
7220: 65 6d 6f 72 79 2c 0a 73 74 61 63 6b 20 6f 76 65  emory,.stack ove
7230: 72 66 6c 6f 77 73 2c 20 6d 65 6d 6f 72 79 20 6c  rflows, memory l
7240: 65 61 6b 73 2c 20 61 6e 64 20 73 6f 20 66 6f 72  eaks, and so for
7250: 74 68 2e 20 20 56 61 6c 67 72 69 6e 64 20 66 69  th.  Valgrind fi
7260: 6e 64 73 20 70 72 6f 62 6c 65 6d 73 0a 74 68 61  nds problems.tha
7270: 74 20 63 61 6e 20 65 61 73 69 6c 79 20 73 6c 69  t can easily sli
7280: 70 20 74 68 72 6f 75 67 68 20 61 6c 6c 20 6f 66  p through all of
7290: 20 74 68 65 20 6f 74 68 65 72 20 74 65 73 74 73   the other tests
72a0: 20 72 75 6e 20 61 67 61 69 6e 73 74 20 53 51 4c   run against SQL
72b0: 69 74 65 2e 0a 41 6e 64 2c 20 77 68 65 6e 20 56  ite..And, when V
72c0: 61 6c 67 72 69 6e 64 20 64 6f 65 73 20 66 69 6e  algrind does fin
72d0: 64 20 61 6e 20 65 72 72 6f 72 2c 20 69 74 20 63  d an error, it c
72e0: 61 6e 20 64 75 6d 70 20 74 68 65 20 64 65 76 65  an dump the deve
72f0: 6c 6f 70 65 72 20 64 69 72 65 63 74 6c 79 0a 69  loper directly.i
7300: 6e 74 6f 20 61 20 73 79 6d 62 6f 6c 69 63 20 64  nto a symbolic d
7310: 65 62 75 67 67 65 72 20 61 74 20 74 68 65 20 65  ebugger at the e
7320: 78 61 63 74 20 70 6f 69 6e 74 20 77 68 65 72 65  xact point where
7330: 20 74 68 65 20 65 72 72 6f 72 20 6f 63 63 75 72   the error occur
7340: 2c 20 74 6f 0a 66 61 63 69 6c 69 74 61 74 65 20  , to.facilitate 
7350: 61 20 71 75 69 63 6b 20 66 69 78 2e 3c 2f 70 3e  a quick fix.</p>
7360: 0a 0a 3c 70 3e 42 65 63 61 75 73 65 20 69 74 20  ..<p>Because it 
7370: 69 73 20 61 20 73 69 6d 75 6c 61 74 6f 72 2c 20  is a simulator, 
7380: 72 75 6e 6e 69 6e 67 20 61 20 62 69 6e 61 72 79  running a binary
7390: 20 69 6e 20 56 61 6c 67 72 69 6e 64 20 69 73 20   in Valgrind is 
73a0: 73 6c 6f 77 65 72 20 74 68 61 6e 20 0a 72 75 6e  slower than .run
73b0: 6e 69 6e 67 20 69 74 20 6f 6e 20 6e 61 74 69 76  ning it on nativ
73c0: 65 20 68 61 72 64 77 61 72 65 2e 20 20 28 54 6f  e hardware.  (To
73d0: 20 61 20 66 69 72 73 74 20 61 70 70 72 6f 78 69   a first approxi
73e0: 6d 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  mation, an appli
73f0: 63 61 74 69 6f 6e 0a 72 75 6e 6e 69 6e 67 20 69  cation.running i
7400: 6e 20 56 61 6c 67 72 69 6e 64 20 6f 6e 20 61 20  n Valgrind on a 
7410: 77 6f 72 6b 73 74 61 74 69 6f 6e 20 77 69 6c 6c  workstation will
7420: 20 70 65 72 66 6f 72 6d 20 61 62 6f 75 74 20 74   perform about t
7430: 68 65 20 73 61 6d 65 20 61 73 20 69 74 0a 77 6f  he same as it.wo
7440: 75 6c 64 20 72 75 6e 6e 69 6e 67 20 6e 61 74 69  uld running nati
7450: 76 65 6c 79 20 6f 6e 20 61 20 73 6d 61 72 74 70  vely on a smartp
7460: 68 6f 6e 65 2e 29 20 20 53 6f 20 69 74 20 69 73  hone.)  So it is
7470: 20 69 6d 70 72 61 63 74 69 63 61 6c 20 74 6f 20   impractical to 
7480: 72 75 6e 20 74 68 65 20 66 75 6c 6c 0a 53 51 4c  run the full.SQL
7490: 69 74 65 20 74 65 73 74 20 73 75 69 74 65 20 74  ite test suite t
74a0: 68 72 6f 75 67 68 20 56 61 6c 67 72 69 6e 64 2e  hrough Valgrind.
74b0: 20 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 76    However, the v
74c0: 65 72 79 71 75 69 63 6b 20 74 65 73 74 73 20 61  eryquick tests a
74d0: 6e 64 0a 74 68 65 20 63 6f 76 65 72 61 67 65 20  nd.the coverage 
74e0: 6f 66 20 74 68 65 20 54 48 33 20 74 65 73 74 73  of the TH3 tests
74f0: 20 61 72 65 20 72 75 6e 20 74 68 72 6f 75 67 68   are run through
7500: 20 56 61 6c 67 72 69 6e 64 20 70 72 69 6f 72 20   Valgrind prior 
7510: 74 6f 20 65 76 65 72 79 0a 72 65 6c 65 61 73 65  to every.release
7520: 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66  .</p>..<tcl>hd_f
7530: 72 61 67 6d 65 6e 74 20 6d 65 6d 74 65 73 74 69  ragment memtesti
7540: 6e 67 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 38 2e 33  ng</tcl>.<h3>8.3
7550: 20 4d 65 6d 73 79 73 32 3c 2f 68 33 3e 0a 0a 3c   Memsys2</h3>..<
7560: 70 3e 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  p>SQLite contain
7570: 73 20 61 20 70 6c 75 67 67 61 62 6c 65 0a 5b 6d  s a pluggable.[m
7580: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
7590: 20 7c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   | memory alloca
75a0: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 5d 2e  tion subsystem].
75b0: 0a 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70  .The default imp
75c0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
75d0: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
75e0: 20 61 6e 64 20 66 72 65 65 28 29 2e 20 0a 48 6f   and free(). .Ho
75f0: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
7600: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
7610: 68 20 5b 53 51 4c 49 54 45 5f 4d 45 4d 44 45 42  h [SQLITE_MEMDEB
7620: 55 47 5d 2c 20 61 6e 20 61 6c 74 65 72 6e 61 74  UG], an alternat
7630: 69 76 65 0a 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ive.memory alloc
7640: 61 74 69 6f 6e 20 77 72 61 70 70 65 72 20 28 5b  ation wrapper ([
7650: 6d 65 6d 73 79 73 32 5d 29 0a 69 73 20 69 6e 73  memsys2]).is ins
7660: 65 72 74 65 64 20 74 68 61 74 20 6c 6f 6f 6b 73  erted that looks
7670: 20 66 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   for memory allo
7680: 63 61 74 69 6f 6e 0a 65 72 72 6f 72 73 20 61 74  cation.errors at
7690: 20 72 75 6e 2d 74 69 6d 65 2e 20 20 54 68 65 20   run-time.  The 
76a0: 6d 65 6d 73 79 73 32 20 77 72 61 70 70 65 72 20  memsys2 wrapper 
76b0: 63 68 65 63 6b 73 20 66 6f 72 20 6d 65 6d 6f 72  checks for memor
76c0: 79 20 6c 65 61 6b 73 2c 20 6f 66 0a 63 6f 75 72  y leaks, of.cour
76d0: 73 65 2c 20 62 75 74 20 61 6c 73 6f 20 6c 6f 6f  se, but also loo
76e0: 6b 73 20 66 6f 72 20 62 75 66 66 65 72 20 6f 76  ks for buffer ov
76f0: 65 72 72 75 6e 73 2c 20 75 73 65 73 20 6f 66 20  erruns, uses of 
7700: 75 6e 69 6e 69 74 69 61 6c 69 7a 65 64 20 6d 65  uninitialized me
7710: 6d 6f 72 79 2c 0a 61 6e 64 20 61 74 74 65 6d 70  mory,.and attemp
7720: 74 73 20 74 6f 20 75 73 65 20 6d 65 6d 6f 72 79  ts to use memory
7730: 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
7740: 65 6e 20 66 72 65 65 64 2e 20 20 54 68 65 73 65  en freed.  These
7750: 20 73 61 6d 65 20 63 68 65 63 6b 73 0a 61 72 65   same checks.are
7760: 20 61 6c 73 6f 20 64 6f 6e 65 20 62 79 20 76 61   also done by va
7770: 6c 67 72 69 6e 64 20 28 61 6e 64 2c 20 69 6e 64  lgrind (and, ind
7780: 65 65 64 2c 20 56 61 6c 67 72 69 6e 64 20 64 6f  eed, Valgrind do
7790: 65 73 20 74 68 65 6d 20 62 65 74 74 65 72 29 0a  es them better).
77a0: 62 75 74 20 6d 65 6d 73 79 73 32 20 68 61 73 20  but memsys2 has 
77b0: 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66  the advantage of
77c0: 20 62 65 69 6e 67 20 6d 75 63 68 20 66 61 73 74   being much fast
77d0: 65 72 20 74 68 61 6e 20 56 61 6c 67 72 69 6e 64  er than Valgrind
77e0: 2c 20 77 68 69 63 68 0a 6d 65 61 6e 73 20 74 68  , which.means th
77f0: 65 20 63 68 65 63 6b 73 20 63 61 6e 20 62 65 20  e checks can be 
7800: 64 6f 6e 65 20 6d 6f 72 65 20 6f 66 74 65 6e 20  done more often 
7810: 61 6e 64 20 66 6f 72 20 6c 6f 6e 67 65 72 20 74  and for longer t
7820: 65 73 74 73 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e  ests.</p>..<tcl>
7830: 68 64 5f 66 72 61 67 6d 65 6e 74 20 6d 75 74 65  hd_fragment mute
7840: 78 74 65 73 74 69 6e 67 3c 2f 74 63 6c 3e 0a 3c  xtesting</tcl>.<
7850: 68 33 3e 38 2e 34 20 4d 75 74 65 78 20 41 73 73  h3>8.4 Mutex Ass
7860: 65 72 74 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 53 51  erts</h3>..<p>SQ
7870: 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
7880: 70 6c 75 67 67 61 62 6c 65 20 6d 75 74 65 78 20  pluggable mutex 
7890: 73 75 62 73 79 73 74 65 6d 2e 20 20 44 65 70 65  subsystem.  Depe
78a0: 6e 64 69 6e 67 20 6f 6e 20 0a 63 6f 6d 70 69 6c  nding on .compil
78b0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 73 2c 20  e-time options, 
78c0: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
78d0: 78 20 73 79 73 74 65 6d 20 63 6f 6e 74 61 69 6e  x system contain
78e0: 73 20 69 6e 74 65 72 66 61 63 65 73 0a 5b 73 71  s interfaces.[sq
78f0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
7900: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
7910: 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29  _mutex_notheld()
7920: 5d 20 74 68 61 74 20 64 65 74 65 63 74 0a 77 68  ] that detect.wh
7930: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 20 70  ether or not a p
7940: 61 72 74 69 63 75 6c 61 72 20 6d 75 74 65 78 20  articular mutex 
7950: 69 73 20 68 65 6c 64 20 62 79 20 74 68 65 20 63  is held by the c
7960: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a 54  alling thread..T
7970: 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
7980: 63 65 73 20 61 72 65 20 75 73 65 64 20 65 78 74  ces are used ext
7990: 65 6e 73 69 76 65 6c 79 20 77 69 74 68 69 6e 20  ensively within 
79a0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
79b0: 6e 74 73 0a 69 6e 20 53 51 4c 69 74 65 20 74 6f  nts.in SQLite to
79c0: 20 76 65 72 69 66 79 20 6d 75 74 65 78 65 73 20   verify mutexes 
79d0: 61 72 65 20 68 65 6c 64 20 61 6e 64 20 72 65 6c  are held and rel
79e0: 65 61 73 65 64 20 61 74 20 61 6c 6c 20 74 68 65  eased at all the
79f0: 20 72 69 67 68 74 0a 6d 6f 6d 65 6e 74 73 2c 20   right.moments, 
7a00: 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 6f 75 62  in order to doub
7a10: 6c 65 2d 63 68 65 63 6b 20 74 68 61 74 20 53 51  le-check that SQ
7a20: 4c 69 74 65 20 64 6f 65 73 20 77 6f 72 6b 20 63  Lite does work c
7a30: 6f 72 72 65 63 74 6c 79 0a 69 6e 20 6d 75 6c 74  orrectly.in mult
7a40: 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  i-threaded appli
7a50: 63 61 74 69 6f 6e 73 2e 3c 2f 70 3e 0a 0a 3c 74  cations.</p>..<t
7a60: 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 6a  cl>hd_fragment j
7a70: 6f 75 72 6e 61 6c 74 65 73 74 3c 2f 74 63 6c 3e  ournaltest</tcl>
7a80: 0a 3c 68 33 3e 38 2e 35 20 4a 6f 75 72 6e 61 6c  .<h3>8.5 Journal
7a90: 20 54 65 73 74 73 3c 2f 68 33 3e 0a 0a 3c 70 3e   Tests</h3>..<p>
7aa0: 4f 6e 65 20 6f 66 20 74 68 65 20 74 68 69 6e 67  One of the thing
7ab0: 73 20 74 68 61 74 20 53 51 4c 69 74 65 20 64 6f  s that SQLite do
7ac0: 65 73 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  es to ensure tha
7ad0: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 0a 61  t transactions.a
7ae0: 72 65 20 61 74 6f 6d 69 63 20 61 63 72 6f 73 73  re atomic across
7af0: 20 73 79 73 74 65 6d 20 63 72 61 73 68 65 73 20   system crashes 
7b00: 61 6e 64 20 70 6f 77 65 72 20 66 61 69 6c 75 72  and power failur
7b10: 65 73 20 69 73 20 74 6f 20 77 72 69 74 65 0a 61  es is to write.a
7b20: 6c 6c 20 63 68 61 6e 67 65 73 20 69 6e 74 6f 20  ll changes into 
7b30: 74 68 65 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75  the rollback jou
7b40: 72 6e 61 6c 20 66 69 6c 65 20 70 72 69 6f 72 20  rnal file prior 
7b50: 74 6f 20 63 68 61 6e 67 69 6e 67 20 74 68 65 0a  to changing the.
7b60: 64 61 74 61 62 61 73 65 2e 20 20 54 68 65 20 54  database.  The T
7b70: 43 4c 20 74 65 73 74 20 68 61 72 6e 65 73 73 20  CL test harness 
7b80: 63 6f 6e 74 61 69 6e 73 20 61 6e 20 61 6c 74 65  contains an alte
7b90: 72 6e 61 74 69 76 65 0a 5b 4f 53 20 62 61 63 6b  rnative.[OS back
7ba0: 65 6e 64 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74  end] implementat
7bb0: 69 6f 6e 20 74 68 61 74 20 68 65 6c 70 73 20 74  ion that helps t
7bc0: 6f 0a 76 65 72 69 66 79 20 74 68 69 73 20 69 73  o.verify this is
7bd0: 20 6f 63 63 75 72 72 69 6e 67 20 63 6f 72 72 65   occurring corre
7be0: 63 74 6c 79 2e 20 20 54 68 65 20 22 6a 6f 75 72  ctly.  The "jour
7bf0: 6e 61 6c 2d 74 65 73 74 20 56 46 53 22 20 6d 6f  nal-test VFS" mo
7c00: 6e 69 74 6f 72 73 0a 61 6c 6c 20 64 69 73 6b 20  nitors.all disk 
7c10: 49 2f 4f 20 74 72 61 66 66 69 63 20 62 65 74 77  I/O traffic betw
7c20: 65 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  een the database
7c30: 20 66 69 6c 65 20 61 6e 64 20 72 6f 6c 6c 62 61   file and rollba
7c40: 63 6b 20 6a 6f 75 72 6e 61 6c 2c 0a 63 68 65 63  ck journal,.chec
7c50: 6b 69 6e 67 20 74 6f 20 6d 61 6b 65 20 73 75 72  king to make sur
7c60: 65 20 74 68 61 74 20 6e 6f 74 68 69 6e 67 20 69  e that nothing i
7c70: 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
7c80: 68 65 20 64 61 74 61 62 61 73 65 0a 66 69 6c 65  he database.file
7c90: 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 20 66   which has not f
7ca0: 69 72 73 74 20 62 65 65 6e 20 77 72 69 74 74 65  irst been writte
7cb0: 6e 20 61 6e 64 20 73 79 6e 63 65 64 20 74 6f 20  n and synced to 
7cc0: 74 68 65 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75  the rollback jou
7cd0: 72 6e 61 6c 2e 0a 49 66 20 61 6e 79 20 64 69 73  rnal..If any dis
7ce0: 63 72 65 70 61 6e 63 69 65 73 20 61 72 65 20 66  crepancies are f
7cf0: 6f 75 6e 64 2c 20 61 6e 20 61 73 73 65 72 74 69  ound, an asserti
7d00: 6f 6e 20 66 61 75 6c 74 20 69 73 20 72 61 69 73  on fault is rais
7d10: 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20  ed.</p>..<p>The 
7d20: 6a 6f 75 72 6e 61 6c 20 74 65 73 74 73 20 61 72  journal tests ar
7d30: 65 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  e an additional 
7d40: 64 6f 75 62 6c 65 2d 63 68 65 63 6b 20 6f 76 65  double-check ove
7d50: 72 20 61 6e 64 20 61 62 6f 76 65 0a 74 68 65 20  r and above.the 
7d60: 63 72 61 73 68 20 74 65 73 74 73 20 74 6f 20 6d  crash tests to m
7d70: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 53 51  ake sure that SQ
7d80: 4c 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  Lite transaction
7d90: 73 20 77 69 6c 6c 20 62 65 20 61 74 6f 6d 69 63  s will be atomic
7da0: 0a 61 63 72 6f 73 73 20 73 79 73 74 65 6d 20 63  .across system c
7db0: 72 61 73 68 65 73 20 61 6e 64 20 70 6f 77 65 72  rashes and power
7dc0: 20 66 61 69 6c 75 72 65 73 2e 3c 2f 70 3e 0a 0a   failures.</p>..
7dd0: 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
7de0: 20 69 6e 74 6f 76 65 72 66 6c 6f 77 3c 2f 74 63   intoverflow</tc
7df0: 6c 3e 0a 3c 68 33 3e 38 2e 36 20 53 69 67 6e 65  l>.<h3>8.6 Signe
7e00: 64 2d 49 6e 74 65 67 65 72 20 4f 76 65 72 66 6c  d-Integer Overfl
7e10: 6f 77 20 43 68 65 63 6b 73 3c 2f 68 33 3e 0a 0a  ow Checks</h3>..
7e20: 3c 70 3e 54 68 65 20 76 61 72 69 6f 75 73 20 43  <p>The various C
7e30: 20 6c 61 6e 67 75 61 67 65 20 73 74 61 6e 64 61   language standa
7e40: 72 64 73 20 73 61 79 20 74 68 61 74 20 74 68 65  rds say that the
7e50: 20 73 69 67 6e 65 64 2d 69 6e 74 65 67 65 72 20   signed-integer 
7e60: 6f 76 65 72 66 6c 6f 77 0a 62 65 68 61 76 69 6f  overflow.behavio
7e70: 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  r is undefined. 
7e80: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
7e90: 20 77 68 65 6e 20 79 6f 75 20 61 64 64 20 61 20   when you add a 
7ea0: 76 61 6c 75 65 20 74 6f 20 61 20 73 69 67 6e 65  value to a signe
7eb0: 64 0a 69 6e 74 65 67 65 72 20 73 75 63 68 20 74  d.integer such t
7ec0: 68 61 74 20 74 68 65 20 72 65 73 75 6c 74 20 69  hat the result i
7ed0: 73 20 74 6f 6f 20 6c 61 72 67 65 20 74 6f 20 66  s too large to f
7ee0: 69 74 20 69 6e 20 74 68 61 74 20 69 6e 74 65 67  it in that integ
7ef0: 65 72 2c 20 74 68 65 0a 76 61 6c 75 65 20 64 6f  er, the.value do
7f00: 65 73 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 69  es not necessari
7f10: 6c 79 20 77 72 61 70 20 61 72 6f 75 6e 64 20 74  ly wrap around t
7f20: 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  o a negative num
7f30: 62 65 72 2c 20 61 73 20 6d 6f 73 74 0a 70 72 6f  ber, as most.pro
7f40: 67 72 61 6d 6d 65 72 73 20 65 78 70 65 63 74 2e  grammers expect.
7f50: 20 20 49 74 20 6d 69 67 68 74 20 64 6f 20 74 68    It might do th
7f60: 61 74 2e 20 20 42 75 74 20 69 74 20 6d 69 67 68  at.  But it migh
7f70: 74 20 64 6f 20 73 6f 6d 65 74 68 69 6e 67 20 63  t do something c
7f80: 6f 6d 70 6c 65 74 65 6c 79 0a 64 69 66 66 65 72  ompletely.differ
7f90: 65 6e 74 2e 20 20 53 65 65 2c 20 66 6f 72 20 65  ent.  See, for e
7fa0: 78 61 6d 70 6c 65 2c 0a 3c 61 20 68 72 65 66 3d  xample,.<a href=
7fb0: 22 68 74 74 70 3a 2f 2f 74 68 69 65 6d 6f 6e 61  "http://thiemona
7fc0: 67 65 6c 2e 64 65 2f 32 30 31 30 2f 30 31 2f 73  gel.de/2010/01/s
7fd0: 69 67 6e 65 64 2d 69 6e 74 65 67 65 72 2d 6f 76  igned-integer-ov
7fe0: 65 72 66 6c 6f 77 2f 22 3e 68 65 72 65 3c 2f 61  erflow/">here</a
7ff0: 3e 0a 61 6e 64 20 3c 61 20 68 72 65 66 3d 22 68  >.and <a href="h
8000: 74 74 70 3a 2f 2f 62 6c 6f 67 2e 72 65 67 65 68  ttp://blog.regeh
8010: 72 2e 6f 72 67 2f 61 72 63 68 69 76 65 73 2f 34  r.org/archives/4
8020: 38 32 22 3e 68 65 72 65 3c 2f 61 3e 2e 20 20 45  82">here</a>.  E
8030: 76 65 6e 20 74 68 65 0a 73 61 6d 65 20 63 6f 6d  ven the.same com
8040: 70 69 6c 65 72 20 6d 69 67 68 74 20 64 6f 20 73  piler might do s
8050: 6f 6d 65 74 68 69 6e 67 20 64 69 66 66 65 72 65  omething differe
8060: 6e 74 20 77 69 74 68 20 73 69 67 6e 65 64 20 69  nt with signed i
8070: 6e 74 65 67 65 72 20 6f 76 65 72 66 6c 6f 77 0a  nteger overflow.
8080: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 70 6c 61  in different pla
8090: 63 65 73 20 69 6e 20 74 68 65 20 63 6f 64 65 20  ces in the code 
80a0: 6f 72 20 61 74 20 64 69 66 66 65 72 65 6e 74 20  or at different 
80b0: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 73 65  optimizations se
80c0: 74 74 69 6e 67 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e  ttings.</p>..<p>
80d0: 53 51 4c 69 74 65 20 6e 65 76 65 72 20 6f 76 65  SQLite never ove
80e0: 72 66 6c 6f 77 73 20 61 20 73 69 67 6e 65 64 20  rflows a signed 
80f0: 69 6e 74 65 67 65 72 2e 0a 54 6f 20 76 65 72 69  integer..To veri
8100: 66 79 20 74 68 69 73 2c 20 74 68 65 20 74 65 73  fy this, the tes
8110: 74 20 73 75 69 74 65 73 20 61 72 65 20 72 75 6e  t suites are run
8120: 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 77   at least once w
8130: 68 65 6e 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  hen compiled wit
8140: 68 0a 74 68 65 20 2d 66 74 72 61 70 76 20 6f 70  h.the -ftrapv op
8150: 74 69 6f 6e 20 74 6f 20 47 43 43 2e 20 20 54 68  tion to GCC.  Th
8160: 65 20 2d 66 74 72 61 70 76 20 6f 70 74 69 6f 6e  e -ftrapv option
8170: 20 63 61 75 73 65 73 20 47 43 43 20 74 6f 20 67   causes GCC to g
8180: 65 6e 65 72 61 74 65 20 63 6f 64 65 0a 74 68 61  enerate code.tha
8190: 74 20 77 69 6c 6c 20 70 61 6e 69 63 28 29 20 6f  t will panic() o
81a0: 6e 20 61 20 73 69 67 6e 65 64 20 69 6e 74 65 67  n a signed integ
81b0: 65 72 20 6f 76 65 72 66 6c 6f 77 2e 20 20 49 6e  er overflow.  In
81c0: 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
81d0: 20 61 72 65 0a 6d 61 6e 79 20 74 65 73 74 20 63   are.many test c
81e0: 61 73 65 73 20 74 68 65 20 73 74 72 69 76 65 20  ases the strive 
81f0: 74 6f 20 70 72 6f 76 6f 6b 65 20 69 6e 74 65 67  to provoke integ
8200: 65 72 20 6f 76 65 72 66 6c 6f 77 73 0a 75 73 69  er overflows.usi
8210: 6e 67 20 62 6f 75 6e 64 61 72 79 20 76 61 6c 75  ng boundary valu
8220: 65 20 63 61 6c 63 75 6c 61 74 69 6f 6e 73 20 73  e calculations s
8230: 75 63 68 20 61 73 0a 20 22 3c 62 3e 53 45 4c 45  uch as. "<b>SELE
8240: 43 54 20 2d 31 2a 28 2d 39 32 32 33 33 37 32 30  CT -1*(-92233720
8250: 33 36 38 35 34 37 37 35 38 30 38 29 3b 3c 2f 62  36854775808);</b
8260: 3e 22 2e 0a 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72  >"....<tcl>hd_fr
8270: 61 67 6d 65 6e 74 20 64 69 73 6f 70 74 74 65 73  agment disopttes
8280: 74 3c 2f 74 63 6c 3e 0a 3c 68 32 3e 39 2e 30 20  t</tcl>.<h2>9.0 
8290: 44 69 73 61 62 6c 65 64 20 4f 70 74 69 6d 69 7a  Disabled Optimiz
82a0: 61 74 69 6f 6e 20 54 65 73 74 73 3c 2f 68 32 3e  ation Tests</h2>
82b0: 0a 0a 3c 70 3e 54 68 65 20 5b 73 71 6c 69 74 65  ..<p>The [sqlite
82c0: 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 5d 28  3_test_control](
82d0: 5b 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c  [SQLITE_TESTCTRL
82e0: 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 53 5d 2c  _OPTIMIZATIONS],
82f0: 20 2e 2e 2e 29 20 69 6e 74 65 72 66 61 63 65 0a   ...) interface.
8300: 61 6c 6c 6f 77 73 20 73 65 6c 65 63 74 65 64 20  allows selected 
8310: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 70  SQL statement op
8320: 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74 6f 20 62  timizations to b
8330: 65 20 64 69 73 61 62 6c 65 64 20 61 74 20 72 75  e disabled at ru
8340: 6e 2d 74 69 6d 65 2e 0a 53 51 4c 69 74 65 20 73  n-time..SQLite s
8350: 68 6f 75 6c 64 20 61 6c 77 61 79 73 20 67 65 6e  hould always gen
8360: 65 72 61 74 65 20 65 78 61 63 74 6c 79 20 74 68  erate exactly th
8370: 65 20 73 61 6d 65 20 61 6e 73 77 65 72 20 77 69  e same answer wi
8380: 74 68 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73  th optimizations
8390: 0a 65 6e 61 62 6c 65 64 20 61 6e 64 20 77 69 74  .enabled and wit
83a0: 68 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20  h optimizations 
83b0: 64 69 73 61 62 6c 65 64 3b 20 74 68 65 20 61 6e  disabled; the an
83c0: 73 77 65 72 20 73 69 6d 70 6c 79 20 61 72 72 69  swer simply arri
83d0: 76 65 73 20 71 75 69 63 6b 65 72 0a 77 69 74 68  ves quicker.with
83e0: 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
83f0: 6e 73 20 74 75 72 6e 65 64 20 6f 6e 2e 20 20 53  ns turned on.  S
8400: 6f 20 69 6e 20 61 20 70 72 6f 64 75 63 74 69 6f  o in a productio
8410: 6e 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 20 6f  n environment, o
8420: 6e 65 20 61 6c 77 61 79 73 0a 6c 65 61 76 65 73  ne always.leaves
8430: 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
8440: 6e 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 74 68  ns turned on (th
8450: 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
8460: 67 29 2e 3c 2f 70 3e 0a 0a 3c 70 3e 4f 6e 65 20  g).</p>..<p>One 
8470: 76 65 72 69 66 69 63 61 74 69 6f 6e 20 74 65 63  verification tec
8480: 68 6e 69 71 75 65 20 75 73 65 64 20 6f 6e 20 53  hnique used on S
8490: 51 4c 69 74 65 20 69 73 20 74 6f 20 72 75 6e 20  QLite is to run 
84a0: 61 6e 20 65 6e 74 69 72 65 20 74 65 73 74 20 73  an entire test s
84b0: 75 69 74 65 0a 74 77 69 63 65 2c 20 6f 6e 63 65  uite.twice, once
84c0: 20 77 69 74 68 20 6f 70 74 69 6d 69 7a 61 74 69   with optimizati
84d0: 6f 6e 73 20 6c 65 66 74 20 6f 6e 20 61 6e 64 20  ons left on and 
84e0: 61 20 73 65 63 6f 6e 64 20 74 69 6d 65 20 77 69  a second time wi
84f0: 74 68 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73  th optimizations
8500: 0a 74 75 72 6e 65 64 20 6f 66 66 2c 20 61 6e 64  .turned off, and
8510: 20 76 65 72 69 66 79 20 74 68 61 74 20 74 68 65   verify that the
8520: 20 73 61 6d 65 20 6f 75 74 70 75 74 20 69 73 20   same output is 
8530: 6f 62 74 61 69 6e 65 64 20 62 6f 74 68 20 74 69  obtained both ti
8540: 6d 65 73 2e 20 20 54 68 69 73 0a 73 68 6f 77 73  mes.  This.shows
8550: 20 74 68 61 74 20 74 68 65 20 6f 70 74 69 6d 69   that the optimi
8560: 7a 61 74 69 6f 6e 73 20 64 6f 20 6e 6f 74 20 69  zations do not i
8570: 6e 74 72 6f 64 75 63 65 20 65 72 72 6f 72 73 2e  ntroduce errors.
8580: 3c 2f 70 3e 0a 0a 3c 70 3e 4e 6f 74 20 61 6c 6c  </p>..<p>Not all
8590: 20 74 65 73 74 20 63 61 73 65 73 20 63 61 6e 20   test cases can 
85a0: 62 65 20 68 61 6e 64 6c 65 64 20 74 68 69 73 20  be handled this 
85b0: 77 61 79 2e 20 20 53 6f 6d 65 20 74 65 73 74 20  way.  Some test 
85c0: 63 61 73 65 73 20 63 68 65 63 6b 0a 74 6f 20 76  cases check.to v
85d0: 65 72 69 66 79 20 74 68 61 74 20 74 68 65 20 6f  erify that the o
85e0: 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 72 65 61  ptimizations rea
85f0: 6c 6c 79 20 61 72 65 20 72 65 64 75 63 69 6e 67  lly are reducing
8600: 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 63   the amount of.c
8610: 6f 6d 70 75 74 61 74 69 6f 6e 20 62 79 20 63 6f  omputation by co
8620: 75 6e 74 69 6e 67 20 74 68 65 20 6e 75 6d 62 65  unting the numbe
8630: 72 20 6f 66 20 64 69 73 6b 20 61 63 63 65 73 73  r of disk access
8640: 65 73 2c 20 73 6f 72 74 20 6f 70 65 72 61 74 69  es, sort operati
8650: 6f 6e 73 2c 20 0a 66 75 6c 6c 2d 73 63 61 6e 20  ons, .full-scan 
8660: 73 74 65 70 73 2c 20 6f 72 20 6f 74 68 65 72 20  steps, or other 
8670: 70 72 6f 63 65 73 73 69 6e 67 20 73 74 65 70 73  processing steps
8680: 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 72 69   that occur duri
8690: 6e 67 20 71 75 65 72 69 65 73 2e 0a 54 68 6f 73  ng queries..Thos
86a0: 65 20 74 65 73 74 20 63 61 73 65 73 20 77 69 6c  e test cases wil
86b0: 6c 20 61 70 70 65 61 72 20 74 6f 20 66 61 69 6c  l appear to fail
86c0: 20 77 68 65 6e 20 6f 70 74 69 6d 69 7a 61 74 69   when optimizati
86d0: 6f 6e 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ons are disabled
86e0: 2e 0a 42 75 74 20 74 68 65 20 6d 61 6a 6f 72 69  ..But the majori
86f0: 74 79 20 6f 66 20 74 65 73 74 20 63 61 73 65 73  ty of test cases
8700: 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 20 74 68   simply check th
8710: 61 74 20 74 68 65 20 63 6f 72 72 65 63 74 20 61  at the correct a
8720: 6e 73 77 65 72 0a 77 61 73 20 6f 62 74 61 69 6e  nswer.was obtain
8730: 65 64 2c 20 61 6e 64 20 61 6c 6c 20 6f 66 20 74  ed, and all of t
8740: 68 6f 73 65 20 63 61 73 65 73 20 63 61 6e 20 62  hose cases can b
8750: 65 20 72 75 6e 20 73 75 63 63 65 73 73 66 75 6c  e run successful
8760: 6c 79 20 77 69 74 68 20 61 6e 64 0a 77 69 74 68  ly with and.with
8770: 6f 75 74 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  out the optimiza
8780: 74 69 6f 6e 73 2c 20 69 6e 20 6f 72 64 65 72 20  tions, in order 
8790: 74 6f 20 73 68 6f 77 20 74 68 61 74 20 74 68 65  to show that the
87a0: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 64   optimizations d
87b0: 6f 20 6e 6f 74 0a 63 61 75 73 65 20 6d 61 6c 66  o not.cause malf
87c0: 75 6e 63 74 69 6f 6e 73 2e 3c 2f 70 3e 0a 0a 0a  unctions.</p>...
87d0: 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
87e0: 20 73 74 61 74 69 63 61 6e 61 6c 79 73 69 73 3c   staticanalysis<
87f0: 2f 74 63 6c 3e 0a 3c 68 32 3e 31 30 2e 30 20 53  /tcl>.<h2>10.0 S
8800: 74 61 74 69 63 20 41 6e 61 6c 79 73 69 73 3c 2f  tatic Analysis</
8810: 68 32 3e 0a 0a 3c 70 3e 53 74 61 74 69 63 20 61  h2>..<p>Static a
8820: 6e 61 6c 79 73 69 73 20 6d 65 61 6e 73 20 61 6e  nalysis means an
8830: 61 6c 79 7a 69 6e 67 20 63 6f 64 65 20 61 74 20  alyzing code at 
8840: 6f 72 20 62 65 66 6f 72 65 20 63 6f 6d 70 69 6c  or before compil
8850: 65 2d 74 69 6d 65 20 74 6f 0a 63 68 65 63 6b 20  e-time to.check 
8860: 66 6f 72 20 63 6f 72 72 65 63 74 6e 65 73 73 2e  for correctness.
8870: 20 20 53 74 61 74 69 63 20 61 6e 61 6c 79 73 69    Static analysi
8880: 73 20 69 6e 63 6c 75 64 65 73 20 6c 6f 6f 6b 69  s includes looki
8890: 6e 67 20 61 74 20 63 6f 6d 70 69 6c 65 72 0a 77  ng at compiler.w
88a0: 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20  arning messages 
88b0: 61 6e 64 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  and running the 
88c0: 63 6f 64 65 20 74 68 72 6f 75 67 68 20 6d 6f 72  code through mor
88d0: 65 20 69 6e 2d 64 65 70 74 68 0a 61 6e 61 6c 79  e in-depth.analy
88e0: 73 69 73 20 65 6e 67 69 6e 65 73 20 73 75 63 68  sis engines such
88f0: 20 61 73 20 74 68 65 0a 5b 68 74 74 70 3a 2f 2f   as the.[http://
8900: 63 6c 61 6e 67 2d 61 6e 61 6c 79 7a 65 72 2e 6c  clang-analyzer.l
8910: 6c 76 6d 2e 6f 72 67 2f 20 7c 20 43 6c 61 6e 67  lvm.org/ | Clang
8920: 20 53 74 61 74 69 63 20 41 6e 61 6c 79 7a 65 72   Static Analyzer
8930: 5d 2e 0a 53 51 4c 69 74 65 20 69 73 20 64 65 76  ]..SQLite is dev
8940: 65 6c 6f 70 65 64 20 70 72 69 6d 61 72 69 6c 79  eloped primarily
8950: 20 75 73 69 6e 67 20 47 43 43 20 61 6e 64 20 69   using GCC and i
8960: 74 20 64 6f 65 73 0a 63 6f 6d 70 69 6c 65 20 77  t does.compile w
8970: 69 74 68 6f 75 74 20 77 61 72 6e 69 6e 67 73 20  ithout warnings 
8980: 6f 6e 20 47 43 43 20 75 73 69 6e 67 20 74 68 65  on GCC using the
8990: 20 2d 57 61 6c 6c 20 61 6e 64 20 2d 57 65 78 74   -Wall and -Wext
89a0: 72 61 20 66 6c 61 67 73 2e 0a 54 68 65 20 53 51  ra flags..The SQ
89b0: 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65  Lite source code
89c0: 20 69 73 20 61 6c 73 6f 20 72 75 6e 20 74 68 72   is also run thr
89d0: 6f 75 67 68 20 43 6c 61 6e 67 20 66 72 6f 6d 20  ough Clang from 
89e0: 74 69 6d 65 20 74 6f 20 74 69 6d 65 20 0a 61 73  time to time .as
89f0: 20 77 65 6c 6c 2c 20 74 68 6f 75 67 68 20 6d 6f   well, though mo
8a00: 73 74 20 6f 66 20 74 68 65 20 77 61 72 6e 69 6e  st of the warnin
8a10: 67 73 20 74 68 65 72 65 20 61 72 65 20 66 61 6c  gs there are fal
8a20: 73 65 2d 70 6f 73 69 74 69 76 65 73 2e 0a 56 43  se-positives..VC
8a30: 2b 2b 20 6f 66 74 65 6e 20 77 69 6c 6c 20 67 65  ++ often will ge
8a40: 6e 65 72 61 74 65 20 61 20 6e 75 6d 62 65 72 20  nerate a number 
8a50: 6f 66 20 77 61 72 6e 69 6e 67 73 20 66 72 6f 6d  of warnings from
8a60: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
8a70: 6f 64 65 2c 0a 62 75 74 20 74 68 65 20 65 78 70  ode,.but the exp
8a80: 65 72 69 65 6e 63 65 20 6f 66 20 53 51 4c 69 74  erience of SQLit
8a90: 65 20 64 65 76 65 6c 6f 70 65 72 73 20 69 73 20  e developers is 
8aa0: 74 68 61 74 20 56 43 2b 2b 20 77 61 72 6e 69 6e  that VC++ warnin
8ab0: 67 73 20 61 72 65 20 6f 66 0a 6c 6f 77 65 72 20  gs are of.lower 
8ac0: 71 75 61 6c 69 74 79 20 61 6e 64 20 63 61 6e 20  quality and can 
8ad0: 62 65 20 73 61 66 65 6c 79 20 69 67 6e 6f 72 65  be safely ignore
8ae0: 64 2e 20 20 55 73 65 72 73 20 61 72 65 20 65 6e  d.  Users are en
8af0: 63 6f 75 72 61 67 65 64 20 6e 6f 74 0a 74 6f 20  couraged not.to 
8b00: 73 74 72 65 73 73 20 6f 76 65 72 20 56 43 2b 2b  stress over VC++
8b10: 20 77 61 72 6e 69 6e 67 73 2e 3c 2f 70 3e 0a 0a   warnings.</p>..
8b20: 3c 70 3e 53 74 61 74 69 63 20 61 6e 61 6c 79 73  <p>Static analys
8b30: 69 73 20 68 61 73 20 6e 6f 74 20 70 72 6f 76 65  is has not prove
8b40: 6e 20 74 6f 20 62 65 20 68 65 6c 70 66 75 6c 20  n to be helpful 
8b50: 69 6e 20 66 69 6e 64 69 6e 67 0a 62 75 67 73 20  in finding.bugs 
8b60: 69 6e 20 53 51 4c 69 74 65 2e 20 20 57 65 20 63  in SQLite.  We c
8b70: 61 6e 6e 6f 74 20 63 61 6c 6c 20 74 6f 20 6d 69  annot call to mi
8b80: 6e 64 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 62  nd a single prob
8b90: 6c 65 6d 20 69 6e 20 53 51 4c 69 74 65 20 74 68  lem in SQLite th
8ba0: 61 74 0a 77 61 73 20 64 65 74 65 63 74 65 64 20  at.was detected 
8bb0: 62 79 20 73 74 61 74 69 63 20 61 6e 61 6c 79 73  by static analys
8bc0: 69 73 20 74 68 61 74 20 77 61 73 20 6e 6f 74 20  is that was not 
8bd0: 66 69 72 73 74 20 73 65 65 6e 20 62 79 20 6f 6e  first seen by on
8be0: 65 0a 6f 66 20 74 68 65 20 6f 74 68 65 72 20 74  e.of the other t
8bf0: 65 73 74 69 6e 67 20 6d 65 74 68 6f 64 73 20 64  esting methods d
8c00: 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2e 20  escribed above. 
8c10: 20 4f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61   On the other ha
8c20: 6e 64 2c 0a 77 65 20 68 61 76 65 20 6f 6e 20 6f  nd,.we have on o
8c30: 63 63 61 73 69 6f 6e 20 69 6e 74 72 6f 64 75 63  ccasion introduc
8c40: 65 64 20 6e 65 77 20 62 75 67 73 20 69 6e 20 6f  ed new bugs in o
8c50: 75 72 20 65 66 66 6f 72 74 73 20 74 6f 20 67 65  ur efforts to ge
8c60: 74 20 53 51 4c 69 74 65 0a 74 6f 20 63 6f 6d 70  t SQLite.to comp
8c70: 69 6c 65 20 77 69 74 68 6f 75 74 20 77 61 72 6e  ile without warn
8c80: 69 6e 67 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e 4f 75  ings.</p>..<p>Ou
8c90: 72 20 65 78 70 65 72 69 65 6e 63 65 2c 20 74 68  r experience, th
8ca0: 65 6e 2c 20 69 73 20 74 68 61 74 20 73 74 61 74  en, is that stat
8cb0: 69 63 20 61 6e 61 6c 79 73 69 73 20 69 73 20 6e  ic analysis is n
8cc0: 6f 74 20 68 65 6c 70 66 75 6c 0a 74 6f 20 6d 61  ot helpful.to ma
8cd0: 69 6e 74 61 69 6e 69 6e 67 20 68 69 67 68 20 63  intaining high c
8ce0: 6f 64 65 20 71 75 61 6c 69 74 79 20 61 6e 64 20  ode quality and 
8cf0: 69 74 20 69 73 20 74 68 65 72 65 66 6f 72 65 20  it is therefore 
8d00: 64 65 65 6d 70 68 61 73 69 7a 65 64 0a 69 6e 20  deemphasized.in 
8d10: 53 51 4c 69 74 65 20 64 65 76 65 6c 6f 70 6d 65  SQLite developme
8d20: 6e 74 20 61 6e 64 20 6d 61 69 6e 74 65 6e 61 6e  nt and maintenan
8d30: 63 65 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64  ce.</p>..<tcl>hd
8d40: 5f 66 72 61 67 6d 65 6e 74 20 73 75 6d 6d 61 72  _fragment summar
8d50: 79 3c 2f 74 63 6c 3e 0a 3c 68 32 3e 31 31 2e 30  y</tcl>.<h2>11.0
8d60: 20 53 75 6d 6d 61 72 79 3c 2f 68 32 3e 0a 0a 3c   Summary</h2>..<
8d70: 70 3e 53 51 4c 69 74 65 20 69 73 20 6f 70 65 6e  p>SQLite is open
8d80: 20 73 6f 75 72 63 65 2e 20 20 54 68 69 73 20 67   source.  This g
8d90: 69 76 65 73 20 6d 61 6e 79 20 70 65 6f 70 6c 65  ives many people
8da0: 20 74 68 65 20 69 64 65 61 20 74 68 61 74 0a 69   the idea that.i
8db0: 74 20 69 73 20 6e 6f 74 20 77 65 6c 6c 20 74 65  t is not well te
8dc0: 73 74 65 64 20 61 73 20 63 6f 6d 6d 65 72 63 69  sted as commerci
8dd0: 61 6c 20 73 6f 66 74 77 61 72 65 20 61 6e 64 20  al software and 
8de0: 69 73 20 70 65 72 68 61 70 73 20 75 6e 72 65 6c  is perhaps unrel
8df0: 69 61 62 6c 65 2e 0a 42 75 74 20 74 68 61 74 20  iable..But that 
8e00: 69 6d 70 72 65 73 73 69 6f 6e 20 69 73 20 66 61  impression is fa
8e10: 6c 73 65 2e 20 20 0a 53 51 4c 69 74 65 20 68 61  lse.  .SQLite ha
8e20: 73 20 65 78 68 69 62 69 74 65 64 20 76 65 72 79  s exhibited very
8e30: 20 68 69 67 68 20 72 65 6c 69 61 62 69 6c 69 74   high reliabilit
8e40: 79 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61  y in the field a
8e50: 6e 64 0a 61 20 76 65 72 79 20 6c 6f 77 20 64 65  nd.a very low de
8e60: 66 65 63 74 20 72 61 74 65 2c 20 65 73 70 65 63  fect rate, espec
8e70: 69 61 6c 6c 79 20 63 6f 6e 73 69 64 65 72 69 6e  ially considerin
8e80: 67 20 68 6f 77 20 72 61 70 69 64 6c 79 20 69 74  g how rapidly it
8e90: 20 69 73 20 65 76 6f 6c 76 69 6e 67 2e 0a 54 68   is evolving..Th
8ea0: 65 20 71 75 61 6c 69 74 79 20 6f 66 20 53 51 4c  e quality of SQL
8eb0: 69 74 65 20 69 73 20 61 63 68 69 65 76 65 64 20  ite is achieved 
8ec0: 69 6e 20 70 61 72 74 20 62 79 20 63 61 72 65 66  in part by caref
8ed0: 75 6c 20 63 6f 64 65 20 64 65 73 69 67 6e 20 61  ul code design a
8ee0: 6e 64 0a 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nd.implementatio
8ef0: 6e 2e 20 20 42 75 74 20 65 78 74 65 6e 73 69 76  n.  But extensiv
8f00: 65 20 74 65 73 74 69 6e 67 20 61 6c 73 6f 20 70  e testing also p
8f10: 6c 61 79 73 20 61 20 76 69 74 61 6c 20 72 6f 6c  lays a vital rol
8f20: 65 20 69 6e 0a 6d 61 69 6e 74 61 69 6e 69 6e 67  e in.maintaining
8f30: 20 61 6e 64 20 69 6d 70 72 6f 76 69 6e 67 20 74   and improving t
8f40: 68 65 20 71 75 61 6c 69 74 79 20 6f 66 20 53 51  he quality of SQ
8f50: 4c 69 74 65 2e 20 20 54 68 69 73 20 64 6f 63 75  Lite.  This docu
8f60: 6d 65 6e 74 20 68 61 73 0a 73 75 6d 6d 61 72 69  ment has.summari
8f70: 7a 65 64 20 74 68 65 20 74 65 73 74 69 6e 67 20  zed the testing 
8f80: 70 72 6f 63 65 64 75 72 65 73 20 74 68 61 74 20  procedures that 
8f90: 65 76 65 72 79 20 72 65 6c 65 61 73 65 20 6f 66  every release of
8fa0: 20 53 51 4c 69 74 65 20 75 6e 64 65 72 67 6f 65   SQLite undergoe
8fb0: 73 0a 77 69 74 68 20 74 68 65 20 68 6f 70 65 73  s.with the hopes
8fc0: 20 6f 66 20 69 6e 73 70 69 72 69 6e 67 20 74 68   of inspiring th
8fd0: 65 20 72 65 61 64 65 72 20 74 6f 20 75 6e 64 65  e reader to unde
8fe0: 72 73 74 61 6e 64 20 74 68 61 74 20 53 51 4c 69  rstand that SQLi
8ff0: 74 65 20 69 73 0a 73 75 69 74 61 62 6c 65 20 66  te is.suitable f
9000: 6f 72 20 75 73 65 20 69 6e 20 6d 69 73 73 69 6f  or use in missio
9010: 6e 2d 63 72 69 74 69 63 61 6c 20 61 70 70 6c 69  n-critical appli
9020: 63 61 74 69 6f 6e 73 2e 3c 2f 70 3e 0a           cations.</p>.