Skip to content

Commit 3099898

Browse files
thomasduftthomasduft
committed
docs: update README.md for clarity and consistency in tool description and usage
1 parent abef068 commit 3099898

File tree

1 file changed

+135
-73
lines changed

1 file changed

+135
-73
lines changed

‎README.md‎

Lines changed: 135 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -1,141 +1,203 @@
1-
[![build](https://github.com/thomasduft/testr/actions/workflows/build.yml/badge.svg)](https://github.com/thomasduft/testr/actions/workflows/build.yml) [![NuGet](https://img.shields.io/nuget/vpre/tomware.TestR.svg)](https://www.nuget.org/packages/tomware.TestR)
1+
[![build](https://github.com/thomasduft/testr/actions/workflows/build.yml/badge.svg)](https://github.com/thomasduft/testr/actions/workflows/build.yml) [![NuGet](https://img.shields.io/nuget/vpre/tomware.testr.svg)](https://www.nuget.org/packages/tomware.testr)
22

3+
# testr
34

4-
# testR
5-
6-
A cli tool to manage executable test cases.
5+
A command-line tool for managing and executing automated test cases with browser support.
76

87
## Introduction
98

10-
`testR` is a command-line tool designed to manage and execute test cases. It supports running test cases against different browsers, validating test case definitions, and creating new test case definitions.
9+
`testr` is a powerful CLI tool designed to streamline test case management and execution. It provides comprehensive support for running automated end-to-end tests across multiple browsers, validating test case definitions, and creating new test cases with a file-based approach.
10+
11+
### Key Features
12+
13+
- 🌐 **Multi-browser support** - Run tests on Chrome, Firefox, and WebKit
14+
- 📝 **File-based test definitions** - Maintain test cases as markdown files
15+
- 🔄 **Test execution history** - Track and store test run results
16+
- 🧪 **Dynamic variables** - Support for parameterized test data
17+
- 📊 **OpenTelemetry integration** - Built-in observability and monitoring
18+
- ✅ **Test validation** - Validate test case definitions before execution
1119

12-
### Vision
20+
## Vision & Workflow
1321

14-
The vision of this tool is to have a tool agnostic file based approach to maintain test cases. A common workflow looks like the following:
22+
The vision of `testr` is to provide a tool-agnostic, file-based approach to test case management. The typical workflow follows these steps:
1523

16-
1. Team creates Use-Cases
17-
2. out of the Use-Cases, Test-Cases will be defined (Test-Case type: Definition) - see [TC-Login-001 Definition sample](samples/Definitions/localhost/TC-Login-001.md)
18-
3. once a feature has been implemented the appropriate Test-Cases can be executed against an environment in an E2E automated manner
19-
![Sample Run](TC-001-Login-Run.gif)
20-
4. each run will be historied with Test-Cases known as Runs (Test-Case type: Run) - see [TC-Login-001 Run sample](samples/Runs/localhost/TC-Login-001.md)
24+
1. **Define Use Cases** - Teams create high-level use case documentation
25+
2. **Create Test Case Definitions** - Convert use cases into executable test case definitions
26+
📄 [Example: TC-Login-001 Definition](samples/Definitions/localhost/TC-Login-001.md)
27+
3. **Execute Tests** - Run automated end-to-end tests against target environments
28+
![Sample Test Run](TC-001-Login-Run.gif)
29+
4. **Store Results** - Each execution creates a historical test run record
30+
📄 [Example: TC-Login-001 Run](samples/Runs/localhost/TC-Login-001.md)
2131

22-
> Note: In case of escaping strings please use a backslash `\` followed by a double quote `"` (e.g. Locator=GetByText Text=\\"Invalid login attempt for user 'Albert'\\" Action=IsVisible)
32+
> **Note:** When escaping strings in test data, use a backslash `\` followed by a double quote `"`. For example:
33+
> `Locator=GetByText Text=\\"Invalid login attempt for user 'Albert'\\" Action=IsVisible`
2334
2435
## Installation
2536

26-
To install `testR`, clone the repository and build the project using the .NET CLI:
37+
### Prerequisites
38+
39+
- [.NET 9.0 SDK](https://dotnet.microsoft.com/download/dotnet/9.0) or later
40+
41+
### Option 1: Install from NuGet (Recommended)
42+
43+
Install `testr` globally using the .NET tool command:
44+
45+
```bash
46+
dotnet tool install -g tomware.testr
47+
```
48+
49+
### Option 2: Build from Source
2750

28-
```sh
51+
Clone the repository and build the project:
52+
53+
```bash
2954
git clone https://github.com/thomasduft/testr.git
3055
cd testr
3156
dotnet build
3257
```
3358

34-
For local testing purpose run the `install.sh` script.
35-
36-
In case of installing the tool in an official way use the following command:
59+
For local development and testing, run the installation script:
3760

38-
> `dotnet tool install -g tomware.TestR`
61+
```bash
62+
./install.sh
63+
```
3964

4065
## Usage
4166

67+
### Quick Start
68+
69+
```bash
70+
# Create a new test case
71+
testr test-case TC-Login-001 "User Login Test"
72+
73+
# Validate a test case definition
74+
testr validate TC-Login-001
75+
76+
# Run a test case
77+
testr run https://localhost:5001 --test-case-id TC-Login-001
78+
```
79+
80+
### Command Overview
81+
4282
```bash
4383
A cli tool to manage and run executable test cases.
4484

45-
Usage: testR [command] [options]
85+
Usage: testr [command] [options]
4686

4787
Options:
4888
-?|-h|--help Show help information.
4989

5090
Commands:
51-
man Displays a man page for helping with writing the Test-Data syntax within a Test Case.
52-
playwright Offers Playwright specific commands.
53-
run Runs Test Case definitions (i.e. "https://localhost:5001" -tc TC-Audit-001).
54-
test-case Creates a new Test Case definition (i.e. test-case TC-Audit-001 "My TestCase Title").
55-
validate Validates a Test Case definition (i.e. TC-Audit-001).
91+
man Display syntax help for writing test data within test cases
92+
playwright Playwright-specific commands and utilities
93+
run Execute test case definitions
94+
test-case Create new test case definitions
95+
validate Validate existing test case definitions
5696

57-
Run 'testR [command] -?|-h|--help' for more information about a command.
97+
Run 'testr [command] -?|-h|--help' for more information about a command.
5898
```
5999
60-
### Commands
100+
## Detailed Command Reference
61101
62-
#### run
102+
### `run` - Execute Test Cases
63103
64-
Runs Test Case definitions.
104+
Execute test case definitions against target environments.
65105
66-
```sh
67-
testR run [domain] [options]
106+
```bash
107+
testr run [domain] [options]
108+
```
68109
69-
Options:
70-
-tc|--test-case-id The Test Case ID (e.g. TC-Audit-001).
71-
-i|--input-directory The input directory where the Test Case definition is located.
72-
Default value is: ..
73-
-o|--output-directory The output directory where the Test Case result will be stored.
74-
--headless Runs the browser in headless mode.
75-
Default value is: False.
76-
--continue-on-failure Continues the Test Case execution even if the Test Case fails.
77-
Default value is: False.
78-
-s|--slow Slows down the execution by the specified amount of milliseconds.
79-
Default value is: 500.
80-
-t|--timeout Sets the timeout for awaiting the Playwright Locator in milliseconds.
81-
Default value is: 10000.
82-
-bt|--browser-type Sets the browser type to run the Test Case against (currently supported Browsers: Chrome, Firefox, Webkit).
83-
Allowed values are: Chrome, Firefox, Webkit.
84-
Default value is: Chrome.
85-
-rvd|--record-video-dir Records a video of the Test Case execution to the specified directory.
86-
-v|--variable Key-Value based variable used for replacing property values in a Test Step data configuration.
87-
-?|-h|--help Show help information.
110+
**Options:**
111+
- `-tc|--test-case-id` - Test Case ID to execute (e.g., `TC-Audit-001`)
112+
- `-i|--input-directory` - Directory containing test case definitions (default: `.`)
113+
- `-o|--output-directory` - Directory for storing test results
114+
- `--headless` - Run browser in headless mode (default: `false`)
115+
- `--continue-on-failure` - Continue execution on test failures (default: `false`)
116+
- `-s|--slow` - Slow down execution by specified milliseconds (default: `500`)
117+
- `-t|--timeout` - Playwright locator timeout in milliseconds (default: `10000`)
118+
- `-bt|--browser-type` - Browser to use: `Chrome`, `Firefox`, `Webkit` (default: `Chrome`)
119+
- `-rvd|--record-video-dir` - Directory for recording test execution videos
120+
- `-v|--variable` - Define variables for test data replacement
121+
- `--otlp` - OpenTelemetry endpoint for metrics collection
122+
123+
**Example:**
124+
```bash
125+
testr run https://localhost:5001 \
126+
--test-case-id TC-Login-001 \
127+
--browser-type Chrome \
128+
--record-video-dir ./videos \
129+
--variable Username=testuser --variable Password=secret123
88130
```
89131
90-
#### test-case
132+
### `test-case` - Create Test Cases
91133
92-
Creates a new Test Case definition.
134+
Create new test case definition files.
93135
94-
```sh
95-
testR test-case [test-case-id] [title]
136+
```bash
137+
testr test-case [test-case-id] [title]
96138
```
97139
98-
#### validate
140+
**Example:**
141+
```bash
142+
testr test-case TC-Registration-001 "User Registration Flow"
143+
```
99144
100-
Validates a Test Case definition.
145+
### `validate` - Validate Test Cases
101146
102-
```sh
103-
testR validate [test-case-id] [options]
147+
Validate the syntax and structure of test case definitions.
104148
105-
Options:
106-
-i|--input-directory The input directory where the Test Case definition is located. (default: .)
149+
```bash
150+
testr validate [test-case-id] [options]
151+
```
152+
153+
**Options:**
154+
- `-i|--input-directory` - Directory containing test case definitions (default: `.`)
155+
156+
**Example:**
157+
```bash
158+
testr validate TC-Login-001 --input-directory ./test-definitions
107159
```
108160
109-
#### Variables Support for Test Data
161+
## Advanced Features
110162
111-
In order to pass in dynamic or confidential data `testR` supports so called `Variables` in a Test Case Step definition.
163+
### Variable Support
112164
113-
A variable is a `Value`-property value starting with a `@`-sign (see below the `@Password`-variable).
165+
Use variables to inject dynamic or sensitive data into test cases. Variables are defined in test steps using the `@` prefix:
114166
115167
```markdown
116168
| 1 | enter password | Locator=GetByLabel Text=Password Action=Fill Value=@Password | password is entered | - |
117169
```
118170
119-
In order to look it up and replace it during execution of the Test Case you need to pass in the appropriate value via the `-v|--variable`-command line argument option.
120-
121-
For the above sample the command line argument option looks like the following:
171+
Pass variable values at runtime:
122172
123173
```bash
124-
.... -v Password=password ...
174+
testr run https://localhost:5001 \
175+
--test-case-id TC-Login-001 \
176+
--variable Password=mysecretpassword \
177+
--variable Username=testuser
125178
```
126179
127-
> Caution: The `Key`-value is case sensitive!
128-
129-
#### OpenTelemetry Support
180+
> ⚠️ **Important:** Variable keys are case-sensitive!
130181
131-
`testR` includes built-in support for OpenTelemetry (OTLP) to enable observability and monitoring of test case executions. This feature allows you to collect metrics from your test runs and send them to compatible observability platforms.
182+
### OpenTelemetry Integration
132183
133-
To enable OpenTelemetry support, use the `--otlp` option when running test cases:
184+
Enable comprehensive observability and monitoring for your test executions:
134185
135186
```bash
136-
testR run https://localhost:5001 --test-case-id TC-Login-001 --otlp "http://localhost:9090/api/v1/otlp/v1/metrics"
187+
testr run https://localhost:5001 \
188+
--test-case-id TC-Login-001 \
189+
--otlp "http://localhost:9090/api/v1/otlp/v1/metrics"
137190
```
138191
192+
This allows you to:
193+
- Track test execution metrics
194+
- Monitor performance trends
195+
- Integrate with observability platforms like Prometheus and Grafana
196+
139197
## License
140198
141199
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
200+
201+
---
202+
203+
**Happy Testing!** 🚀

0 commit comments

Comments
 (0)