Testing¶
A test suite that drives TensorWeaver usually runs in two places: on a machine
with a licence, where circuits are really simulated, and in CI, where there is
often no licence and no wish to spend minutes simulating. MockTensorWeaver
serves the second case. It takes the same arguments as TwSimulator, refuses
the same inputs, and returns real QCSResults without simulating anything;
Without a licence describes exactly what it guarantees.
This page covers how to set up a project and its tests around the two.
One suite, two backends¶
Pick the backend in one place, a fixture, and let every test take it. An environment variable makes the choice explicit:
# conftest.py
import os
import pytest
import tensorweaver as tw
MOCK = os.environ.get("TW_MOCK") == "1"
@pytest.fixture
def simulator():
# Same keywords for both: a knob the real simulator rejects is rejected
# by the mock too, so CI catches it without a licence.
cls = tw.MockTensorWeaver if MOCK else tw.TwSimulator
return cls(bonddim=64, algorithm="cmpo")
# For tests that check physics rather than plumbing.
needs_simulation = pytest.mark.skipif(MOCK, reason="MockTensorWeaver simulates nothing")
# test_pipeline.py
import mimiqcircuits as mc
from conftest import needs_simulation
def bell():
c = mc.Circuit()
c.push(mc.GateH(), 0)
c.push(mc.GateCX(), 0, 1)
c.push(mc.Measure(), [0, 1], [0, 1])
return c
def test_results_round_trip(simulator, tmp_path):
# Plumbing: runs the same against the mock and the real simulator.
res = simulator.execute(bell(), nsamples=100, seed=1)
assert len(res.cstates) == 100
res.saveproto(tmp_path / "out.pb")
@needs_simulation
def test_bell_correlations(simulator):
# Physics: the mock returns all-zero samples, so this only means
# something on the real simulator.
res = simulator.execute(bell(), nsamples=1000, seed=1)
assert {bs.to01() for bs in res.cstates} == {"00", "11"}
Run TW_MOCK=1 pytest in CI and plain pytest on a licensed machine.
Use an explicit switch like TW_MOCK rather than detecting the licence.
tw.has_kernels() says whether the build can simulate, not whether a
licence is present: it is True for the licensed package on a machine without
a licence, where TwSimulator then raises LicenseError at the first run.
The direct simulator and Qiskit¶
TwDirectSimulator has its own mock, MockTensorWeaverDirect, with the same
constructor and refusals. Swap it in the fixture the same way:
The Qiskit backend and estimator take the switch as mock=, for either
simulator:
from tensorweaver.qiskit import TensorWeaverBackend, TensorWeaverEstimator
backend = TensorWeaverBackend(simulator="direct", mock=MOCK, bonddim=64)
estimator = TensorWeaverEstimator(mock=MOCK, bonddim=64)
With mock=True every shot is the all-zero outcome and every expectation value
is 0. See Choosing a simulator.
Installing for CI¶
The same package everywhere¶
The mocks are in every build, so the licensed package serves both sides.
Without a licence it imports, the mocks run, and only
TwSimulator and TwDirectSimulator refuse, with LicenseError. Nothing in
the project changes between the two environments: install
mimiq-tensorweaver from the QPerfect index as described in
Getting Started, and set TW_MOCK=1 in CI.
Without a licence, importing tensorweaver prints one line to standard error,
tw: license init failed: license file not found .... It is expected and does
not stop the mock.
This is the simplest setup whenever CI can reach the QPerfect index or the wheel file.
CI without access to the licensed package¶
If CI cannot reach the QPerfect index, it can install the public build from
PyPI instead. It holds the same tensorweaver module with every compute kernel
left out, so the mocks are the only backends that run on it. It is published
under two names with the same contents: mimiq-tensorweaver, the licensed
package's own name, and mimiq-tensorweaver-mock.
Never install the public and the licensed build in one environment, under either name: they write the same files. Under two different names, nothing warns you about it.
Under its own name¶
mimiq-tensorweaver-mock lets a project declare both builds without any index
configuration. With pip, keep them in separate requirements files, one per
environment. In a uv project, two dependency groups that exclude each other do
it from one pyproject.toml and one lockfile. Here the licensed build comes
as a wheel file:
[dependency-groups]
licensed = ["mimiq-tensorweaver"]
mock = ["mimiq-tensorweaver-mock"]
[tool.uv]
# Both install the `tensorweaver` package, so they can never be installed
# together.
conflicts = [[{ group = "licensed" }, { group = "mock" }]]
[tool.uv.sources]
mimiq-tensorweaver = { path = "wheels/mimiq_tensorweaver-<version>-<tags>.whl" }
The wheel file is needed to create or update the lockfile, not to install the mock:
uv sync --group licensed # licensed machine, wheel file present
uv sync --frozen --group mock # CI, no wheel file, no credentials
To take the licensed build from the QPerfect index instead, point its source at it as Getting Started shows.
Under the same name¶
The two builds also share the name mimiq-tensorweaver, so that code and
imports do not change between them. In a uv project, two dependency groups
that exclude each other give each environment its build from its own index:
[dependency-groups]
licensed = ["mimiq-tensorweaver"]
mock = ["mimiq-tensorweaver"]
[tool.uv]
# The two groups install the same package from different places, so they can
# never be installed together.
conflicts = [[{ group = "licensed" }, { group = "mock" }]]
[[tool.uv.index]]
name = "qperfect"
url = "https://gitlab.qperfect.io/api/v4/projects/29/packages/pypi/simple"
explicit = true
[[tool.uv.index]]
name = "pypi"
url = "https://pypi.org/simple"
explicit = true
[tool.uv.sources]
mimiq-tensorweaver = [
{ index = "qperfect", group = "licensed" },
{ index = "pypi", group = "mock" },
]
The lockfile records both builds, so creating or updating it needs the
QPerfect credentials (UV_INDEX_QPERFECT_USERNAME and
UV_INDEX_QPERFECT_PASSWORD). Installing does not, for the mock:
uv sync --group licensed # licensed machine
uv sync --frozen --group mock # CI, no credentials needed
If you receive the licensed build as a wheel file rather than from the index,
use a path for the licensed source instead:
{ path = "wheels/mimiq_tensorweaver-<version>-<tags>.whl", group = "licensed" }.
The public build is published with the same version numbers as the licensed one, but may lag behind it. Check that the version CI installs is the one you test against.