terminal: notify terminal emulator about test session progress #13728

bluetech · 2025-09-14T15:16:14Z

Use OSC 9;4 ANSI sequences terminal progress to notify the terminal emulator about progress, so it can display it to the user (e.g. on the terminal tab).

Fix #13072.

bluetech · 2025-09-14T15:23:34Z

This replaces PR #13395.

While searching the web for OSC 9;4, I found some reports that this sequence conflicts with OSC 9 usage by the iTerm terminal emulator, which uses it for generating desktop notifications. So this might end up generating a bunch of notifications on such terminals... I will need to test if that is indeed the case. Though I don't have easy access to macOS so if someone's able to test it that would be appreciated :)

For reference I tested it on:

Supported: Gnome Terminal, Ptyxis, Kitty (though for some reason the reset doesn't work?)
Not supported (ignored): ~~Ghostty~~ (is supported now)

The-Compiler · 2025-09-15T14:12:25Z

Though I don't have easy access to macOS so if someone's able to test it that would be appreciated :)

For what it's worth, I can recommend Scaleway for this. They charge 0.11€/h for a Mac Mini you can access remotely, so you pay 2.64€ for the minimum of 24h to try something out. Could easily get it back after via our OpenCollective too. Only caveat is that you need to remember to disable it after 24h, because you can't do that in advance sadly.

webknjaz · 2025-09-15T14:53:49Z

@bluetech could you include links to relevant docs/standards for future reference?

changelog/13072.feature.rst

webknjaz · 2025-09-15T14:55:48Z

Is https://conemu.github.io/en/AnsiEscapeCodes.html#ConEmu_specific_OSC the canonical standard?

bluetech · 2025-09-16T12:09:27Z

@The-Compiler thanks for the suggestion, in the end I was able to get access to an old apple laptop.

@webknjaz Yes, I think ConEmu invented these sequences. There is a link in the code, but I will also link it in the changelog.

The `write` method does some processing on the input, namely markup and adding to the current line. `write_raw` skips these parts. It is useful for emitting invisible escape sequences.

Return how many items have been reported in the progress so far. This cleans up the code a bit, but also allows grabbing this info without accessing the internals. We can consider making this property public separately.

bluetech · 2025-09-16T12:39:25Z

Updated the changelog.
Changed the code to use match, reads more nicely (I wish it were an expression instead of a statement...)

nicoddemus

Thanks! Tested it and the feature works well on Windows.

The-Compiler

I added a couple of thoughts - mostly worried about the things in the changelog, the rest is "take it or leave it" material in my book 😉

The-Compiler · 2025-09-25T19:50:36Z

src/_pytest/terminal.py

+
+        # OSC 9;4 sequence: ESC ] 9 ; 4 ; state ; progress ST
+        # ST can be ESC \ or BEL. ESC \ seems better supported.
+        match state:


Since you say Changed the code to use match, reads more nicely I'll take the freedom to nitpick on this:

Wouldn't it be simpler to say something like (untested):

state_ids = { "remove": 0, "normal": 1, "error": 2, "indeterminate": 3, "paused": 4, } state_id = state_ids[state] if progress is None: assert state != "normal" progress = "" else: assert state not in ["remove", "indeterminate"], state sequence = f"\x1b]9;4;{state_id};{progress}\x1b\\"

I find this harder to read, so somewhat prefer the match version. Just straight dumb code :)

The-Compiler · 2025-09-25T19:51:27Z

changelog/13072.feature.rst

@@ -0,0 +1,6 @@
+Added support for displaying test session progress in the terminal tab using the `OSC 9;4; <https://conemu.github.io/en/AnsiEscapeCodes.html#ConEmu_specific_OSC>`_ ANSI sequence.
+When pytest runs in a supported terminal emulator like ConEmu, Gnome Terminal, Ptyxis, Windows Terminal or Ghostty,


Kitty as well maybe?

The-Compiler · 2025-09-25T19:52:25Z

changelog/13072.feature.rst

+you'll see the progress in the terminal tab or window,
+allowing you to monitor pytest's progress at a glance.
+
+This feature is automatically enabled.


Should we really do that? If yes, should we maybe mention -p no:terminalprogress as an escape hatch to disable it?

With e.g. stable Linux distributions, it's entirely possible people will continue using affected versions (that show notifications) for possibly years. Has someone checked how that situation looks like on e.g. Ubuntu 22.04 (supported until 2027) or 24.04 (until 2029)?

Yea, I'll mention it.

