[Tests][CI] contrib LaTeX tests fail instead of skipping when dependencies missing

[karineek]

Describe the issue

When running python -m pytest cirq-core/ some tests in cirq.contrib failed when LaTeX dependencies are missing or partially installed, instead of being skipped. The error is (when grep with error/warning string the outputs):

ubuntu@fuzzer-03:~/git/try/H-Fuzz$ ./Cirq/script.sh 
cirq-core/cirq/contrib/quantikz/circuit_to_latex_render_test.py:41: AssertionError
!!! pdflatex failed on run 1 (exit code 1) !!!
! LaTeX Error: File `standalone.cls' not found.
!  ==> Fatal error occurred, no output PDF file produced!
        os_error = None
            except (OSError, IOError) as e:
                # Use FileNotFoundError when python 2 is dropped
                os_error = e
                if os_error.errno == errno.ENOENT:
            except subprocess.CalledProcessError as e:
                # For all other errors print the output and raise the error
                except (OSError, IOError, subprocess.CalledProcessError):
                        except (OSError, IOError) as e:
                            # Use FileNotFoundError when python 2 is dropped
                CompilerError(
E           pylatex.errors.CompilerError: No LaTex compiler was found
.venv/lib/python3.11/site-packages/pylatex/document.py:325: CompilerError
=============================== warnings summary ===============================
cirq-core/cirq/experiments/z_phase_calibration_test.py::test_calibrate_z_phases_workflow_no_options[angles1-error1]
cirq-core/cirq/experiments/z_phase_calibration_test.py::test_calibrate_z_phases_workflow_no_options[angles2-error2]
    warnings.warn(
    warnings.warn(f"Op {op} no qubits.")
    warnings.warn(
cirq-core/cirq/experiments/single_qubit_readout_calibration_test.py::test_estimate_parallel_readout_errors_no_noise
cirq-core/cirq/experiments/single_qubit_readout_calibration_test.py::test_estimate_parallel_readout_errors_no_noise
    warnings.warn("Optimal parameters could not be found for curve fit", RuntimeWarning)
cirq-core/cirq/experiments/t1_decay_experiment_test.py::test_plot_does_not_raise_error
cirq-core/cirq/experiments/t1_decay_experiment_test.py::test_plot_does_not_raise_error
cirq-core/cirq/work/observable_measurement_data_test.py::test_bitstring_accumulator_errors
cirq-core/cirq/work/observable_measurement_data_test.py::test_bitstring_accumulator_errors
    warnings.warn(
-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
FAILED cirq-core/cirq/contrib/quantikz/circuit_to_latex_render_test.py::test_render_circuit
FAILED cirq-core/cirq/contrib/qcircuit/qcircuit_pdf_test.py::test_qcircuit_pdf
= 2 failed, 20025 passed, 10 skipped, 64 xfailed, 21 warnings in 285.91s (0:04:45) =

Then, after trying to install LaTeX/TeX packages, it works a little bit better (but I assume it was not the full right installation):

cirq-core/cirq/contrib/quantikz/circuit_to_latex_render_test.py:42: AssertionError
stdout = b'Latexmk: This is Latexmk, John Collins, 26 Dec. 2019, version: 4.67.\nRule \'latex\': The following rules & subrules... or warnings treated as errors.\n=== TeX engine is \'pdfTeX\'\nLatexmk: Errors, so I did not complete making targets\n'
        CalledProcessError. The CalledProcessError object will have the return code
        triggered by setting any of text, encoding, errors or universal_newlines.
                raise ValueError('stdin and input arguments may not both be used.')
                raise ValueError('stdout and stderr arguments may not be used '
>               raise CalledProcessError(retcode, process.args,
E               subprocess.CalledProcessError: Command '['latexmk', '-pdfps', '--interaction=nonstopmode', '/tmp/pytest-of-ubuntu/pytest-38/test_qcircuit_pdf0/test_file.tex']' returned non-zero exit status 12.
/usr/lib/python3.11/subprocess.py:571: CalledProcessError
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
! LaTeX Error: Missing \begin{document}.
Collected error summary (may duplicate other messages):
 unless error was exceeding maximum runs, or warnings treated as errors.
Latexmk: Errors, so I did not complete making targets
...
FAILED cirq-core/cirq/contrib/quantikz/circuit_to_latex_render_test.py::test_render_circuit
FAILED cirq-core/cirq/contrib/qcircuit/qcircuit_pdf_test.py::test_qcircuit_pdf
= 2 failed, 20025 passed, 10 skipped, 64 xfailed, 21 warnings in 289.77s (0:04:49) =

Some documentation in some deep subfolder helps to resolve it, but it takes some effort to find it:

cirq-core/cirq/contrib/quantikz/circuit_to_latex_render.py:            "On Ubuntu/Debian: `sudo apt-get install texlive-full` "

However, it will be a good idea to add it in the main README.

Expected Result:

Not to crash if there are missing install, either suggest exactly how to install the missing packages or add a skip:

[Suggested Fix] Nonetheless, the best practice is likely to skip when one of the LaTeX/TeX dependencies is missing, adding something like this:

pytest.mark.skipif(shutil.which("pdflatex") is None, ...)

Tell us the version of Cirq where this happens

I use Cirq from source version: commit 9888067c5c36b4505917de57f0528c53882ec240
Python: Python 3.11.11

You can get the Cirq version you are running by using Python
to print the value of cirq.__version__. From the command line:

python -c 'import cirq; print(cirq.__version__)'

This prints:

(.venv) ubuntu@fuzzer-03:~/Cirq$ python -c 'import cirq; print(cirq.__version__)'
1.6.1

Reproducing the error:

I used this script:

ubuntu@fuzzer-03:~/git/try/H-Fuzz$ cat Cirq/script.sh 
#!/bin/bash
cd ~/Cirq
source .venv/bin/activate
which pdflatex
python -m pytest cirq-core/ | grep -e"Crash" -e"Failed" -e"FAILED" -e"failed" -e"error" -e"crash" -e"warnings" -e"Warnings" -e"Error" -e"ERROR"

initially, without the installation of LaTeX/TeX, and then trying to install it using the hints I have found in the documentation of Cirq.

[mhucka]

@karineek Thank you for your report. It's not clear if you installed the developer dependencies following the developer documentation at https://quantumai.google/cirq/dev/development

Could you clarify if that is the case or not?

The necessary dependencies should have gotten installed when doing step 2 under "Setting up an environment".

[karineek]

Thanks for the response. Right after I did: git clone https://github.com/quantumlib/Cirq.git, I ran these:

 1127  cd /home/ubuntu/Cirq
 1128  python3.11 -m venv .venv
 1129  source .venv/bin/activate
 1130  python --version
 1131  python -m pip install --upgrade pip
 1132  python -m pip install -r dev_tools/requirements/dev.env.txt

Then, when this did not work, I followed the advice in cirq-core/cirq/contrib/quantikz/circuit_to_latex_render.py and ran:

`sudo apt-get install texlive-full`

This specific one in cirq-core/cirq/contrib/quantikz/circuit_to_latex_render.py caused issues, did not solve the problem, and I had to revert. It would be helpful to add a note about this file and a recommendation.

I followed the instructions you added step by step in a new folder and venv. First, the venv does not enforce Python 3.11:

collected 0 items / 1 error                                                                                                                    

==================================================================== ERRORS ====================================================================
_______________________________________________________ ERROR collecting cirq-core/cirq ________________________________________________________
/usr/lib/python3.10/importlib/__init__.py:126: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
<frozen importlib._bootstrap>:1050: in _gcd_import
    ???
<frozen importlib._bootstrap>:1027: in _find_and_load
    ???
<frozen importlib._bootstrap>:992: in _find_and_load_unlocked
    ???
<frozen importlib._bootstrap>:241: in _call_with_frames_removed
    ???
<frozen importlib._bootstrap>:1050: in _gcd_import
    ???
<frozen importlib._bootstrap>:1027: in _find_and_load
    ???
<frozen importlib._bootstrap>:1006: in _find_and_load_unlocked
    ???
<frozen importlib._bootstrap>:688: in _load_unlocked
    ???
<frozen importlib._bootstrap_external>:883: in exec_module
    ???
<frozen importlib._bootstrap>:241: in _call_with_frames_removed
    ???
cirq-core/cirq/__init__.py:27: in <module>
    from cirq import (
cirq-core/cirq/_version.py:21: in <module>
    raise SystemError(
E   SystemError: You installed the latest version of Cirq but aren't on Python 3.11+.
E   To fix this error, you need to either:
E   
E   A) Update to Python 3.11 or later.
E   - OR -
E   B) Explicitly install an older deprecated-but-compatible version of Cirq (e.g. "python -m pip install cirq==1.5.0")
=========================================================== short test summary info ============================================================
ERROR cirq-core/cirq - SystemError: You installed the latest version of Cirq but aren't on Python 3.11+.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
=============================================================== 1 error in 1.46s ===============================================================
(cirq-py3) ubuntu@fuzzer-03:~/TEST/Cirq$

I then re-created the venv with Python 3.11, and re-run:

workon cirq-py3
python -m pip install --upgrade pip
python -m pip install -r dev_tools/requirements/dev.env.txt

Then it still seems to fail:

cirq-core/cirq/contrib/quantikz/circuit_to_latex_render_test.py F                                                                        [ 23%]

with the errors seem to be still the same:

=================================================================== FAILURES ===================================================================
_____________________________________________________________ test_render_circuit ______________________________________________________________

tmp_path = PosixPath('/tmp/pytest-of-ubuntu/pytest-47/test_render_circuit0')

    def test_render_circuit(tmp_path: pathlib.Path) -> None:
        q0, q1 = cirq.LineQubit.range(2)
        circuit = cirq.Circuit(
            cirq.H(q0),
            cirq.CNOT(q0, q1),
            cirq.rx(0.25 * np.pi).on(q1),
            cirq.measure(q0, q1, key='result'),
        )
        # Render and display in Jupyter (if available), also save to a file
        img_or_path = render_circuit(
            circuit,
            output_png_path=tmp_path / "my_circuit.png",
            output_tex_path=tmp_path / "my_circuit.tex",
            output_pdf_path=tmp_path / "my_circuit.pdf",
            fold_at=2,
            debug=True,
            wire_labels="qid",
        )
>       assert img_or_path is not None
E       assert None is not None

cirq-core/cirq/contrib/quantikz/circuit_to_latex_render_test.py:41: AssertionError
------------------------------------------------------------- Captured stdout call -------------------------------------------------------------
[Debug] Temporary directory created at: /tmp/tmprn603q2h
[Debug] Generating LaTeX source...
[Debug] Generated LaTeX (first 500 chars):
 \documentclass[preview, border=2pt]{standalone}
% Core drawing packages
\usepackage{tikz}
\usetikzlibrary{quantikz} % Loads the quantikz library (latest installed version)
% Optional useful TikZ libraries
\usetikzlibrary{fit, arrows.meta, decorations.pathreplacing, calligraphy}
% Font encoding and common math packages
\usepackage[T1]{fontenc}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
% --- Custom Preamble Injection Point ---
% --- End Custom Preamble ---
\begin{document}
\b...
[Debug] LaTeX saved to temporary file: /tmp/tmprn603q2h/circuit_render.tex
[Debug] Running pdflatex (/usr/bin/pdflatex)...
[Debug]   pdflatex run 1/2...
!!! pdflatex failed on run 1 (exit code 1) !!!
--- Tail of circuit_render.log ---
This is pdfTeX, Version 3.14159265-2.6-1.40.20 (TeX Live 2019/Debian) (preloaded format=pdflatex 2026.4.7)  7 APR 2026 09:00
entering extended mode
 restricted \write18 enabled.
 %&-line parsing enabled.
**/tmp/tmprn603q2h/circuit_render.tex
(/tmp/tmprn603q2h/circuit_render.tex
LaTeX2e <2020-02-02> patch level 2
L3 programming layer <2020-02-14>

! LaTeX Error: File `standalone.cls' not found.

Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: cls)

