@tmihoc and @dwilding would you suggest just linking to the docs, like:

Harness is deprecated; we recommend using state transition testing (previously known as 'Scenario') instead. How-to: https://ops.readthedocs.io/en/latest/howto/write-scenario-tests-for-a-charm.html, reference: https://ops.readthedocs.io/en/latest/reference/ops-testing.html

Or would you include more? Or less, just one link?

@tonyandrewmeyer I would do:

Harness is deprecated; we recommend using state transition testing (previously known as 'Scenario') instead. See more: https://ops.readthedocs.io/en/latest/howto/write-scenario-tests-for-a-charm.html

The how-to already links to the reference, so that should be fine.

PS I'm a little confused by "state transition testing". The name of the ops module is just ops.testing, right? What I'm trying to say is we should perhaps just pick a name and stick with it throughout. As it is, we have "scenario" in the how-to guide, "testing" in the reference, and "state transition testing" in the metalanguage around it all.

PS I'm a little confused by "state transition testing". The name of the ops module is just ops.testing, right? What I'm trying to say is we should perhaps just pick a name and stick with it throughout. As it is, we have "scenario" in the how-to guide, "testing" in the reference, and "state transition testing" in the metalanguage around it all.

Yeah, it's quite annoying. Saying "Scenario" would work fine, but we got the word from up high that it's not to be used as a public name (using it as an internal code name is ok). I've removed most of the public references to "Scenario" already - the how-to guides have a PR open (I was waiting for the docs to move here, rather than do changes during the migration). If you find ones left we probably need to update them.

ops.testing is the namespace where you find the classes (Context, State, and so on). However, it's also where you find Harness, so it doesn't really distinguish itself.

ops[testing] is the way to optionally install the (ops-scenario) package. This doesn't seem like a great name to use.

"State transition testing" is probably the most accurate description of what these tests are actually doing. It's a long name.

"The ops testing harness" and variations of that don't really work because of Harness.

"Unit tests" is our shorthand reference, and generally what we are trying to call these. That's why the old docs (yesterday 😉) titled the page "Unit testing (was Scenario)" but now the names are all the namespaces instead of descriptive. But you can say "write charm unit tests with Harness" but you can't say "write charm unit tests with unit tests". In time, our hope is people default to the new system (Scenario) and say "write charms tests with the ops unit testing framework" or similar.

@tonyandrewmeyer Thanks for the context there. It's good for me to know even as I don't have any useful suggestion to offer at this time.

I would only do 1 link vs 2. I think that link can be a good place to expand on other resources that people would want to look at.

I also think the ops.testing vs ops[testing] vs ops-scenario is a source of confusion. (pip install ops[testing] causes it to install ops-scenario which causes ops.testing to populate itself with the testing content is how I understand it, but it is quite the mouthful to explain.)

And I'm guessing the issue is that we didn't want to have ops.testing present at runtime for every charm, but we did want it as part of the namespace for charmers. (Offhand, I have to wonder if ops_testing or something along those lines as a top level package might have been fewer handoffs and explanations needed.)

Anyway, I don't think using "Unit Testing" in the deprecation warning is sufficient, because it is Ops Unit Testing, or some top level caveat.

I think just saying ops.testing.Harness is deprecated, see https://juju.is/docs/sdk/unit-testing.hmtl or something to that effect would be reasonable. Its relatively short, it can fit on 1 line, and it gives you a URL that lets you explain whatever we feel is relevant.