summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--fable-arch.md81
1 files changed, 59 insertions, 22 deletions
diff --git a/fable-arch.md b/fable-arch.md
index 50a91a0..5e34aaa 100644
--- a/fable-arch.md
+++ b/fable-arch.md
@@ -1,4 +1,5 @@
---
+documentclass: report
title: Acceptance testing using Fable
author:
- The Fable project
@@ -16,8 +17,8 @@ abstract: |
presents the acceptance test suite to non-expert readers as a
human-readable text document.
- This document explains Fable, its architecture, and its input
- language.
+ This document explains Fable, its architecture, its input
+ language, and specifies the acceptance criteria for Fable.
...
# Beware
@@ -30,31 +31,67 @@ Fable that does not yet exist.
# Introduction
-Fable is a tool for acceptance testing of software. It helps software
-developers make sure their software fulfils the acceptance criteria
-for the software. Such criteria may come from paying clients, users,
+Fable is a tool for acceptance testing of software. It helps describe
+acceptance criteria for all stakeholders in a software project, and
+also for computers. Such criteria may come from paying clients, users,
the developers, their employers, or elsewhere.
-Fable is specifically meant for automated acceptance testing. It takes a
-two-pronged approach, where it lets developers write automated
-tests for all the acceptance criteria they have, and runs the tests.
-On the other hand, Fable also produces a standalone file, which documents the
-automated tests for non-technical stakeholders, such as project
-managers and clients.
+Fable is specifically meant for describing automated acceptance tests.
+It takes a two-pronged approach, where it lets developers write
+automated tests for all the acceptance criteria they have, and runs
+the tests. On the other hand, Fable also produces a standalone
+document, which describes the automated tests all stakeholders,
+including non-technical ones, such as project managers and clients.
-More concretely, Fable helps developers implement and document their
-automated acceptance tests in a way that, at the same time, helps the
-developers automatically test their software, and write documentation
-for the tests in way that doesn't require programming knowledge to
-understand.
+More concretely, Fable helps developers specify the automated
+acceptance tests so that the tests can be executed, but also
+understood without requiring programming knowledge to understand.
-Fable is meant to be a tool for developers, who use it to produce a
-document, which is meant to facilitate communication between various
-shareholders of the software being developed.
+Fable is meant to be used to produce a document to facilitate
+communication between various shareholders of the software being
+developed.
Fable's overall working principle is that the tests are implemented and
-documented in a number of source files, which Fable reads to execute
-tests, and to produce a document for non-developer consumption.
+documented in a number of source files, which by two Fable tools. One
+tool produces a PDF or HTML document, for humans to read. The other
+produces a test program, which executes the acceptaance tests.
+
+# Requirements
+
+This chapter lists requirements for Fable. These requirements are not
+meant to be testable as such. For more specific, testable acceptance
+criteria, see the later [chapter with acceptance tests for
+Fable](#acceptance).
+
+Each requirement here is given a unique mnemnoic id for easier
+reference in discussions.
+
+* **UnderstadableTests:** Acceptance tests should be possible to express in
+ a way that's easily understood by non-programmers.
+
+* **EasyToWriteDocs:** The markup language for writing documentation
+ should be easy to write.
+
+* **AidsComprehension:** The formatted human-readable documentation
+ should use good layout and typography to enhance comprension.
+
+* **CodeSeparately:** The code to implement the acceptance tests
+ should not be embedded in the documentation source, but be in
+ separate files. This makes it easier to edit without specialised
+ tooling.
+
+* **AnyProgammingLanguage:** The developers implementing the
+ acceptance tests should be free to use a language they're familiar
+ and comfortable with. Fable should not require them to use a
+ specific language.
+
+* **FastTestExecution:** Executing the acceptance tests should be
+ fast.
+
+* **NoDeployment:** The acceptance test tooling should assume the
+ system under test is already deployed and available. Deploying is
+ too big of a problem space to bring into the scope of acceptance
+ testing, and there are already good tools for deployment.
# Fable architecture
@@ -318,7 +355,7 @@ arguments and return values. The generated program will handle running
scenarios concurrently, and taking care of USING constraints, and
other resource constraints.
-# Acceptance tests for Fable
+# Acceptance tests for Fable {#acceptance}
FIXME: This needs to be written eventually, when Fable is implemented.