Enter file name: 
! Emergency stop.
<read *> 
         
l.3 \usepackage
               {tikz}^^M 
Here is how much of TeX's memory you used:
 23 strings out of 483183
 566 string characters out of 5966293
 231602 words of memory out of 5000000
 15137 multiletter control sequences out of 15000+600000
 532338 words of font info for 24 fonts, out of 8000000 for 9000
 14 hyphenation exceptions out of 8191
 14i,0n,17p,114b,10s stack positions out of 5000i,500n,10000p,200000b,80000s

!  ==> Fatal error occurred, no output PDF file produced!

______________________________________________________________ test_qcircuit_pdf _______________________________________________________________

tmp_path = PosixPath('/tmp/pytest-of-ubuntu/pytest-47/test_qcircuit_pdf0')

    def test_qcircuit_pdf(tmp_path: pathlib.Path) -> None:
        circuit = cirq.Circuit(cirq.X(cirq.q(0)), cirq.CZ(cirq.q(0), cirq.q(1)))
>       qcircuit_pdf.circuit_to_pdf_using_qcircuit_via_tex(circuit, f"{tmp_path}/test_file")

cirq-core/cirq/contrib/qcircuit/qcircuit_pdf_test.py:25: 
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
cirq-core/cirq/contrib/qcircuit/qcircuit_pdf.py:65: in circuit_to_pdf_using_qcircuit_via_tex
    doc.generate_pdf(filepath, **pdf_kwargs)
