Summary#
When a brief asks for an exam CLI, a command that takes a JSON test case, or a way to check the app before its
screens exist, you don't need a script. Write one function that takes the case and returns the result, and the
command is osy run:
osy run Exam --arg-file c=case.json --output jsonIt prints the function's result as JSON on stdout, and nothing else goes there. A failure prints a JSON error on
stderr and exits non-zero. If the project was never compiled, or has changed since it last was, osy run compiles
it first.
Signature#
osy run <function> [path] [--args-file <path|->] [--args-stdin] [--arg-file NAME=<path|->] [--arg NAME=VALUE]
[--output json] [--no-compile] [--as <login> --password <pw>]Description#
What does the function look like?#
Write a function that takes one case object and returns one result object. Model both as classes, so each field has a name and a type. The function is ordinary Osy#: your tests call it, and so can a page.
class ExamCase {
public string Question = "";
public List<int> Numbers = [];
}
class ExamResult {
public int Total;
public string Verdict = "";
}
ExamResult Exam(ExamCase c) {
var total = 0;
foreach (var n in c.Numbers) { total = total + n; }
return new ExamResult { Total = total, Verdict = total > 10 ? "big" : "small" };
}A grader's case file is the case itself:
{ "question": "add them up", "numbers": [4, 5, 6] }Field names match without regard to case, so numbers binds Numbers.
How does the case get in?#
There are two shapes. Pick the one that fits the file you are given.
| the file holds | flag | binds |
|---|---|---|
| one value, such as a test case | --arg-file c=case.json | the whole document to the parameter c |
| every argument, one property per parameter | --args-file args.json | each property to the parameter it names, like --args-json |
Use - in place of a path to read standard input. --args-stdin means --args-file -.
osy run Exam --arg-file c=case.json --output json # the case, from a file
osy run Exam --arg-file c=- --output json < case.json # the case, piped in
osy run Exam --args-file args.json --output json # args.json is {"c": {…}}
cat args.json | osy run Exam --args-stdin --output jsonYou can layer them. One whole-arguments source (--args-json, --args-file or --args-stdin) goes first, each
--arg-file goes on top of it, and each --arg goes on top of those. Standard input can only be read once, so if two
flags ask for it, osy run refuses. It also refuses, rather than waiting, when a flag asks for standard input and
nothing is piped in.
What comes out?#
With --output json, the result is printed on stdout as one line of JSON and the exit code is 0:
$ osy run Exam --arg-file c=case.json --output json
{"total":15,"verdict":"big"}A number comes out as 42, a string as "hola", a list as […], and a returned row as its fields with its id. A
function that returns nothing prints null. Nothing else goes to stdout: the platform starting, a compile on demand,
and any notes are all written to stderr. A script can read stdout with a single JSON parse.
--json is different. It prints the whole answer (success, output, result, error, code and ranAs) as one
document. Use one flag or the other, not both.
What does a failure look like?#
When the function throws or is refused, stdout stays empty, stderr gets one line of JSON, and the exit code is not zero:
$ osy run Exam --arg-file c=case.json --output json
{"error":{"code":"denied","message":"You do not have permission to create a note. — …"}}
$ echo $?
1Branch on code. The message is written for a person and may change. The codes are stable:
| code | means | what to do |
|---|---|---|
invalid | the function refused the input (a validation error, a throw of a validation kind) | the case is wrong, or the rule is |
denied | the app's security refused the caller (a rule, a policy, [Authorize]) | run as someone allowed: --as <login> --password <pw> |
not-found | something the function looked up is not there | check the ids in the case |
conflict | the change clashes with the data as it is | re-read and retry |
unavailable | a service the function called did not answer | try again later |
too-many-attempts | sign-in attempts are being limited | wait, then try again |
fault | the function failed in a way it did not declare (a bug, or a plain throw) | read the message, fix the function |
function-not-found | no function has that name | check the spelling; the message lists what can run |
function-not-runnable | the name is a method, a test, a constructor or a workflow step | call a top-level function |
function-ambiguous | two kits declare that name | name it in full |
sign-in-refused | --as did not sign in | check the login, password and --code |
bad-arguments | the flags or a case file could not be read (missing file, not JSON, nothing piped) | the message names the flag |
compile-failed | the compile on demand found errors (they are on stderr above the error line) | fix them |
not-a-project | there is no app.osy here | run it in the project's folder, or pass its path |
platform-unavailable | the local platform could not be started | the message says why |
platform-unreachable | the local platform stopped answering (exit code 2) | start it again: osy launch |
Does it need compiling first?#
No. osy run compiles the project first if the local platform has never compiled it, or if the source has changed
since it last did. It says so on stderr:
$ osy run Exam --arg-file c=case.json --output json
The source changed since the last compile — compiling it first (`osy compile`).
{"total":15,"verdict":"big"}osy seed <name> does the same, so on a fresh clone osy seed ExamWorld followed by osy run Exam … works with no
other step. --no-compile runs whatever the platform has now.
Prove it with a test as well#
The command is for the grader. Your own check is a test that calls the same function, which osy check runs with
everything else:
[Test]
void a_case_adds_its_numbers() {
var result = Exam(new ExamCase { Question = "add them up", Numbers = [4, 5, 6] });
Assert.Equal(15, result.Total);
Assert.Equal("big", result.Verdict);
}If the brief says to pass the exam cases before building screens, build this function and its command first, and run the command on a real case before you start on any page.
See also#
Running a function — osy run in full: who it runs as, entity arguments, --json.
Compiling your app — what the compile on demand runs.
[Test] / [TestFixture] — writing the test that calls the same function.