docs: separate test_workload_version_is_set in k8s tutorial chapter 3

[tromai]

This PR brought test_workload_version_is_set back to life in chapter 3, and propagate that change to chapter 4 and 5. It also updated the example examples/k8s-*/tests/integration/test_charm.py files.

Doc preview

It was raised by David:

In the k8s tutorial Chapter, section write an integration test, we replace the contents of test_charm.py. That loses test_workload_version_is_set and we never recreate it. In the corresponding file in the example charm, we keep the version check as part of test_database_integration, but we don't have that in the tutorial.

[dwilding]

Nice work!

[dwilding]

I hadn't thought of using a diff - we rarely use them (I see only one other instance in the Ops docs). Definitely not against it! I'd like to see @tonyandrewmeyer's opinion on whether the intent is clear enough.

[tonyandrewmeyer]

I'm not keen on the diff, because it seems harder to both maintain and to use, although perhaps easier to read. For maintenance, we want to load this in from the actual files, and I don't think that can be done as a diff, so we would have to manually re-create the diff every time the code changes. For use, I think it's much simpler to hit the copy button and then paste than to apply a patch.

However, if this is the only line that's changing, then I think we are showing too much of the file. Just the test would be enough.

[dwilding]

This is a convincing reason not to do a diff. I'm good if we show the new version of the test_deploy function, which can retain the comment about why we're waiting for blocked status.

[tromai]

Thanks for the feedback. I added this function back in 8b27c59.
It's a good point on copy-and-paste experience for readers.

[tromai]

Another observation I have, we instructed the readers to run integration tests in 2 ways:

In your Multipass Ubuntu VM, run the tests again:

```text
ubuntu@juju-sandbox-k8s:~/fastapi-demo$ tox -e integration
```

here, and

Run the following command from anywhere in the `~/fastapi-demo` directory:

```text
tox -e integration
```

here and here.

In the setup your development environment chapter, we instructed the reader to switch to the VM, so I assume we don't need the "In your Multipass Ubuntu VM" part anymore ?

[dwilding]

I assume we don't need the "In your Multipass Ubuntu VM" part anymore ?

Yeah, I think it's fine to remove this - good thinking. Earlier in the tutorial we established that commands are run in the VM, even if the reader is editing files using their regular editor.

[tonyandrewmeyer]

I guess this is because we don't have abort_on_fail yet. I'm not a huge fan of this approach, but perhaps it's ok for a tutorial, where you don't want to have to build something more complex.

It also seems a bit strange if you skip setup, where you presumably have the deployed app already, and don't actually need the charm, although probably it is findable and the cost is low, since it needs to already have been packed.

Is this a pattern we are creating or something we see in real charms? I see we already do this with the database test, is this just documenting something we already decided to do?

[dwilding]

It's the approach we previously standardised on in our docs and example charms.

[tonyandrewmeyer]

I'm not keen on the diff, because it seems harder to both maintain and to use, although perhaps easier to read. For maintenance, we want to load this in from the actual files, and I don't think that can be done as a diff, so we would have to manually re-create the diff every time the code changes. For use, I think it's much simpler to hit the copy button and then paste than to apply a patch.

However, if this is the only line that's changing, then I think we are showing too much of the file. Just the test would be enough.