Regarding possible breakage, I'm definitely concerned about it. But I think we should just try it and see. I understand that smells like the derided "move fast and break stuff" approach, but I am not able to do full testing on other distros myself unfortunately. I am a bit optimistic because:

Not a lot of terminal emulators implemented the desktop notification sequence

None of the default terminal emulators (which probably most people use) implemented it AFAIK

systemd already uses it (though admittedly that's linux only and much less like to be running on older distros than pytest).

It's possible we'll need to change it to off-by-default if there are complaints.

The-Compiler · 2025-09-25T19:57:56Z

testing/test_terminal.py

+        plugin._emit_progress("indeterminate")
+        assert "\x1b]9;4;3;\x1b\\" in mock_file.getvalue()
+        mock_file.truncate(0)
+        mock_file.seek(0)


Parametrize the test case maybe?

bluetech · 2025-10-01T08:16:15Z

@The-Compiler thanks for the review. I updated the PR.

The-Compiler

Thanks, let's get this in and see what people say!

Use OSC 9;4 ANSI sequences terminal progress to notify the terminal emulator about progress, so it can display it to the user (e.g. on the terminal tab). Fix pytest-dev#13072. Co-Authored-By: Anna Tasiopoulou <[email protected]>

psf-chronographer bot added the bot:chronographer:provided (automation) changelog entry is part of PR label Sep 14, 2025

webknjaz reviewed Sep 15, 2025

View reviewed changes

changelog/13072.feature.rst Outdated Show resolved Hide resolved

bluetech added 2 commits September 16, 2025 15:16

terminal: add a TerminalReporter.write_raw method

5a73c57

The `write` method does some processing on the input, namely markup and adding to the current line. `write_raw` skips these parts. It is useful for emitting invisible escape sequences.

terminal: add TerminalReporter.reported_progress

c71920c

Return how many items have been reported in the progress so far. This cleans up the code a bit, but also allows grabbing this info without accessing the internals. We can consider making this property public separately.

bluetech force-pushed the terminal-tab-progress branch from c99e5ed to f1b1c0a Compare September 16, 2025 12:36

nicoddemus approved these changes Sep 18, 2025

View reviewed changes

The-Compiler requested changes Sep 25, 2025

View reviewed changes

bluetech force-pushed the terminal-tab-progress branch from f1b1c0a to a090c83 Compare October 1, 2025 08:15

The-Compiler approved these changes Oct 1, 2025

View reviewed changes

bluetech force-pushed the terminal-tab-progress branch from a090c83 to 99cd7a2 Compare October 1, 2025 09:38

bluetech merged commit a55c959 into pytest-dev:main Oct 1, 2025
27 of 33 checks passed

bluetech deleted the terminal-tab-progress branch October 1, 2025 10:00

bluetech mentioned this pull request Oct 2, 2025

Terminal tab progress reporting issue #13072 #13395

Closed

		@@ -0,0 +1,6 @@
		Added support for displaying test session progress in the terminal tab using the `OSC 9;4; <https://conemu.github.io/en/AnsiEscapeCodes.html#ConEmu_specific_OSC>`_ ANSI sequence.
		When pytest runs in a supported terminal emulator like ConEmu, Gnome Terminal, Ptyxis, Windows Terminal or Ghostty,

Uh oh!

terminal: notify terminal emulator about test session progress #13728

terminal: notify terminal emulator about test session progress #13728

Conversation

bluetech commented Sep 14, 2025

Uh oh!

bluetech commented Sep 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

The-Compiler commented Sep 15, 2025

Uh oh!

webknjaz commented Sep 15, 2025

Uh oh!

Uh oh!

webknjaz commented Sep 15, 2025

Uh oh!

bluetech commented Sep 16, 2025

Uh oh!

bluetech commented Sep 16, 2025

Uh oh!

nicoddemus left a comment

Choose a reason for hiding this comment

Uh oh!

The-Compiler left a comment

Choose a reason for hiding this comment

Uh oh!

The-Compiler Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

bluetech Sep 30, 2025

Choose a reason for hiding this comment

Uh oh!

The-Compiler Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

bluetech Sep 30, 2025

Choose a reason for hiding this comment

Uh oh!

The-Compiler Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

bluetech Sep 30, 2025

Choose a reason for hiding this comment

Uh oh!

The-Compiler Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

bluetech commented Oct 1, 2025

Uh oh!

The-Compiler left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

bluetech commented Sep 14, 2025 •

edited

Loading