There is a confusing topic regarding scripts.
Can you share the key differences between running “daml test” vs “daml test-scripts” vs “daml script” in respect to actions done on DAR file on a ledger (or sandbox)
1 Like
Hi @liav and welcome to the forum!
Let me go through the different options:
-
daml scriptruns an individual script in your DAR specified via--script-nameagainst the ledger specified via--ledger-hostand --ledger-port`. -
daml test-scriptruns all scripts in a DAR against the ledger specified via--ledger-hostand ``-ledger-port` and can spin up a ledger for you if you don’t specify one. -
daml testis the odd one out here. It runs all scripts in a project (instead of taking a DAR, it compiles the files for you) and it runs each script in its own isolated testing ledger (daml test-scriptdoes not provide isolation between scripts but you can often achieve it by allocating fresh parties) via the script service. This is the same dummy ledger also used in Daml Studio. The script service is deliberately only a testing ledger which allows it to behave differently from “real” ledgers. Specifically, it doesn’t have to worry about leaking information and can therefore provide much more explicit error messages to help you figure out what is wrong. it is usually also significantly faster than running the scripts viadaml test-script(although the fact that it compiles the files first can skew that the other way around). It also provides some limited coverage information and other useful goodies.
So when do you use what?
daml test is what I recommend to use in CI setups.
daml script is what you use for ledger initialization and similar scenarios where you want to run an individual script against a running ledger.
daml test-script is rarely needed imho. It is nice if you want to test the actual behavior of a ledger rather than relying on the script service but in most cases you can safely ignore it.
Thanks Moritz for your prompt response. It’s fairly confusing.
So running a “daml test” runs all scripts in the project or given DAR file and runs them in a special in-memory emulator?
“daml test-script” takes a DAR file, a script identifier and a ledger connection and runs a script against the ledger?
“daml script” runs the script on a special in-memory ledger emulator?
When wishing to simply open a DAML file with a script in the IDE it means that you start a sandbox and run all scripts in a given dar file against the sandbox?
Let me try to make a table which hopefully makes the differences clearer:
| Source or DAR | Runs all scripts | Script service or real ledger | |
|---|---|---|---|
| daml script | DAR | No | Real ledger |
| daml test-script | DAR | Yes | Real ledger |
| daml test | Source | Yes | Script service |
| Daml Studio | Source | Yes but only for open files | Script service |
Explanations:
Source or DAR: DAR means it accepts a DAR, i.e., compiled Daml source code. Source means it takes Daml source files and compiles them before running the scripts.
Runs all scripts: This is about whether you select a specific script to run or whether they are all run.
Script service vs real ledger: The script service is the thing used in Daml studio and daml test. You can only run Daml scripts in there, it does not provide a ledger API or other things you expect from a real ledger. However in return you get better error messages, performance & isolation between scripts. Real ledger here refers to anything that exposes the ledger API. This includes the in-memory sandbox which is a compliant ledge (and is therefore very different from the script service).
So daml test is the CLI version of what daml studio uses. daml script and daml test-script both run against actual ledgers on the other hand with the main difference being that one runs an individual script while the other runs all scripts.
4 Likes
Great explanation here, was just wondering this myself the other day. Currently trying to find out the best way to set up testing Daml and CI.
In 2.0, we simplified this a fair bit. There is now only daml test which behaves as it did before and daml script. daml test-script has been removed in favor of daml script --all which runs all scripts in a given DAR.
1 Like