{"id":20623895,"url":"https://github.com/cezarypiatek/nscenario","last_synced_at":"2025-04-09T17:26:25.278Z","repository":{"id":42502398,"uuid":"367110027","full_name":"cezarypiatek/NScenario","owner":"cezarypiatek","description":"Dead simple library for annotating steps of test case scenarios.","archived":false,"fork":false,"pushed_at":"2024-11-06T21:35:44.000Z","size":485,"stargazers_count":67,"open_issues_count":1,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-02T15:08:57.365Z","etag":null,"topics":["component-testing","dotnet","integration-testing","testcase","testing"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cezarypiatek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-13T16:32:17.000Z","updated_at":"2024-11-06T21:33:29.000Z","dependencies_parsed_at":"2024-11-16T12:29:21.924Z","dependency_job_id":"2f0c1ed2-228b-44fe-ad0b-673d23d31571","html_url":"https://github.com/cezarypiatek/NScenario","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cezarypiatek%2FNScenario","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cezarypiatek%2FNScenario/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cezarypiatek%2FNScenario/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cezarypiatek%2FNScenario/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cezarypiatek","download_url":"https://codeload.github.com/cezarypiatek/NScenario/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248076241,"owners_count":21043734,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["component-testing","dotnet","integration-testing","testcase","testing"],"created_at":"2024-11-16T12:28:51.899Z","updated_at":"2025-04-09T17:26:25.259Z","avatar_url":"https://github.com/cezarypiatek.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NScenario\n[![NuGet](https://img.shields.io/nuget/vpre/NScenario.svg)](https://www.nuget.org/packages/NScenario/)\n\nDead simple, test framework independent, without any magic, a library for annotating steps of test case scenarios.\nPlease read [Readable and clear tests for ASP.NET Core services](https://cezarypiatek.github.io/post/component-tests-scenarios/) article for better exaplanation and example use cases.\n\nThis library was discussed during [ASP.NET Community Standup 2021-08-24](https://www.youtube.com/watch?v=Zw11P2z_ptc\u0026t=831s)\n\n## How to install\n`NScenario` is distribute as a nuget package [NScenario](https://www.nuget.org/packages/NScenario/)\n\n\n## How to use it\n\nJust create an instance of `NScenario.TestScenario` class and start annotating your test steps by wrapping it in `Step` method call.\nYou can create `TestScenario` instance manually by providing a desired composition of `IScenarioStepExecutor` instances or simply by calling `TestScenarioFactory.Default()` method.\n\nExample test can look as follows:\n\n```cs\n[Test]\npublic async Task should_activate_community_supporter_license_when_eligible()\n{\n    using var driver = await LicenseServerTestDriver.Create();\n    var scenario = TestScenarioFactory.Default();\n\n    var activationData = new\n    {\n        email = \"abs@test.com\",\n        licenseKey = \"WTKP4-66NL5-HMKQW-GFSCZ\"\n    };\n\n    await scenario.Step(\"Import supporters\", async () =\u003e\n    {\n        await driver.ImportSupporters(\"BuyMeCoffee\", new[] { \"john@done.com\", \"jane@done.com\", activationData.email });\n    });\n\n    await scenario.Step(\"Register purchase for supporter email\", async () =\u003e\n    {\n        await driver.RegisterPurchaseWithCoupon(\"Extension for VS2017\", activationData.email, activationData.licenseKey, \"OssSupporter\");\n    });\n\n    await scenario.Step(\"Activate the license with supporter email\", async () =\u003e\n    {\n        var activationResult = await scenario.Step(\"Call active license endpoint\" () =\u003e \n        {\n            return await driver.ActivateLicense(activationData.email, activationData.licenseKey);\n        });\n        \n        await scenario.Step(\"Verify that license activated properly\", () =\u003e\n        {\n            Assert.AreEqual(true, activationResult.Activated);\n            Assert.AreEqual(\"Unlimited\", activationResult.Capabilities[\"VsVersion\"]);\n        });\n    });\n}\n```\n\nConsole output\n\n```plaintext\nSCENARIO: should activate community supporter license when eligible\n\nSTEP 1: Import supporters\nSTEP 2: Register purchase for supporter email\nSTEP 3: Activate the license with supporter email\n    STEP 3.1: Call active license endpoint\n    STEP 3.2: Verify that license activated properly\n```\n\nBenefits:\n- Obvious way to enforce step descriptions\n- More readable test scenario\n- Sub-scopes for repeatable steps\n- Readable output that facilitates broken scenario investigation\n\n## Console output\nSome test runners are hijacking console output and provide a custom stream for logging. By default `NScenario` is writing scenario description to the console, but this can be overridden by providing a custom `TextWriter` stream to `TestScenarioFactory.Default()` method. \n\n### Example setup for `NUnit`\n\n```cs\npublic class MyTests\n{\n    [Test]\n    public void sample_test_case()\n    {\n        var scenario = TestScenarioFactory.Default(TestContext.Progress);    \n    }\n}\n```\n\n### Example setup for `XUnit`\n\n```cs\n\npublic class XUnitOutputAdapter : TextWriter\n{\n    private readonly ITestOutputHelper _output;\n    public XUnitOutputAdapter(ITestOutputHelper output) =\u003e _output = output;\n    public override void WriteLine(string? value) =\u003e _output.WriteLine(value);\n    public override Encoding Encoding { get; }\n}\n\npublic class MyTests\n{\n    private readonly ITestOutputHelper _output;\n    public MyTests(ITestOutputHelper output) =\u003e this._output = output;\n    \n    [Fact]\n    public void sample_test_case()\n    {\n        var scenario = TestScenarioFactory.Default(new XUnitOutputAdapter(_output));\n    }\n}\n```\n\nMore info about [capturing console output in XUnit](https://xunit.net/docs/capturing-output)\n\n## Global setup for scenario output\nTest scenario output can be configured globally by setting `TestScenarioFactory.DefaultScenarioOutputWriter`.\n\n### Example using [Module initializer](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-9.0/module-initializers) :\n\n```cs\nusing NScenario.OutputWriters;\nusing NScenario.StepExecutors;\n\npublic static class GlobalSetup\n{\n    [System.Runtime.CompilerServices.ModuleInitializer]\n    public static void Setup()\n    {\n        TestScenarioFactory.DefaultScenarioOutputWriter = new StreamScenarioOutputWriter(TestContext.Progress);\n    }\n}\n```\n\n### Example using [SetUpFixture](https://docs.nunit.org/articles/nunit/writing-tests/attributes/setupfixture.html) for `NUnit`\n\nYou should put that code under the default namespace:\n\n```cs\nusing NScenario.OutputWriters;\nusing NScenario.StepExecutors;\nusing NUnit.Framework;\n\n[SetUpFixture]\npublic class AllTestsSetup\n{\n    [OneTimeSetUp]\n    public void GlobalSetup()\n    {\n        TestScenarioFactory.DefaultScenarioOutputWriter = new StreamScenarioOutputWriter(TestContext.Progress);\n    }\n}\n```\n\n## Exporting scenario transcription\n\nYou save the test scenario transcription as Markdown (with option to export as HTML) using `MarkdownFormatterOutputWriter`.\n\nSample setup with exporting scenario transcription to a file:\n\n```cs\nusing NScenario.OutputWriters;\nusing NScenario.StepExecutors;\nusing NUnit.Framework;\n\n[SetUpFixture]\npublic class AllTestsSetup\n{\n    private readonly MarkdownFormatterOutputWriter _reportWriter = new (title: \"Sample tests with NScenario\", currentTestIdentifierAccessor: ()=\u003e TestContext.CurrentContext.Test.ID);\n\n    [OneTimeSetUp]\n    public void GlobalSetup()\n    {\n        TestScenarioFactory.DefaultScenarioOutputWriter = new ComposeScenarioOutputWriter(new IScenarioOutputWriter[]\n        {\n            //INFO: Configure live reporting to console with NUnit\n            new StreamScenarioOutputWriter(TestContext.Progress),\n            //INFO: Configure collecting transcription as markdown\n            _reportWriter\n        });\n\n    }\n\n    [OneTimeTearDown]\n    public void GlobalTearDown()\n    {\n        // INFO: Save the raw Markdown to a file\n        _reportWriter.Save(\"Report.md\");\n        //INFO: Export the markdown to HTML file\n        _reportWriter.ExportToHtml(\"Report.html\");\n    }\n}\n```\n\n\nThere's also an option to generate a nice html report for all test scenarios. Just invoke `TestScenarioFactory.GetAllExecutedScenarios().SaveAsReport(\"AllReports.html\");` in your global teardown to get a report like the one below:\n\n![image](https://github.com/cezarypiatek/NScenario/assets/7759991/13c501d6-d26b-4406-93fb-1da29dca9bff)\n\n\nThis report browser supports links to scenario steps definition. To make it work, you need to set the following msbuild properties (or environment variables):\n- RepositoryUrl\n- SourceRevisionId\n\n## Test scenario title\n\nTest scenario title is generated by removing underscores and splitting camel/pascalcase string from the test method name (`[CallerMemberName]` is used to retrieve that name). This allows for immediate review of the test name (I saw many, extremely long and totally ridiculous test method names. A good test method name should reveal the intention of the test case, not its details). You can always override the default title by setting it explicitly during test scenario creation (especially useful for parametrized test methods):\n\n```cs\n[TestCase(false)]\n[TestCase(true)]\npublic async Task should_present_basic_scenario_with_explicit_title(bool someFlag)\n{\n    var scenario = TestScenarioFactory.Default(title: $\"some scenario when flag set to '{someFlag}'\");\n\n    await scenario.Step(\"This is the first step\", () =\u003e\n    {\n        // Here comes the logic\n    });\n\n    await scenario.Step(\"This is the second step\", () =\u003e\n    {\n        // Here comes the logic\n    });\n\n    await scenario.Step(\"This is the third step\", () =\u003e\n    {\n        // Here comes the logic\n    });\n}\n```\n\n`NScenario` is prefixing scenario title with `SCENARIO:` prefix and every step is prefixed with `STEP`. If you are writing step descriptions in other languages than English, you can override those prefixes by specifing them explicitly why calling `TestScenarioFactory.Default()` method.\n\n```cs\nvar scenario = TestScenarioFactory.Default(scenarioPrefix: \"SCENARIUSZ\", stepPrefix: \"KROK\");\n```\n\n\n\n## Why not XBehave.net\n\n[xBehave.net](https://github.com/adamralph/xbehave.net) is the `XUnit` extension so it can be used only with XUnit based tests. In my opinion, it is also quite cryptic (string extension methods called with single letter might not obvious) and a little bit over-complicated. **BUT THIS IS MY PERSONAL OPINION**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcezarypiatek%2Fnscenario","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcezarypiatek%2Fnscenario","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcezarypiatek%2Fnscenario/lists"}