diff --git a/CSF.Screenplay.Abstractions/CSF.Screenplay.Abstractions.csproj b/CSF.Screenplay.Abstractions/CSF.Screenplay.Abstractions.csproj index c4a227b4..3f225c85 100644 --- a/CSF.Screenplay.Abstractions/CSF.Screenplay.Abstractions.csproj +++ b/CSF.Screenplay.Abstractions/CSF.Screenplay.Abstractions.csproj @@ -2,6 +2,7 @@ + CSF.Screenplay diff --git a/CSF.Screenplay.Abstractions/README.md b/CSF.Screenplay.Abstractions/README.md new file mode 100644 index 00000000..4357b38e --- /dev/null +++ b/CSF.Screenplay.Abstractions/README.md @@ -0,0 +1,15 @@ +# CSF.Screenplay.Abstractions + +**CSF.Screenplay.Abstractions** provides the interfaces and abstractions for much of [CSF.Screenplay]'s API. +It does not contain the logic and associated dependencies for the Screenplay framework. +As such, this library is expected to receive changes less frequently than the other libraries in the CSF.Screenplay ecosystem. + +Use the library for: + +* Authoring new [Screenplay extensions] +* Writing [Performables] and/or [Abilities] for your own software or tests, if you wish to keep those types in an assembly which does not depend upon the full Screenplay package + +[CSF.Screenplay]: https://www.nuget.org/packages/CSF.Screenplay +[Screenplay extensions]: https://csf-dev.github.io/CSF.Screenplay/glossary/Extension.html +[Performables]: https://csf-dev.github.io/CSF.Screenplay/glossary/Performable.html +[Abilities]: https://csf-dev.github.io/CSF.Screenplay/glossary/Ability.html diff --git a/CSF.Screenplay.Docs/README.md b/CSF.Screenplay.Docs/README.md index 149ae99c..d9043832 100644 --- a/CSF.Screenplay.Docs/README.md +++ b/CSF.Screenplay.Docs/README.md @@ -1,13 +1,14 @@ # Documentation source files This directory contains a [DocFx documentation project]. -These are the source files which generate the documentation website in the `docs/` directory. +These are the source files which generate the content of the `docs/` directory at the root of the solution. +That docs directory forms [the CSF.Screenplay documentation website]. Files in the `api/` subdirectory are auto-generated by the DocFx build process; they are not for hand-editing. API documentation is auto-generated from C# types and members and their XML documentation comments. Markdown files (except this README file) in this directory and subdirectories are converted to HTML pages by DocFx. -The `CSF.Screenplay.Docs.proj` file ensures that the latest documentation is built just by executing `dotnet build`. +The `CSF.Screenplay.Docs.proj` file ensures that the latest documentation is built just by executing `dotnet build -c Docs`. If you do not yet have the `docfx` .NET tool installed then you will receive a build error; use the following command to install (or update) it. ```txt @@ -15,3 +16,4 @@ dotnet tool update -g docfx ``` [DocFx documentation project]: https://dotnet.github.io/docfx/index.html +[the CSF.Screenplay documentation website]: https://csf-dev.github.io/CSF.Screenplay/ diff --git a/CSF.Screenplay.Docs/docs/extensions/selenium/index.md b/CSF.Screenplay.Docs/docs/extensions/selenium/index.md new file mode 100644 index 00000000..ef1a52e2 --- /dev/null +++ b/CSF.Screenplay.Docs/docs/extensions/selenium/index.md @@ -0,0 +1 @@ +TODO: Write this docs page diff --git a/CSF.Screenplay.Docs/docs/extensions/webApis/index.md b/CSF.Screenplay.Docs/docs/extensions/webApis/index.md new file mode 100644 index 00000000..ef1a52e2 --- /dev/null +++ b/CSF.Screenplay.Docs/docs/extensions/webApis/index.md @@ -0,0 +1 @@ +TODO: Write this docs page diff --git a/CSF.Screenplay.Docs/glossary/index.md b/CSF.Screenplay.Docs/glossary/index.md index a7a9d7bf..38701754 100644 --- a/CSF.Screenplay.Docs/glossary/index.md +++ b/CSF.Screenplay.Docs/glossary/index.md @@ -9,6 +9,7 @@ Where applicable, the glossary item links directly to the relevant type within t | [Ability] | Something that an actor is able to do or has; provides the dependencies for actions/questions | | [Action] | A kind of peformable; the lowest-level interaction that changes the state of the application | | [Actor] | Typically a human user of the application, directs the use of performables | +| [Asset] | A file which is saved to disk during a Performance, accessible from the Report | | [Cast] | A factory & registry for actors which facilitates managing multiple actors in a performance | | [Extension] | An add-on library providing new Abilities, Actions & Questions for controlling a specific technology | | [Feature] | A logical group of related scenarios, this is a test class or test fixture in some testing frameworks | @@ -42,3 +43,4 @@ Where applicable, the glossary item links directly to the relevant type within t [Feature]: Feature.md [Integration]: Integration.md [Extension]: Extension.md +[Asset]: Asset.md diff --git a/CSF.Screenplay.Docs/glossary/toc.yml b/CSF.Screenplay.Docs/glossary/toc.yml index d49ee9bd..83b1cc2d 100644 --- a/CSF.Screenplay.Docs/glossary/toc.yml +++ b/CSF.Screenplay.Docs/glossary/toc.yml @@ -6,8 +6,12 @@ href: Action.md - name: Actor uid: CSF.Screenplay.Actor +- name: Asset + href: Asset.md - name: Cast uid: CSF.Screenplay.ICast +- name: Extension + href: Extension.md - name: Feature href: Feature.md - name: Integration diff --git a/CSF.Screenplay.JsonToHtmlReport.Template/README.md b/CSF.Screenplay.JsonToHtmlReport.Template/README.md index b5795a69..d9d23257 100644 --- a/CSF.Screenplay.JsonToHtmlReport.Template/README.md +++ b/CSF.Screenplay.JsonToHtmlReport.Template/README.md @@ -4,3 +4,5 @@ This project contains a small node/Webpack project, used to build the HTML file The HTML template is used as an embedded resource in that app/library. This project contains the _source code_ for building the HTML template; the build output of this project is sent to `CSF.Screenplay.JsonToHtmlReport/template/template.html`, where it is consumed as an embedded resource. + +_This project is not built/packaged independently; it is used only to supplement the JSON-to-HTML report generator project._ diff --git a/CSF.Screenplay.JsonToHtmlReport/CSF.Screenplay.JsonToHtmlReport.csproj b/CSF.Screenplay.JsonToHtmlReport/CSF.Screenplay.JsonToHtmlReport.csproj index e2bc4026..b08e548a 100644 --- a/CSF.Screenplay.JsonToHtmlReport/CSF.Screenplay.JsonToHtmlReport.csproj +++ b/CSF.Screenplay.JsonToHtmlReport/CSF.Screenplay.JsonToHtmlReport.csproj @@ -1,6 +1,7 @@  + netcoreapp3.1;net462;netstandard2.0;net6.0;net8.0 diff --git a/CSF.Screenplay.JsonToHtmlReport/README.md b/CSF.Screenplay.JsonToHtmlReport/README.md new file mode 100644 index 00000000..0e79e137 --- /dev/null +++ b/CSF.Screenplay.JsonToHtmlReport/README.md @@ -0,0 +1,8 @@ +# CSF.Screenplay.JsonToHtmlReport + +**CSF.Screenplay.JsonToHtmlReport** is a utility which converts a JSON-format [Screenplay Report] into a human-readable, interactive HTML page. +This is particularly useful if you wish to share the results of your Screenplay Performances with developers and non-developers alike. + +This project may also be consumed as a library to add HTML report-generation capabilities to your own application. + +[Screenplay Report]: https://csf-dev.github.io/CSF.Screenplay/docs/GettingReports.html diff --git a/CSF.Screenplay.NUnit/CSF.Screenplay.NUnit.csproj b/CSF.Screenplay.NUnit/CSF.Screenplay.NUnit.csproj index 85753053..39d574e4 100644 --- a/CSF.Screenplay.NUnit/CSF.Screenplay.NUnit.csproj +++ b/CSF.Screenplay.NUnit/CSF.Screenplay.NUnit.csproj @@ -2,6 +2,7 @@ + CSF.Screenplay diff --git a/CSF.Screenplay.NUnit/README.md b/CSF.Screenplay.NUnit/README.md new file mode 100644 index 00000000..156f8163 --- /dev/null +++ b/CSF.Screenplay.NUnit/README.md @@ -0,0 +1,9 @@ +# CSF.Screenplay.NUnit + +**CSF.Screenplay.NUnit** is a [Test Framework Integration] which allows Screenplay-based logic/syntax to be used with tests written in [NUnit v3.6+]. + +Learn more at the [Getting Started with NUnit 3 documentation page]. + +[Test Framework Integration]: https://csf-dev.github.io/CSF.Screenplay/glossary/Integration.html +[NUnit v3.6+]: https://nunit.org/ +[Getting Started with NUnit 3 documentation page]: https://csf-dev.github.io/CSF.Screenplay/docs/gettingStarted/nunit3/index.html diff --git a/CSF.Screenplay.Selenium/CSF.Screenplay.Selenium.csproj b/CSF.Screenplay.Selenium/CSF.Screenplay.Selenium.csproj index c387fd6d..c649c3c8 100644 --- a/CSF.Screenplay.Selenium/CSF.Screenplay.Selenium.csproj +++ b/CSF.Screenplay.Selenium/CSF.Screenplay.Selenium.csproj @@ -2,6 +2,7 @@ + CSF.Screenplay.Selenium diff --git a/CSF.Screenplay.Selenium/README.md b/CSF.Screenplay.Selenium/README.md new file mode 100644 index 00000000..8995c612 --- /dev/null +++ b/CSF.Screenplay.Selenium/README.md @@ -0,0 +1,9 @@ +# CSF.Screenplay.Selenium + +**CSF.Screenplay.Selenium** is a [Screenplay Extension] which allows CSF.Screenplay to control Web Browsers via a [Selenium WebDriver]. + +Learn more at [the documentation for the CSF.Screenplay.Selenium extension]. + +[Screenplay Extension]: https://csf-dev.github.io/CSF.Screenplay/glossary/Extension.html +[Selenium WebDriver]: https://www.selenium.dev/ +[the documentation for the CSF.Screenplay.Selenium extension]: https://csf-dev.github.io/CSF.Screenplay/docs/extensions/selenium/index.html diff --git a/CSF.Screenplay.SpecFlow/CSF.Screenplay.SpecFlow.csproj b/CSF.Screenplay.SpecFlow/CSF.Screenplay.SpecFlow.csproj index 2e431ff1..056e69f3 100644 --- a/CSF.Screenplay.SpecFlow/CSF.Screenplay.SpecFlow.csproj +++ b/CSF.Screenplay.SpecFlow/CSF.Screenplay.SpecFlow.csproj @@ -2,6 +2,7 @@ + CSF.Screenplay diff --git a/CSF.Screenplay.SpecFlow/README.md b/CSF.Screenplay.SpecFlow/README.md new file mode 100644 index 00000000..1ba1d360 --- /dev/null +++ b/CSF.Screenplay.SpecFlow/README.md @@ -0,0 +1,11 @@ +# CSF.Screenplay.SpecFlow + +**CSF.Screenplay.SpecFlow** is a [Test Framework Integration] which allows Screenplay-based logic/syntax to be used with tests written in the [legacy SpecFlow, *which is now retired*]. + +Learn more at the [Getting Started with Reqnroll documentation page]. +[Reqnroll] is the maintained fork of SpecFlow, supported by its original authors. + +[Test Framework Integration]: https://csf-dev.github.io/CSF.Screenplay/glossary/Integration.html +[legacy SpecFlow, *which is now retired*]: https://reqnroll.net/news/2025/01/specflow-end-of-life-has-been-announced/ +[Getting Started with Reqnroll documentation page]: https://csf-dev.github.io/CSF.Screenplay/docs/gettingStarted/reqnroll/index.html +[Reqnroll]: https://reqnroll.net/ diff --git a/CSF.Screenplay.WebApis/CSF.Screenplay.WebApis.csproj b/CSF.Screenplay.WebApis/CSF.Screenplay.WebApis.csproj index 7117f640..56bc3159 100644 --- a/CSF.Screenplay.WebApis/CSF.Screenplay.WebApis.csproj +++ b/CSF.Screenplay.WebApis/CSF.Screenplay.WebApis.csproj @@ -1,6 +1,7 @@  + net5.0;netstandard2.0;net462;net8.0 diff --git a/CSF.Screenplay.WebApis/README.md b/CSF.Screenplay.WebApis/README.md new file mode 100644 index 00000000..39bd5599 --- /dev/null +++ b/CSF.Screenplay.WebApis/README.md @@ -0,0 +1,8 @@ +# CSF.Screenplay.WebApis + +**CSF.Screenplay.WebApis** is a [Screenplay Extension] which allows CSF.Screenplay to interact with HTTP web API endpoints. + +Learn more at [the documentation for the CSF.Screenplay.WebApis extension]. + +[Screenplay Extension]: https://csf-dev.github.io/CSF.Screenplay/glossary/Extension.html +[the documentation for the CSF.Screenplay.WebApis extension]: https://csf-dev.github.io/CSF.Screenplay/docs/extensions/webApis/index.html diff --git a/CSF.Screenplay/CSF.Screenplay.csproj b/CSF.Screenplay/CSF.Screenplay.csproj index 0ee09161..839babe6 100644 --- a/CSF.Screenplay/CSF.Screenplay.csproj +++ b/CSF.Screenplay/CSF.Screenplay.csproj @@ -2,6 +2,7 @@ + CSF.Screenplay diff --git a/CSF.Screenplay/README.md b/CSF.Screenplay/README.md new file mode 100644 index 00000000..5c3bd973 --- /dev/null +++ b/CSF.Screenplay/README.md @@ -0,0 +1,11 @@ +# CSF.Screenplay + +**CSF.Screenplay** is the core logic of the CSF.Screenplay framework. +It provides the *engine* for running Screenplay Performances but provides very little in the way of capabilities such as [Abilities] or [Performables]. + +To make Screenplay useful, you will likely need to make use of one or more [Screenplay Extensions], and a [Test Framework Integration] if you wish to use Screenplay as a testing tool. + +[Abilities]: https://csf-dev.github.io/CSF.Screenplay/glossary/Ability.html +[Performables]: https://csf-dev.github.io/CSF.Screenplay/glossary/Performable.html +[Screenplay Extensions]: https://csf-dev.github.io/CSF.Screenplay/glossary/Extension.html +[Test Framework Integration]: https://csf-dev.github.io/CSF.Screenplay/glossary/Integration.html diff --git a/LICENSE b/LICENSE index c9307b6b..165aa703 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2024 CSF Software Limited +Copyright (c) 2026 CSF Software Limited Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 5bd9af04..16adfe22 100755 --- a/README.md +++ b/README.md @@ -1,20 +1,31 @@ # CSF.Screenplay Screenplay is a *software design pattern* to assist in the automation of complex processes. -It is commonly recommended for use in writing tests using the [Behaviour Driven Development] (BDD) style. -**CSF.Screenplay** is a library and framework for using this design pattern. +Screenplay synergises particularly well with tests which use the [Behaviour Driven Development] (BDD) style. -[Behaviour Driven Development]: https://en.wikipedia.org/wiki/Behavior-driven_development +**CSF.Screenplay** is a library and framework which brings that design pattern to .NET. +The main library itself is intended to be used alongside extensions. +It has *two primary extension points*; [Test Framework integrations] and [Screenplay Extensions]. +One such extension is [CSF.Screenplay.Selenium], which allows Screenplay to control Web Browsers, via [a Selenium WebDriver]. -## More information +**Learn Screenplay's concepts and how to use it [on the documentation website].** -Detailed information about Screenplay & how it is used is [available on the documentation website]. +[Behaviour Driven Development]: https://en.wikipedia.org/wiki/Behavior-driven_development +[Test Framework integrations]: https://csf-dev.github.io/CSF.Screenplay/glossary/Integration.html +[Screenplay Extensions]: https://csf-dev.github.io/CSF.Screenplay/glossary/Extension.html +[CSF.Screenplay.Selenium]: https://www.nuget.org/packages/CSF.Screenplay.Selenium +[a Selenium WebDriver]: https://www.selenium.dev/ +[on the documentation website]: https://csf-dev.github.io/CSF.Screenplay/ -[available on the documentation website]: https://csf-dev.github.io/CSF.Screenplay/ +## Developer information -## Continuous integration status +CI builds are configured via **GitHub Actions**, with static code analysis & reporting in **SonarCloud**. +This project is tested with [BrowserStack]. -CI builds are configured via **AppVeyor**, with static code analysis & reporting in **SonarCloud**. +The contents of the `docs/` directory of this repository is auto-generated from the `CSF.Screenplay.Docs` project. +There is nothing hand-editable inside. [![.NET CI](https://github.com/csf-dev/CSF.Screenplay/actions/workflows/dotnetCi.yml/badge.svg)](https://github.com/csf-dev/CSF.Screenplay/actions/workflows/dotnetCi.yml) [![Test coverage](https://sonarcloud.io/api/project_badges/measure?project=csf-dev_CSF.Screenplay&metric=coverage)](https://sonarcloud.io/summary/new_code?id=csf-dev_CSF.Screenplay) + +[BrowserStack]: https://www.browserstack.com/ diff --git a/Tests/README.md b/Tests/README.md new file mode 100644 index 00000000..f8e55707 --- /dev/null +++ b/Tests/README.md @@ -0,0 +1,8 @@ +# Tests + +This directory contains .NET test projects; nothing here is packed or forms part of the CSF.Screenplay framework. + +Of note, the **CSF.Screenplay.Selenium.TestWebapp** project is a small website without any test code of its own. +It is used alongside **CSF.Screenplay.Selenium.Tests**. +The Selenium-based tests are written to interact with this small app, the behaviour of which is already known and verified. +This way, the Selenium tests may verify that Screenplay/Selenium are interacting with web applications in the correct/expected manner. diff --git a/Tools/PackageReadmes.props b/Tools/PackageReadmes.props new file mode 100644 index 00000000..40817ea7 --- /dev/null +++ b/Tools/PackageReadmes.props @@ -0,0 +1,9 @@ + + + README.md + + + + + + \ No newline at end of file diff --git a/Tools/README.md b/Tools/README.md new file mode 100644 index 00000000..8563e788 --- /dev/null +++ b/Tools/README.md @@ -0,0 +1,8 @@ +# Tools + +This directory contains a mixture of content: + +* Shared files + * For example, MSBuild `.props` files with reusable content +* Build & configuration files + * For example, files used during the CI build process diff --git a/Tools/appveyor_publish_docs.ps1 b/Tools/appveyor_publish_docs.ps1 deleted file mode 100644 index 1a231510..00000000 --- a/Tools/appveyor_publish_docs.ps1 +++ /dev/null @@ -1,31 +0,0 @@ -$ErrorActionPreference = "Stop" - -$BaseDir = "docs" - -if($Env:APPVEYOR -eq "True" -and ($Env:APPVEYOR_PULL_REQUEST_NUMBER -or $Env:APPVEYOR_REPO_BRANCH -ne "master")) { - Write-Host "Skipping publishing docs; we are not building on master" - Exit 0; -} - -Write-Host "Publishing the docs site to $BaseDir" - -if($Env:APPVEYOR -eq "True") { - Write-Host "Setting up git to make a commit from Appveyor" - git config --global user.name "Appveyor (on behalf of Craig Fowler)" - git config --global user.email "craig+appveyor@csf-dev.com" - git config --global credential.helper store - Set-Content -Path "$HOME\.git-credentials" -Value "https://$($Env:GITHUB_SECRET_KEY):x-oauth-basic@github.com`n" -NoNewline -} - -# The git commands below could report warnings which cause the script to -# stop unless I change the error preference first -$ErrorActionPreference = "silentlycontinue" - -git checkout -b temp/publish-docs -git add --all $BaseDir/ -git commit -m "Auto: Updates to docs website via CI [skip ci]" -git checkout $Env:APPVEYOR_REPO_BRANCH -git pull -git merge temp/publish-docs --no-ff -m "Auto: Merge docs website via CI [skip ci]" -git push origin $Env:APPVEYOR_REPO_BRANCH -BRANCH diff --git a/Tools/se-config.toml b/Tools/se-config.toml index 72d87f07..6a3f8c5c 100644 --- a/Tools/se-config.toml +++ b/Tools/se-config.toml @@ -1,7 +1,11 @@ -# This config file is required for builds running on AppVeyor -# because AppVeyor images come with chromedriver pre-installed, but its -# usually not the version we want. That's because on the Windows images, -# Chrome will have auto-updated. +# This is a Selenium Manager configuration file: +# * https://www.selenium.dev/blog/2022/introducing-selenium-manager/ +# * https://www.selenium.dev/documentation/selenium_manager/ +# +# It's used for CI, when performing first-level tests with a locally-running +# Web Browser and WebDriver. It ensures that the CI environment picks Google +# Chrome and that it downloads the whole browser independently of any software +# already installed. browser = "chrome" force-browser-download = true