search

Azure / simdem

Tool for Simulating Demo's, delivering Tutorials and using documentation as tests.
MIT License
34 stars 17 forks source link

Document use of Validation section #100

Open SorraTheOrc opened 6 years ago

SorraTheOrc commented 6 years ago

Validation sections are both a normal part of a document and a way to test if a prerequisite is run. This issue is about their use as a normal part of a document. In this mode the validation section should be run. Consider the example below which should output and/or test the value of UNIQUE_FILENAME when run in any mode.

ASIDE: I've written this example as both documentation and test script... where should it live?

How to use Environment Variables to Configure SimDem Scripts

It can be convenient to have a SimDem script that creates a number of environment variables for use in other scripts. This script can then be used as a prerequisite to ensure that you have a consistent environment on each execution. To set an environment variable use a command like the following:

MY_VARIABLE="My value"

You can use bash commands to create unique strings too:

UNIQUE_FILENAME=my_filename_$(date +%Y-%m-%d-%H)

If you want to avoid overwriting values provided by the SimDem user, you can easily do so with a value check:

if [ -z "$ANOTHER_UNIQUE_FILENAME" ]; then $ANOTHER_UNIQUE_FILENAME = my_filename_$(date +%Y-%m-%d-%H); fi

Validation

A validation section is useful in two ways. It can be used to ensure we output the final results when executing in a tutorial/demo environment and it can be used to test whether a prerequisite file needs to be run. For example:

if [ -z "$UNIQUE_FILENAME" ]; echo "We need to provide or generate a unique filename"; else "UNIQUE_FILENAME=$UNIQUE_FILENAME"; fi

Results:

UNIQUE_FILENAME=my_filename_yyyy-mm-dd-hh
lastcoolnameleft commented 6 years ago

To answer your aside question: I've put all examples here. We can change it later, but for now it works. https://github.com/Azure/simdem/tree/simdem2/examples

Regarding implementing validation:

SorraTheOrc commented 6 years ago

You are looking at it the wrong way around. The validation section is just a normal part of the document, with one exception (see below). Just treat it as any other section in all modes.

The one exception is to establish whether we need to run a prerequisite or not. Here the validation section allows us to prevent the need to run a prerequisite multiple times when it is defined as a prerequisite in multiple documents. If all validation tests pass, prerequisite has already been run.

Get Outlook for Androidhttps://aka.ms/ghei36

From: Tommy Falgout notifications@github.com Sent: Saturday, March 3, 2018 3:16:06 PM To: Azure/simdem Cc: Ross Gardler; Author Subject: Re: [Azure/simdem] SimDem2: Validation section not run (#100)

To answer your aside question: I've put all examples here. We can change it later, but for now it works. https://github.com/Azure/simdem/tree/simdem2/exampleshttps://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FAzure%2Fsimdem%2Ftree%2Fsimdem2%2Fexamples&data=04%7C01%7Cross.gardler%40microsoft.com%7Cf5b3cf1f58084c0cddc008d5815cbf21%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636557157704843685%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwifQ%3D%3D%7C-1&sdata=qcxk8wgdozuBxYm0qkEpiBhnI7ADyozJI9wqwtnn%2B0c%3D&reserved=0

Regarding implementing validation:

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHubhttps://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FAzure%2Fsimdem%2Fissues%2F100%23issuecomment-370187609&data=04%7C01%7Cross.gardler%40microsoft.com%7Cf5b3cf1f58084c0cddc008d5815cbf21%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636557157704843685%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwifQ%3D%3D%7C-1&sdata=%2FSgEhuBVtRqQp1IPdJoby74Nddn6zkw4bevmgLIU8S8%3D&reserved=0, or mute the threadhttps://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FAAPRgKJ7wQZNQ38bFzY9UO0VidWbv4brks5tayQ2gaJpZM4SRPx3&data=04%7C01%7Cross.gardler%40microsoft.com%7Cf5b3cf1f58084c0cddc008d5815cbf21%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636557157704843685%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwifQ%3D%3D%7C-1&sdata=EiUCpnKiYNj60be5EL%2BzSuWGN1%2FPPG3ZhDPCRjx66rs%3D&reserved=0.

lastcoolnameleft commented 6 years ago

Ah, ok. I was thinking that Validation is a section that validates the entire document completed successfully.

Let me mull over this change as I will probably need to pass the "mode" variable into the parser so that it only treats "# Validation" special if it's a prerequisite.

lastcoolnameleft commented 6 years ago

Correction: I will need to pass "is_prerequisite" into the parser, so that it knows if it should handle the validation section. Otherwise, it should just treat it as a regular body section.

lastcoolnameleft commented 6 years ago

@rgardler Can you validate it works according to spec? I've added the following commit to the simdem2 branch which should fix the issue.

https://github.com/Azure/simdem/commit/c1c7f99121ccabdeeea62eb04398754f440b631c

SorraTheOrc commented 6 years ago

Confirmed... working as expected, thanks. Leaving this open (but dropping priority) as a reminder for me to move the example into docs.