Using Harness.add_storage(..., attach=True) before begin_with_initial_hooks gives confusing error

[tonyandrewmeyer]

For example:

import ops
import ops.testing

class MyCharm(ops.CharmBase):
    pass

meta = """
            containers:
                test-container:
                    mounts:
                        - storage: test-storage
                          location: /mounts/foo
            storage:
                test-storage:
                    type: filesystem
"""

h = ops.testing.Harness(MyCharm, meta=meta)
try:
    h.add_storage("test-storage", attach=True)
    h.begin_with_initial_hooks()
finally:
    h.cleanup()

If begin() is used instead of begin_with_initial_hooks, everything is ok, because begin_with_initial_hooks does the attaching (to then emit the StorageAttached event) and begin does not. Similarly, if attach=True is not used, everything is ok.

However, when run as above, an error like this is generated:

Traceback (most recent call last):
  File "/tmp/storagetest/test.py", line 41, in <module>
    h.begin_with_initial_hooks()
  File "/tmp/storagetest/.venv/lib/python3.11/site-packages/ops/testing.py", line 407, in begin_with_initial_hooks
    self.attach_storage(s.full_id)
  File "/tmp/storagetest/.venv/lib/python3.11/site-packages/ops/testing.py", line 752, in attach_storage
    if not self._backend._storage_attach(storage_id):
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/storagetest/.venv/lib/python3.11/site-packages/ops/testing.py", line 2348, in _storage_attach
    mounting_dir.symlink_to(target_dir)
  File "/usr/lib/python3.11/pathlib.py", line 1199, in symlink_to
    os.symlink(target, self, target_is_directory)
FileExistsError: [Errno 17] File exists: '/tmp/ops-harness-z2tflymi/storages/test-storage/0' -> '/tmp/ops-harness-z2tflymi/containers/test-container/mounts/foo'

This happens because the add_storage call mounts the storage, and then the begin_with_initial_hooks attempts to mount it again, but that's already happened, so the symlinking fails.

We should:

• Adjust the API documentation so that it explicitly says that attach does nothing if begin hasn't yet been called
• Verify that begin has been called (ie. ._charm is not None) before trying to mount the storage