Ingesting Reports

Ingestion is the process of reading a report generated by a test framework, normalizing it into QA Lens models, and storing it in SQLite.

QA Lens is not a test runner. Your CI or local test command still produces the report. QA Lens reads that report after the run completes.

Supported Formats

Detect a Report

Before ingestion, you can ask QA Lens what format it sees:

qalens detect path/to/report

Verbose mode explains why a parser matched:

qalens detect path/to/report --verbose

Extract Without Storing

Use extract when debugging parser behavior or inspecting the normalized model:

qalens extract path/to/report --out normalized-run.json

If --out is omitted, JSON is printed to stdout.

Ingest Into SQLite

qalens ingest path/to/report --db ./qalens.db

If --db is omitted, QA Lens uses:

~/.qalens/qalens.db

Idempotency

Ingestion is idempotent by run identity. If the same run already exists, QA Lens skips it.

To re-ingest the same run:

qalens ingest path/to/report --db ./qalens.db --force

Use --force when:

• You changed parser code.
• You fixed owner mapping.
• The original report was incomplete.
• You want to replace an existing run record.

Projects

QA Lens stores a project value with each run when available from the report metadata. Project scoping is used by:

• The project dropdown in the UI.
• API query parameters.
• Chat context.
• Report exports.

If reports from different applications are stored in the same database, project names help keep views separated.

Owner Mapping

Owner mapping assigns tests, suites, features, stories, or tags to teams.

Example command:

qalens ingest path/to/report --db ./qalens.db --owner-map owners.toml

Use owner mapping when:

• Reports do not include owner metadata.
• You want consistent team names across frameworks.
• You want Analysis and Risk views grouped by owner.

Use --override-owners if the mapping file should replace owner labels that already exist in the report:

qalens ingest path/to/report --db ./qalens.db --owner-map owners.toml --override-owners

Artifact and Screenshot Policy

QA Lens supports artifact metadata and optional image byte storage.

Default:

--artifact-mode metadata-only

Modes:

Examples:

qalens ingest path/to/report --db ./qalens.db --artifact-mode text-only
qalens ingest path/to/report --db ./qalens.db --artifact-mode metadata-only
qalens ingest path/to/report --db ./qalens.db --artifact-mode full

Useful caps:

qalens ingest path/to/report \
  --db ./qalens.db \
  --artifact-mode full \
  --max-screenshots-per-failure 2 \
  --max-screenshot-bytes 5242880 \
  --max-total-screenshot-bytes 52428800

Use metadata-only for most CI setups. Use full only when the UI needs to display stored screenshots after the original report folder is unavailable.

Ingesting Multiple Runs

QA Lens becomes more useful with history.

qalens ingest reports/run-001 --db ./qalens.db
qalens ingest reports/run-002 --db ./qalens.db
qalens ingest reports/run-003 --db ./qalens.db

History enables:

• Flakiness scoring.
• Risk scoring.
• Failure trend direction.
• Incident persistence.
• Run-to-run comparison.
• Pass-rate extrema questions.
• Action Brief prioritization.

CI Usage

Example GitHub Actions pattern:

- name: Ingest test report
  run: qalens ingest path/to/report --db qalens.db

- name: Export QA Lens report
  run: qalens report --db qalens.db --out qalens-report.html

- name: Upload QA Lens report
  uses: actions/upload-artifact@v4
  with:
    name: qalens-report
    path: qalens-report.html

For long-lived history, persist qalens.db between CI runs or store it in an artifact/cache strategy your team controls.

What QA Lens Stores

The SQLite database stores:

• Runs.
• Test cases.
• Statuses.
• Durations.
• Suites/features/stories/tags.
• Failure messages and stack traces.
• Normalized failure fingerprints.
• Owner labels.
• Artifact metadata.
• Optional artifact storage references.

QA Lens does not need the original report after ingestion unless you chose not to store needed artifacts and still want to inspect original files separately.