WIP #256 - Add READMEs for every project

craigfowler · craigfowler · commit a0806683586e · 2026-01-17T21:01:32.000Z
diff --git a/CSF.Screenplay.Abstractions/CSF.Screenplay.Abstractions.csproj b/CSF.Screenplay.Abstractions/CSF.Screenplay.Abstractions.csproj
@@ -2,6 +2,7 @@
 
   <Import Project="..\Tools\MultiTargeting.props" />
   <Import Project="..\Tools\Version.props" />
+  <Import Project="..\Tools\PackageReadmes.props" />
 
   <PropertyGroup>
     <RootNamespace>CSF.Screenplay</RootNamespace>
diff --git a/CSF.Screenplay.Abstractions/README.md 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
@@ -1,17 +1,19 @@
 # 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
 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
@@ -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
@@ -0,0 +1 @@
+TODO: Write this docs page
diff --git 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
@@ -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
@@ -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
@@ -1,6 +1,7 @@
 ﻿<Project Sdk="Microsoft.NET.Sdk">
 
   <Import Project="..\Tools\Version.props" />
+  <Import Project="..\Tools\PackageReadmes.props" />
 
   <PropertyGroup>
     <TargetFrameworks Condition="'$(TargetFrameworks)' == ''">netcoreapp3.1;net462;netstandard2.0;net6.0;net8.0</TargetFrameworks>
diff --git a/CSF.Screenplay.JsonToHtmlReport/README.md 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
@@ -2,6 +2,7 @@
 
   <Import Project="..\Tools\MultiTargeting.props" />
   <Import Project="..\Tools\Version.props" />
+  <Import Project="..\Tools\PackageReadmes.props" />
 
   <PropertyGroup>
     <RootNamespace>CSF.Screenplay</RootNamespace>
diff --git a/CSF.Screenplay.NUnit/README.md 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
@@ -2,6 +2,7 @@
 
   <Import Project="..\Tools\MultiTargeting.props" />
   <Import Project="..\Tools\Version.props" />
+  <Import Project="..\Tools\PackageReadmes.props" />
 
   <PropertyGroup>
     <RootNamespace>CSF.Screenplay.Selenium</RootNamespace>
diff --git a/CSF.Screenplay.Selenium/README.md 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
@@ -2,6 +2,7 @@
 
   <Import Project="..\Tools\MultiTargeting.props" />
   <Import Project="..\Tools\Version.props" />
+  <Import Project="..\Tools\PackageReadmes.props" />
 
   <PropertyGroup>
     <RootNamespace>CSF.Screenplay</RootNamespace>
diff --git a/CSF.Screenplay.SpecFlow/README.md 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
@@ -1,6 +1,7 @@
 ﻿<Project Sdk="Microsoft.NET.Sdk">
 
   <Import Project="..\Tools\Version.props" />
+  <Import Project="..\Tools\PackageReadmes.props" />
 
   <PropertyGroup>
     <TargetFrameworks Condition="'$(TargetFrameworks)' == ''">net5.0;netstandard2.0;net462;net8.0</TargetFrameworks>
diff --git a/CSF.Screenplay.WebApis/README.md 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
@@ -2,6 +2,7 @@
 
   <Import Project="..\Tools\MultiTargeting.props" />
   <Import Project="..\Tools\Version.props" />
+  <Import Project="..\Tools\PackageReadmes.props" />
 
   <PropertyGroup>
     <RootNamespace>CSF.Screenplay</RootNamespace>
diff --git a/CSF.Screenplay/README.md 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
@@ -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
@@ -1,29 +1,27 @@
 # 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
-
-## An extensible framework
-
-Screenplay itself is a framework which is intended to be used alongside extensions.
+**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].
 
+**Learn Screenplay's concepts and how to use it [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/
-
-**Learn Screenplay's concepts and how to use it [on the documentation website].**
-
 [on the documentation website]: https://csf-dev.github.io/CSF.Screenplay/
 
-## Continuous integration status
+## Developer information
 
 CI builds are configured via **GitHub Actions**, 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)
diff --git a/Tests/README.md 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
@@ -0,0 +1,9 @@
+<Project>
+    <PropertyGroup>
+        <PackageReadmeFile>README.md</PackageReadmeFile>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <None Include="README.md" Pack="true" PackagePath="\" />
+    </ItemGroup>
+</Project>
diff --git a/Tools/README.md 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
diff --git 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
