Merging Coverage

Coverage from multiple test runs must be merged into a single database before you can report on the full regression. Use ucis merge:

ucis merge -o merged.xml test1.xml test2.xml test3.xml

Common Options

--input-format / -if

Source format. Specify once and it applies to all inputs. Defaults to xml. Use vltcov, cocotb-xml, etc. to merge directly from simulator output without a prior convert step.

ucis merge --input-format vltcov -o merged.xml \
    test1/coverage.dat test2/coverage.dat
--output-format / -of

Output format. Defaults to xml. Use sqlite for large regressions — it is faster to query and supports the --fast path.

ucis merge --output-format sqlite -o merged.ucisdb \
    test1.xml test2.xml test3.xml
--fast

SQLite-to-SQLite only. Bypasses the in-memory model and merges directly at the database level. Significantly faster for large regressions. Requires both inputs and output to be SQLite format.

ucis merge --input-format sqlite --output-format sqlite --fast \
    -j 8 -o merged.ucisdb tests/*.ucisdb
-j / --workers

Number of parallel reader threads for --fast merge (default: 4).

--squash-history

Collapse per-test history nodes into a single summary. Useful when you do not need per-test attribution in the merged result.

NCDB — Fast, Compact Merging

For large regressions the NCDB format offers the best merge performance and the smallest disk footprint (typically 100–200× smaller than SQLite). Use ncdb as the output format to accumulate per-test .cdb files:

# Per-test run (simulator writes NCDB directly, or convert after)
ucis convert -if sqlite -of ncdb -o test_42.cdb test_42.ucisdb

# Merge all per-test NCDB files into one
ucis merge --input-format ncdb --output-format ncdb \
    -o regression.cdb tests/test_*.cdb

When all input files share the same scope-tree structure (same design, same elaboration), NCDB uses a same-schema fast-merge path that reduces the merge to element-wise integer addition over a flat array — no SQL overhead, no scope-tree parsing. See NCDB Coverage File Format for the technical details.

When to choose NCDB vs SQLite:

  • NCDB — continuous integration, large seed sweeps, any scenario where disk space and merge speed matter.

  • SQLite — when you need to query coverage via SQL, or when third-party tools require a SQLite .cdb.

Typical Regression Workflow

# 1. Run tests (each produces a coverage file)
make run_all_tests   # produces test_*.xml

# 2. Merge
ucis merge -o regression.xml test_*.xml

# 3. Explore or report
ucis view regression.xml
ucis report regression.xml -of html -o regression_report.html

Next Steps