testing.rst

Testing

python-zfs uses pytest for testing. The test code can be found in the tests-subdirectory of the source tree.

Preparation

Usually, when running the test suite locally in your shell, it is advised to use a virtual environment. Which one to use is up to the reader. The authors use the venv module. The requirements can be found in the file requirements_develop.txt or by installing the module with tests.

$ python3 -m venv venv
$ source venv/bin/activate
(venv) $ pip install -e .[tests]

Running the tests

Then run the tests using pytest: pytest -v --cov. The test suite will be expanded in the future.

Creating local pools and datasets

Pool with most vdev types

To have a pool with most of the supported vdev types, create a pool from a set of files. The following sequence creates a set of 64MB files (the minimum size ZFS accepts). The new pool is not really usable for storing data, mostly because it is based on sparse files and ZFS does not like that. But it should be usable for most of the actions that one wants to perform on it for testing purposes.

mkdir /tmp/z
for i in {1..12}; do truncate -s 64M /tmp/z/vol$i; done
sudo zpool create testpool \
     raidz /tmp/z/vol1 /tmp/z/vol2 /tmp/z/vol3 \
     raidz /tmp/z/vol4 /tmp/z/vol5 /tmp/z/vol6 \
     log mirror /tmp/z/vol7 /tmp/z/vol8 \
     cache /tmp/z/vol9 /tmp/z/vol10 \
     spare /tmp/z/vol11 /tmp/z/vol12

The new pool should now look like this:

pool: testpool

state: ONLINE

scan: none requested

config:

NAME STATE READ WRITE CKSUM testpool ONLINE 0 0 0 raidz1-0 ONLINE 0 0 0 /tmp/z/vol1 ONLINE 0 0 0 /tmp/z/vol2 ONLINE 0 0 0 /tmp/z/vol3 ONLINE 0 0 0 raidz1-1 ONLINE 0 0 0 /tmp/z/vol4 ONLINE 0 0 0 /tmp/z/vol5 ONLINE 0 0 0 /tmp/z/vol6 ONLINE 0 0 0 logs mirror-2 ONLINE 0 0 0 /tmp/z/vol7 ONLINE 0 0 0 /tmp/z/vol8 ONLINE 0 0 0 cache /tmp/z/vol9 ONLINE 0 0 0 /tmp/z/vol10 ONLINE 0 0 0 spares /tmp/z/vol11 AVAIL /tmp/z/vol12 AVAIL

errors: No known data errors

For reference, when getting a listing of the pools content, the output should look like this (converted to json using json.dumps() and pretty-printed for readability:

{
  "testpool": {
    "drives": [
      {
        "type": "raidz1",
        "health": "ONLINE",
        "size": 184549376,
        "alloc": 88064,
        "free": 184461312,
        "frag": 0,
        "cap": 0,
        "members": [
          {
            "name": "/tmp/z/vol1",
            "health": "ONLINE"
          },
          {
            "name": "/tmp/z/vol2",
            "health": "ONLINE"
          },
          {
            "name": "/tmp/z/vol3",
            "health": "ONLINE"
          }
        ]
      },
      {
        "type": "raidz1",
        "health": "ONLINE",
        "size": 184549376,
        "alloc": 152576,
        "free": 184396800,
        "frag": 0,
        "cap": 0,
        "members": [
          {
            "name": "/tmp/z/vol4",
            "health": "ONLINE"
          },
          {
            "name": "/tmp/z/vol5",
            "health": "ONLINE"
          },
          {
            "name": "/tmp/z/vol6",
            "health": "ONLINE"
          }
        ]
      }
    ],
    "log": [
      {
        "type": "mirror",
        "size": 50331648,
        "alloc": 0,
        "free": 50331648,
        "frag": 0,
        "cap": 0,
        "members": [
          {
            "name": "/tmp/z/vol7",
            "health": "ONLINE"
          },
          {
            "name": "/tmp/z/vol8",
            "health": "ONLINE"
          }
        ]
      }
    ],
    "cache": [
      {
        "type": "none",
        "members": [
          {
            "name": "/tmp/z/vol9",
            "health": "ONLINE"
          },
          {
            "name": "/tmp/z/vol10",
            "health": "ONLINE"
          }
        ]
      }
    ],
    "spare": [
      {
        "type": "none",
        "members": [
          {
            "name": "/tmp/z/vol11",
            "health": "AVAIL"
          },
          {
            "name": "/tmp/z/vol12",
            "health": "AVAIL"
          }
        ]
      }
    ],
    "size": 369098752,
    "alloc": 240640,
    "free": 368858112,
    "chkpoint": null,
    "expandsz": null,
    "frag": 0,
    "cap": 0,
    "dedup": 1,
    "health": "ONLINE",
    "altroot": null
  }
}