dazl

dazl.testing

This module provides testing utilities for writing simple tests around a Daml ledger running with a local sandbox. Call the sandbox() function which returns an object that controls the lifecycle of a sandbox process.

Starting up a Daml sandbox and uploading relevant DARs takes long enough (more than one second) that you’ll probably want to start a single sandbox to run for the duration of the tests. In order to achieve good test isolation, though, you don’t necessarily want to use the same parties for each test, you should also use connect_with_new_party(), which will automatically allocate and return a new party on every invocation.

Example:

# this assumes a daml.yaml file exists in the same location as your Python code;
# you may need to adjust this location for your own project
project_root = path.dirname(__file__)

async def main():
   async with sandbox(project_root=) as sb:
      async with connect_with_new_party(url=sb.url) as p:
         logging.info("Connecting as party: %s", p.party)
         await p.conn.create("Some:Asset", {"owner": p.party, "amount": 1000})

# Python 3.7+ only
asyncio.run(main())
dazl.testing.sandbox()
Parameters

  • project_root (str or os.PathLike) – The root project directory for your Daml project. If supplied, the DAR from this project is automatically uploaded like daml start does. If None, an empty sandbox is started and you must supply your own DAR.

  • version (str) – The Daml Connect version to use.

  • timeout (datetime.timedelta) – The amount of time to wait for a Sandbox to start before giving up. The defualt is 10 seconds.

Launch a sandbox running on a randomized port, optionally using the DARs as specified by a local Daml project.

The resulting object can be used as a context manager _or_ an asynchronous context manager.

dazl.testing.connect_with_new_party(*, party_count=1, url=None, read_as=None, act_as=None, admin=False, ledger_id=None, dar=None, identifier_hint=None, display_name=None) → dazl.testing.connect.ConnectWithNewParty

A helper function for connecting to a ledger as a brand new party. This isn’t normally useful outside of tests, where having creating new parties for each test helps keep test data isolated.

Like the dazl.ledger.connect() function, all parameters are optional, and if unspecified, get their default values from the environment.

This function can NOT be used with ledgers that require authentication since it has no way to ask a token granter for an appropriate token for the newly allocated party.

Parameters

  • url (str) – The URL of the ledger to connect to. This ledger MUST NOT require authentication!

  • read_as (str or Collection[str]) – Extra parties to for which read-as access should be granted.

  • act_as – Extra parties to for which act-as access should be granted. The created party is added to this list.

  • admin (bool) – True if the created connection should have “admin” rights; otherwise False. Note that in order to allocate parties, an initial connection with admin rights is ALWAYS created, and the value of this call only affects the returned connection.

  • ledger_id (str) – The ledger ID to connect to. As with the connect api, if the target is the gRPC Ledger API, then supplying this field is optional, and with an HTTP JSON API server, this field must be supplied.

  • dar (str or bytes or PathLike or BinaryIO) – A path to a file, the contents of the file (as bytes), or a byte buffer that point to a DAR that should also be uploaded.

  • party_count (int) – The number of parties (and connections) to create.

  • identifier_hint (str) – A hint to the backing participant. Note that the Daml ledger is free to ignore this hint entirely. If party_count is greater than 1, then

  • display_name – A human-readable name that corresponds to the allocated Party.

Returns

An asynchronous context manager that returns one or more ConnectionWithParty objects.