From 79b2abf3f365077098f53809af99dab37dd5e020 Mon Sep 17 00:00:00 2001 From: Yves Chevallier Date: Wed, 9 Oct 2024 17:21:56 +0200 Subject: [PATCH] Update documentation --- baygon/__main__.py | 33 +++++++++------- baygon/score.py | 2 +- docs/docs/.vuepress/config.ts | 1 + docs/docs/guide/README.md | 14 +++++-- docs/docs/guide/score.md | 74 +++++++++++++++++++++++++++++++++++ docs/docs/guide/syntax.md | 19 --------- 6 files changed, 105 insertions(+), 38 deletions(-) create mode 100644 docs/docs/guide/score.md diff --git a/baygon/__main__.py b/baygon/__main__.py index 48360d6..f5502da 100644 --- a/baygon/__main__.py +++ b/baygon/__main__.py @@ -171,31 +171,34 @@ def _traverse_group(self, tests): self.points_total += test.points if issues is None: # Skipped click.secho(" SKIPPED", fg="yellow") - click.secho( - "".join([f" $ {cmd}\n" for cmd in self.ran_commands]), - fg="blue", - dim=True, - ) + if self.ran_commands: + click.secho( + "".join([f" $ {cmd}\n" for cmd in self.ran_commands]), + fg="blue", + dim=True, + ) self.skipped += 1 continue display_pad(self.align_column - test_name_length(test)) if not issues: self.successes += 1 click.secho(" PASSED", fg="green") - click.secho( - "".join([f" $ {cmd}\n" for cmd in self.ran_commands]), - fg="blue", - dim=True, - ) + if self.ran_commands: + click.secho( + "".join([f" $ {cmd}\n" for cmd in self.ran_commands]), + fg="blue", + dim=True, + ) self.points_earned += test.points else: self.failures += 1 click.secho(" FAILED", fg="red", bold=True) - click.secho( - "".join([f" $ {cmd}\n" for cmd in self.ran_commands]), - fg="blue", - dim=True, - ) + if self.ran_commands: + click.secho( + "".join([f" $ {cmd}\n" for cmd in self.ran_commands]), + fg="blue", + dim=True, + ) for issue in issues: click.secho( " " * len(test.id) + "- " + str(issue), fg="magenta" diff --git a/baygon/score.py b/baygon/score.py index 0498b8f..0348ede 100644 --- a/baygon/score.py +++ b/baygon/score.py @@ -2,7 +2,7 @@ Used in academic. """ -from decimal import Decimal, getcontext, ROUND_HALF_UP +from decimal import Decimal, getcontext, ROUND_HALF_UP, ROUND_DOWN def float_or_int(value): diff --git a/docs/docs/.vuepress/config.ts b/docs/docs/.vuepress/config.ts index df47178..103f8ee 100644 --- a/docs/docs/.vuepress/config.ts +++ b/docs/docs/.vuepress/config.ts @@ -26,6 +26,7 @@ export default defineUserConfig({ { text: 'Getting Started', link: '/guide/' }, { text: 'Syntax', link: '/guide/syntax.md' }, { text: 'Scripting', link: '/guide/scripting.md' }, + { text: 'Academic Use', link: '/guide/score.md' }, { text: 'Advanced', link: '/guide/advanced.md' }, ], }, diff --git a/docs/docs/guide/README.md b/docs/docs/guide/README.md index 536d5cf..16bd743 100644 --- a/docs/docs/guide/README.md +++ b/docs/docs/guide/README.md @@ -1,9 +1,13 @@ -# Introduction +# What is Baygon? -Baygon is a minimalistic test framework for any types of executables. It provides a simple way of testing code with a [JSON](https://en.wikipedia.org/wiki/JSON) or a [YAML](https://en.wikipedia.org/wiki/YAML) description of tests. +**Baygon** is a minimalistic test framework for any types of executables. It provides a simple way of testing code with a [JSON](https://en.wikipedia.org/wiki/JSON) or a [YAML](https://en.wikipedia.org/wiki/YAML) description of tests. + +It is mainly designed for simple tests in academic environments, but it can be used for any kind of tests. + +Points can be assigned to tests, group of tests or automatically distributed based on the number of tests. The total earned points can be used to calculate the final assignment grade. ::: warning -Baygon v1 is currently in `beta` stage. It's ready to be used for building functional tests, but the config and API are not stable enough, which is likely to have breaking changes between minor releases. +Baygon is currently in `beta` stage. It's ready to be used for building functional tests, but the config and API are not stable enough, which is likely to have breaking changes between minor releases. ::: ## How it works @@ -14,6 +18,10 @@ Based on the description file, a `TestSuite` is built. A `TestSuite` is a collec By default Baygon will run all the tests in the description file. +## What a strange name! + +Baygon is a brand of insecticide popularized in the 80s by the commercial ads featuring Michel Leeb. The name was chosen because it's a simple and short name that is easy to remember. And Baygon is meant to kill bugs in your code! + ## Get started Let's say you have a C program you want to test: diff --git a/docs/docs/guide/score.md b/docs/docs/guide/score.md new file mode 100644 index 0000000..9106b8d --- /dev/null +++ b/docs/docs/guide/score.md @@ -0,0 +1,74 @@ +# Academic Assignment + +Baygon is well designed to handle academic assignments. You can specify the points for each test, group of tests or at the top level. + +The configuration keys you can use are: + +**`points`** + +The total points that can be earned from the whole suite, group of tests or test. + +**`weight`** + +The weight of a test or group of tests. The weight is used to calculate the available points. A default `weight` value of `10` is used but you can set it to any value you want according to your needs. + +**`min-points`** + +When using weights, for instance if you have a group of test awarded 2 points shared in three tests of equally weights, each test will be awarded 0.666...points. The `min-points` key allows you to set a minimum value for the points. In this case, if you set `min-points` to `1`, each test will be awarded 1 point. Typical values are `1`, `0.5`, `0.25` or `0.1`. + +Baygon will automatically figure out how to assign points to each test based on your entries. Some rules apply: + +1. Without any other information each successfull test is awarded 1 points. +2. If a total number of points is specified at any level, the points are distributed equally among the subtests. +3. Weights can be used influence the distribution of points. The default weight is 10. + +To give you some examples we will simplify the configuration files. + +## Equally distributed points + +By default we know that `min-points` is 0.1 and with equal `weight` on each test, the points are distributed equally. + +```yaml +version: 1 +points: 10 +tests: + - name: Test 1 # 3.4 + - name: Test 2 # 3.3 + - name: Test 3 # 3.3 +``` + +## Weighted points distribution + +This time we have two subgroups of tests. The first group has a weight of 5 and the second group has a weight of 10. The total points are 10. + +```yaml +version: 1 +points: 12 +tests: + - name: Group 1 # 4 + weight: 5 + tests: + - name: Test 1 # 2 + - name: Test 2 # 2 + - name: Group 2 # 8 + weight: 10 + tests: + - name: Test 3 # 4 + - name: Test 4 # 4 +``` + +## Using the result + +The number of points is given on the output it has the form of: + +```text +Points: 4/10 +``` + +Alternatively you may want to use the report feature to generate a report in JSON or YAML format. The report will contain the points for each test and group of tests. + +```console +baygon --report=report.json +``` + +This report could be used by a grading system to automatically assign grades to students. diff --git a/docs/docs/guide/syntax.md b/docs/docs/guide/syntax.md index 2f4fcaf..42efef3 100644 --- a/docs/docs/guide/syntax.md +++ b/docs/docs/guide/syntax.md @@ -205,22 +205,3 @@ tests: - regex: f(oo|aa|uu) # Must match - equals: foobar ``` - -## Given Points - -In the case Baygon is used in an academic context, you can assign points to each test. The following assigns 10 points to the first test and 5 to the second: - -```yaml -version: 1 -tests: - - points: 10 - args: [1, 2] - stdout: 3 - - points: 5 - args: [1, 2] - stdout: 3 -``` - -Points can be given at different levels: - -1. At the top level, all tests will have the same points.