Changes between Version 4 and Version 5 of CodeCoverage


Ignore:
Timestamp:
Aug 27, 2008, 12:44:12 AM (11 years ago)
Author:
gz
Comment:

snapshot support, in-core stats, misc tweaks.

Legend:

Unmodified
Added
Removed
Modified
  • CodeCoverage

    v4 v5  
    7171The following functions can be used to manage the coverage data:
    7272
    73 '''`CCL:REPORT-COVERAGE index-file &key external-format (statistics t)`'''
     73'''`CCL:REPORT-COVERAGE index-file &key (external-format :default) (statistics t) (html t)`'''
    7474
    75 This will generate an HTML report, consisting of an index file and one html file for each
     75If `:html` is non-nil, this will generate an HTML report, consisting of an index file and one html file for each
    7676instrumented source file that has been loaded in the current session.   The individual
    77 source file reports are stored in the same directory as the index file.  If `:statistics`
     77source file reports are stored in the same directory as the index file.  [[br]]
     78The `:external-format` argument controls the external format of the html files. [[br]]
     79If `:statistics`
    7880is non-nil, a comma-separated file is also generated with the summary of statistics. You can specify
    7981a filename for the statistics argument, otherwise `"statistics.csv"` is created in the output directory.
     82See documentation of `ccl:coverage-statistics` below for a description of the values in the statistics file. [[br]]
    8083
    8184So for example
    8285if you've loaded `"foo.lx64fsl"` and `"bar.lx64fsl"` and have run some tests, you could do
    8386{{{
    84 (CCL:REPORT-COVERAGE "/my/dir/coverage/report.html" :statistics t)
     87(CCL:REPORT-COVERAGE "/my/dir/coverage/report.html")
    8588}}}
    8689and this would generate `"report.html"`, `"foo_lisp.html"` and `"bar_lisp.html"`, and `"statistics.csv"` all in `/my/dir/coverage/`.
     
    99102
    100103Saves all coverage info in a file, so you can restore the coverage state later.  This
    101 allows you to combine multiple runs or continue in a later session.
     104allows you to combine multiple runs or continue in a later session.  Equivalent to `(ccl:write-coverage-to-file (ccl:save-coverage) pathname)`.
    102105
    103106'''`CCL:RESTORE-COVERAGE-FROM-FILE pathname`'''
    104107
    105108Restores the coverage data previously saved with `CCL:SAVE-COVERAGE-IN-FILE`, for 
    106 the set of instrumented fasls that were loaded both at save and restore time.  I.e. coverage info is only restored for files that have been loaded in this session.  I.e. if in a previous session you had loaded `"foo.lx86fsl"` and then saved the coverage info, in this session you must load the same `"foo.lx86fsl"` before calling `ccl:restore-coverage-from-file` in order to retrieve the stored coverage info for `"foo"`.
     109the set of instrumented fasls that were loaded both at save and restore time.  I.e. coverage info is only restored for files that have been loaded in this session.  For example if in a previous session you had loaded `"foo.lx86fsl"` and then saved the coverage info, in this session you must load the same `"foo.lx86fsl"` before calling `ccl:restore-coverage-from-file` in order to retrieve the stored coverage info for `"foo"`.[[br]]
     110Equivalent to `(ccl:restore-coverage (ccl:read-coverage-from-file pathname))`.
     111
     112'''`CCL:SAVE-COVERAGE`'''
     113
     114Returns a snapshot of the current coverage data.  A snapshot is a copy of the current coverage state.  It can be saved in a file with `ccl:write-coverage-to-file`, reinstated back as the current state with `ccl:restore-coverage`, or combined with other snapshots with `ccl:combine-coverage`.
     115
     116'''`CCL:RESTORE-COVERAGE snapshot`'''
     117
     118Reinstalls the coverage snapshot as the current coverage state.
     119
     120'''`CCL:COMBINE-COVERAGE snapshots`'''
     121
     122Takes a sequence of snapshots and returns a new snapshot that is the union of all of them.  I.e. in the combined snapshot an instruction is marked as covered if it is marked as covered in at least one of the input snapshots, otherwise it is marked as uncovered.
     123
     124'''`CCL:WRITE-COVERAGE-TO-FILE snapshot pathname`'''
     125
     126Saves the coverage snapshot in a file.  The snapshot can be loaded back with `ccl:read-coverage-from-file` or loaded and restored with `ccl:restore-coverage-from-file`.  Note that the file created is actually a lisp source file and can be compiled for faster loading.
     127
     128'''`CCL:READ-COVERAGE-FROM-FILE pathname`'''
     129
     130Returns the snapshot saved in `pathname`.  Doesn't affect the current coverage state.  `pathname` can be the file previously created with `ccl:write-coverage-to-file` or `ccl:save-coverage-in-file`, or it can be the name of the fasl created from compiling such a file.
     131
     132'''`CCL:COVERAGE-STATISTICS`'''
     133
     134Returns a sequence `ccl:coverage-statistics` objects, one for each source file, containing the same information as that written to the statistics file by `ccl:report-coverage`.  The following accessors are defined for `ccl:coverage-statistics` objects:
     135   * `ccl:coverage-source-file` - the name of the source file corresponding to this information
     136   * `ccl:coverage-expressions-total` - the total number of expressions
     137   * `ccl:coverage-expressions-entered` - the number of source expressions that have been entered (i.e. at least partially covered)
     138   * `ccl:coverage-expressions-covered` - the number of source expressions that were fully covered
     139   * `ccl:coverage-unreached-branches` - the number of conditionals with one branch taken and one not taken
     140   * `ccl:coverage-code-forms-total` - the total number of ''code forms''.  A code form is an expression in the final stage of compilation, after all macroexpansion and compiler transforms and simplification
     141   * `ccl:coverage-code-forms-covered` - the number of code forms that have been entered
     142   * `ccl:coverage-functions-total` - the total number of functions
     143   * `ccl:coverage-functions-fully-covered` - the number of functions that were fully covered
     144   * `ccl:coverage-functions-partly-covered` - the number of functions that were partly covered
     145   * `ccl:coverage-functions-not-entered` - the number of functions never entered
     146
    107147
    108148'''`CCL:*COMPILE-CODE-COVERAGE*`'''