.venv/lib/python3.11/site-packages/pylatex/document.py:276: in generate_pdf
    output = subprocess.check_output(
/usr/lib/python3.11/subprocess.py:466: in check_output
    return run(*popenargs, stdout=PIPE, timeout=timeout, check=True,
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 

input = None, capture_output = False, timeout = None, check = True
popenargs = (['latexmk', '-pdfps', '--interaction=nonstopmode', '/tmp/pytest-of-ubuntu/pytest-47/test_qcircuit_pdf0/test_file.tex'],)
kwargs = {'cwd': '/tmp/pytest-of-ubuntu/pytest-47/test_qcircuit_pdf0', 'stderr': -2, 'stdout': -1}
process = <Popen: returncode: 12 args: ['latexmk', '-pdfps', '--interaction=nonstopmod...>
stdout = b'Latexmk: This is Latexmk, John Collins, 26 Dec. 2019, version: 4.67.\nRule \'latex\': The following rules & subrules... or warnings treated as errors.\n=== TeX engine is \'pdfTeX\'\nLatexmk: Errors, so I did not complete making targets\n'
stderr = None, retcode = 12

    def run(*popenargs,
            input=None, capture_output=False, timeout=None, check=False, **kwargs):
        """Run command with arguments and return a CompletedProcess instance.
    
        The returned instance will have attributes args, returncode, stdout and
        stderr. By default, stdout and stderr are not captured, and those attributes
        will be None. Pass stdout=PIPE and/or stderr=PIPE in order to capture them,
        or pass capture_output=True to capture both.
    
        If check is True and the exit code was non-zero, it raises a
        CalledProcessError. The CalledProcessError object will have the return code
        in the returncode attribute, and output & stderr attributes if those streams
        were captured.
    
        If timeout is given, and the process takes too long, a TimeoutExpired
        exception will be raised.
    
        There is an optional argument "input", allowing you to
        pass bytes or a string to the subprocess's stdin.  If you use this argument
        you may not also use the Popen constructor's "stdin" argument, as
        it will be used internally.
    
        By default, all communication is in bytes, and therefore any "input" should
        be bytes, and the stdout and stderr will be bytes. If in text mode, any
        "input" should be a string, and stdout and stderr will be strings decoded
        according to locale encoding, or by "encoding" if set. Text mode is
        triggered by setting any of text, encoding, errors or universal_newlines.
    
        The other arguments are the same as for the Popen constructor.
        """
        if input is not None:
            if kwargs.get('stdin') is not None:
                raise ValueError('stdin and input arguments may not both be used.')
            kwargs['stdin'] = PIPE
    
        if capture_output:
            if kwargs.get('stdout') is not None or kwargs.get('stderr') is not None:
                raise ValueError('stdout and stderr arguments may not be used '
                                 'with capture_output.')
            kwargs['stdout'] = PIPE
            kwargs['stderr'] = PIPE
    
        with Popen(*popenargs, **kwargs) as process:
            try:
                stdout, stderr = process.communicate(input, timeout=timeout)
            except TimeoutExpired as exc:
                process.kill()
                if _mswindows:
                    # Windows accumulates the output in a single blocking
                    # read() call run on child threads, with the timeout
                    # being done in a join() on those threads.  communicate()
                    # _after_ kill() is required to collect that and add it
                    # to the exception.
                    exc.stdout, exc.stderr = process.communicate()
                else:
                    # POSIX _communicate already populated the output so
                    # far into the TimeoutExpired exception.
                    process.wait()
                raise
            except:  # Including KeyboardInterrupt, communicate handled that.
                process.kill()
                # We don't call process.wait() as .__exit__ does that for us.
                raise
            retcode = process.poll()
            if check and retcode:
>               raise CalledProcessError(retcode, process.args,
                                         output=stdout, stderr=stderr)
E               subprocess.CalledProcessError: Command '['latexmk', '-pdfps', '--interaction=nonstopmode', '/tmp/pytest-of-ubuntu/pytest-47/test_qcircuit_pdf0/test_file.tex']' returned non-zero exit status 12.

/usr/lib/python3.11/subprocess.py:571: CalledProcessError
------------------------------------------------------------- Captured stdout call -------------------------------------------------------------
Latexmk: This is Latexmk, John Collins, 26 Dec. 2019, version: 4.67.
Rule 'latex': The following rules & subrules became out-of-date:
      'latex'
------------
Run number 1 of rule 'latex'
------------
------------
Running 'latex  --interaction=nonstopmode -recorder  "/tmp/pytest-of-ubuntu/pytest-47/test_qcircuit_pdf0/test_file.tex"'
------------
Latexmk: applying rule 'latex'...
This is pdfTeX, Version 3.14159265-2.6-1.40.20 (TeX Live 2019/Debian) (preloaded format=latex)
 restricted \write18 enabled.
entering extended mode
(/tmp/pytest-of-ubuntu/pytest-47/test_qcircuit_pdf0/test_file.tex
LaTeX2e <2020-02-02> patch level 2
L3 programming layer <2020-02-14>
(/usr/share/texlive/texmf-dist/tex/latex/base/article.cls
Document Class: article 2019/12/20 v1.4l Standard LaTeX document class
(/usr/share/texlive/texmf-dist/tex/latex/base/size10.clo))
(/usr/share/texlive/texmf-dist/tex/latex/base/fontenc.sty)
(/usr/share/texlive/texmf-dist/tex/latex/base/inputenc.sty)

! LaTeX Error: File `lmodern.sty' not found.

Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: sty)

Enter file name: 
! Emergency stop.
<read *> 
         
l.5 \usepackage
               {textcomp}%^^M
No pages of output.
Transcript written on test_file.log.
Latexmk: Missing input file: 'lmodern.sty' from line
  '! LaTeX Error: File `lmodern.sty' not found.'
Latexmk: Log file says no output from latex
Latexmk: For rule 'latex', no output was made
Collected error summary (may duplicate other messages):
  latex: Command for 'latex' gave return code 1
      Refer to 'test_file.log' for details
Latexmk: Use the -f option to force complete processing,
 unless error was exceeding maximum runs, or warnings treated as errors.
=== TeX engine is 'pdfTeX'
Latexmk: Errors, so I did not complete making targets

=============================================================== warnings summary ===============================================================
cirq-core/cirq/ops/global_phase_op_test.py::test_protocols

[pavoljuhas]

! LaTeX Error: File `lmodern.sty' not found.

You need to install the texlive-latex-extra apt package.
(if that does not help just install explicitly the lmodern package)
I will update apt-system-requirements.txt to include that.