Skip to content
Become a
Sponsor or follow @15r10nk on
or
for updates

# external()

Storing snapshots in the source code is the main feature of inline snapshots. This has the advantage that you can easily see changes in code reviews. However, it also has some drawbacks:

- It is problematic to snapshot a large amount of data, as it consumes significant space in your tests.
- Binary data or images are not human-readable in your tests.

`external()` solves this problem and integrates nicely with inline snapshots. It stores a reference to the external data in a special `external()` object, which can be used like `snapshot()`.

There are different storage protocols, such as hash or uuid, and different file formats, such as .txt, .bin, and .json. It is also possible to implement custom file formats.

Example:

    from inline_snapshot import external

    def test_something():
        # inline-snapshot can determine the correct file types
        assert "string" == external()
        assert b"bytes" == external()

        # Data structures with lists and dictionaries are stored as JSON
        assert ["json", "like", "data"] == external()

        # You can also explicitly specify the storage protocol
        assert "other text" == external("uuid:")

        # And the format (.json instead of the default .txt in this case)
        assert "other text" == external("uuid:.json")

inline-snapshot will then fill in the missing parts when you create your snapshots. It will keep your specified protocols and file types and generate names for your snapshots.

    from inline_snapshot import external

    def test_something():
        # inline-snapshot can determine the correct file types
        assert "string" == external("uuid:e3e70682-c209-4cac-a29f-6fbed82c07cd.txt")
        assert b"bytes" == external("uuid:f728b4fa-4248-4e3a-8a5d-2f346baa9455.bin")

        # Data structures with lists and dictionaries are stored as JSON
        assert ["json", "like", "data"] == external(
            "uuid:eb1167b3-67a9-4378-bc65-c1e582e2e662.json"
        )

        # You can also explicitly specify the storage protocol
        assert "other text" == external(
            "uuid:f7c1bd87-4da5-4709-9471-3d60c8a70639.txt"
        )

        # And the format (.json instead of the default .txt in this case)
        assert "other text" == external(
            "uuid:e443df78-9558-467f-9ba9-1faf7a024204.json"
        )

The `external()` function can also be used inside other data structures.

    from inline_snapshot import snapshot, external

    def test_something():
        assert ["long text\n" * times for times in [1, 2, 1000]] == snapshot(
            [..., ..., external()]
        )

    from inline_snapshot import snapshot, external

    def test_something():
        assert ["long text\n" * times for times in [1, 2, 1000]] == snapshot(
            [
                "long text\n",
                """\
    long text
    long text
    """,
                external("uuid:e3e70682-c209-4cac-a29f-6fbed82c07cd.txt"),
            ]
        )

## Storage Protocols

### UUID

The `uuid:` storage protocol is the default protocol and stores the external files relative to the test files in `__inline_snapshot__/<test_file>/<qualname>/<uuid>.suffix`.

- Files are co-located with the file/function where your value is used.
- The use of a UUID allows inline-snapshot to find the external file even if file or function names of a test function have changed.
- Distinguishing multiple external snapshots in the same function remains challenging.

Note

Using the same external uuid multiple times like this is not supported:

    from inline_snapshot import external

    def test_a():
        assert "test" == external("uuid:e3e70682-c209-4cac-a29f-6fbed82c07cd.txt")

    def test_b():
        assert "test" == external("uuid:e3e70682-c209-4cac-a29f-6fbed82c07cd.txt")

This can happen when you copy tests and change them for another use case. inline-snapshot notifies you in this case, and you should change one external back to `external("uuid:")` and create new external snapshots.

The correct way to do use the same external in different tests is to assign the external to a variable and reuse this variable.

    from inline_snapshot import external

    expected = external("uuid:e3e70682-c209-4cac-a29f-6fbed82c07cd.txt")

    def test_a():
        assert "test" == expected

    def test_b():
        assert "test" == expected

### Hash

The `hash:` storage can be used to store snapshot files based on the hash of their content. This was the first storage protocol supported by inline-snapshot and can still be useful in some cases. It also preserves backward compatibility with older inline-snapshot versions.

The external data is by default stored inside `<pytest_config_dir>/.inline-snapshot/external`, where `<pytest_config_dir>` is replaced by the directory containing the Pytest configuration file, if any. To store data in a different location, set the `storage-dir` option in pyproject.toml.

- Value changes cause source code changes because the hash changes.
- GitHub/GitLab web UIs cannot be used to view the diffs, because the filename changes.

## Formats

inline-snapshot supports several built-in formats for external snapshots. The format used is determined by the given data type: bytes are stored in a `.bin` file, and strings are stored in a `.txt` file by default. More complex data types are stored in a `.json` file.

Suffix | Priority | Description
--- | --- | ---
`.bin` | 0 | Stores bytes in `.bin` files and shows them as a hexdump.
`.txt` | 0 | Stores strings in `.txt` files.
`.json` | -10 | Stores the data with `json.dump()`.

Custom formats are also supported.

You can also use format aliases if you want to use specific file suffixes that have the same handling as existing formats. You must specify the suffix in this case.

    from inline_snapshot import register_format_alias, external

    register_format_alias(".html", ".txt")

    def test():
        assert "<html></html>" == external(".html")

inline-snapshot uses the given suffix to create an external snapshot.

    from inline_snapshot import register_format_alias, external

    register_format_alias(".html", ".txt")

    def test():
        assert "<html></html>" == external(
            "uuid:e3e70682-c209-4cac-a29f-6fbed82c07cd.html"
        )

Breaking Change

`register_format_alias()` is required if you used `outsource(value, suffix="html")` and are migrating from inline-snapshot prior to version 0.24.

## pytest Options

It interacts with the following `--inline-snapshot` flags:

- `create`: Creates new external files.
- `fix`: Changes external files.
- `trim`: Removes all snapshots from the storage that are not referenced with `external(...)` in the code.