Skip to content

Commit ed2846b

Browse files
mike-d-davydovmike-d-davydov
committed
docs: Refine README with updated examples and installation instructions
1 parent e2e514b commit ed2846b

File tree

1 file changed

+91
-46
lines changed

1 file changed

+91
-46
lines changed

‎README.md‎

Lines changed: 91 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
JPWise is a powerful Java framework for generating pairwise test combinations, with support for complex parameter relationships and compatibility rules. See [All-pairs testing](https://en.wikipedia.org/wiki/All-pairs_testing) for more information about this testing approach.
44

55
## Table of Contents
6-
- [Why JPWise?](#why-jpwise-smart--simple-test-data-generation)
6+
- [Why JPWise? Smart & Simple Test Data Generation](#why-jpwise-smart--simple-test-data-generation)
77
- [Features](#features)
88
- [Installation](#installation)
99
- [Basic Usage](#basic-usage)
@@ -22,51 +22,55 @@ Manually creating comprehensive test data for features with many interacting opt
2222
**Here's JPWise in action, demonstrating key features including TestNG integration:**
2323

2424
```java
25-
import io.github.mikeddavydov.jpwise.JPWise;
26-
import io.github.mikeddavydov.jpwise.core.CombinationTable;
27-
import io.github.mikeddavydov.jpwise.core.CompatibilityPredicate;
28-
import io.github.mikeddavydov.jpwise.core.EquivalencePartition;
29-
import io.github.mikeddavydov.jpwise.core.SimpleValue;
30-
import io.github.mikeddavydov.jpwise.core.CyclingPartition;
25+
import io.github.mikeddavydov.jpwise.*;
26+
import io.github.mikeddavydov.jpwise.core.*;
27+
import static java.util.Arrays.asList;
28+
import java.util.List;
3129
import org.testng.annotations.DataProvider;
3230
import org.testng.annotations.Test;
33-
import java.util.Arrays;
34-
import java.util.List;
3531

3632
public class JPWiseQuickDemoTest {
33+
3734
private static final CombinationTable DEMO_COMBINATIONS = generateJPWiseData();
3835

3936
private static CombinationTable generateJPWiseData() {
40-
// Define a rule: "Safari" browser is only compatible with "macOS"
41-
List<CompatibilityPredicate> browserRules = Arrays.asList(
42-
(ep1, ep2) -> {
37+
// Define a rule: "Safari" browser is only compatible with "macOS".
38+
List<CompatibilityPredicate> browserOsRules = asList(
39+
(ep1, ep2) -> { // ep1 will be a "Browser" value, ep2 will be an "OS" value
4340
if (ep1.getName().equals("Safari") && !ep2.getName().equals("macOS")) {
44-
return false; // Safari is incompatible with non-macOS
41+
return false; // Incompatible pair
4542
}
46-
return true; // Otherwise compatible
43+
return true; // Compatible pair
4744
}
4845
);
4946

5047
return JPWise.builder()
51-
.parameter("Browser",
52-
CyclingPartition.of("Chrome", Arrays.asList("latest", "previous")),
53-
SimpleValue.of("Safari"))
54-
.parameter("OS",
55-
SimpleValue.of("macOS"),
56-
SimpleValue.of("Windows"))
57-
.generatePairwise();
48+
.parameter("Browser", // First parameter: Browser
49+
asList(
50+
// Chrome will cycle through "latest" and "previous" versions
51+
CyclingPartition.of("Chrome", asList("latest", "previous")),
52+
SimpleValue.of("Safari")
53+
),
54+
browserOsRules) // These rules apply between "Browser" and the next parameter ("OS")
55+
.parameter("OS", // Second parameter: Operating System
56+
SimpleValue.of("macOS"),
57+
SimpleValue.of("Windows")
58+
)
59+
.generatePairwise(); // Generate all valid pairs
5860
}
5961

6062
@DataProvider(name = "jpwiseTestData")
6163
public Object[][] getTestDataFromJPWise() {
64+
// Provides generated combinations to TestNG tests
6265
return DEMO_COMBINATIONS.asDataProvider();
6366
}
6467

6568
@Test(dataProvider = "jpwiseTestData")
66-
public void testFeatureWithVariedConfigs(String description, String browser, String os) {
67-
// description provides a summary (e.g., "Browser=Chrome(latest), OS=Windows")
68-
System.out.printf("Testing: %s%n", description);
69-
// Your test implementation here
69+
// scenarioDesc: e.g., "Browser=Chrome(latest), OS=Windows"
70+
// browserValue, osValue: concrete values for the current test case (e.g., "latest", "Windows")
71+
public void testFeatureWithVariedConfigs(String scenarioDesc, Object browserValue, Object osValue) {
72+
System.out.printf("Testing: %s - Browser: %s, OS: %s%n", scenarioDesc, browserValue, osValue);
73+
// Your actual test automation logic using browserValue and osValue would go here...
7074
}
7175
}
7276
```
@@ -83,9 +87,53 @@ public class JPWiseQuickDemoTest {
8387

8488
## Installation
8589

90+
### Using GitHub Packages (Recommended)
91+
92+
JPWise is available through GitHub Packages. To use it, you need to configure Maven to use the GitHub Packages repository for `io.github.mike-d-davydov`.
93+
94+
1. **Authenticate to GitHub Packages**: Ensure your Maven `settings.xml` (usually in `~/.m2/settings.xml`) is configured with your GitHub username and a Personal Access Token (PAT) with `read:packages` scope.
95+
96+
```xml
97+
<settings>
98+
<servers>
99+
<server>
100+
<id>github</id>
101+
<username>YOUR_GITHUB_USERNAME</username>
102+
<password>YOUR_GITHUB_PAT</password>
103+
</server>
104+
</servers>
105+
</settings>
106+
```
107+
108+
2. **Add the repository to your `pom.xml`**:
109+
If your project doesn't already resolve from GitHub Packages for this owner, you might need to add the repository. However, often just the dependency is enough if the parent POM or `settings.xml` is configured globally.
110+
111+
```xml
112+
<repositories>
113+
<repository>
114+
<id>github</id>
115+
<name>GitHub mike-d-davydov Apache Maven Packages</name>
116+
<url>https://maven.pkg.github.com/mike-d-davydov/jpwise</url>
117+
<snapshots><enabled>true</enabled></snapshots>
118+
</repository>
119+
</repositories>
120+
```
121+
*(Note: For snapshot versions, ensure the snapshot repository URL is correctly configured if different or ensure your Maven settings allow snapshot resolution from this repository.)*
122+
123+
124+
3. **Add the dependency to your `pom.xml`**:
125+
126+
```xml
127+
<dependency>
128+
<groupId>io.github.mike-d-davydov</groupId>
129+
<artifactId>jpwise</artifactId>
130+
<version>1.0-SNAPSHOT</version> <!-- Or the latest released version -->
131+
</dependency>
132+
```
133+
86134
### Using JitPack
87135

88-
Add the JitPack repository to your `pom.xml`:
136+
Alternatively, you can use JitPack. Add the JitPack repository to your `pom.xml`:
89137

90138
```xml
91139
<repositories>
@@ -102,7 +150,7 @@ Add the dependency:
102150
<dependency>
103151
<groupId>com.github.mike-d-davydov</groupId>
104152
<artifactId>jpwise</artifactId>
105-
<version>v1.0.0</version>
153+
<version>1.0-SNAPSHOT</version> <!-- Or a specific tag like v1.0.0 -->
106154
</dependency>
107155
```
108156

@@ -118,9 +166,9 @@ Then add the dependency to your project:
118166

119167
```xml
120168
<dependency>
121-
<groupId>com.github.mike-d-davydov</groupId>
169+
<groupId>io.github.mike-d-davydov</groupId>
122170
<artifactId>jpwise</artifactId>
123-
<version>1.0.0</version>
171+
<version>1.0-SNAPSHOT</version>
124172
</dependency>
125173
```
126174

@@ -131,26 +179,23 @@ The most concise way to use JPWise is through the builder API:
131179
```java
132180
import io.github.mikeddavydov.jpwise.JPWise;
133181
import io.github.mikeddavydov.jpwise.core.SimpleValue;
182+
import io.github.mikeddavydov.jpwise.core.EquivalencePartition;
183+
import io.github.mikeddavydov.jpwise.core.CombinationTable;
184+
import io.github.mikeddavydov.jpwise.core.Combination;
185+
import java.util.Arrays;
134186

135187
// Generate combinations
136188
CombinationTable results = JPWise.builder()
137-
.parameter("browser",
138-
SimpleValue.of("Chrome"),
139-
SimpleValue.of("Firefox"))
140-
.parameter("os",
141-
SimpleValue.of("Windows", "11"),
142-
SimpleValue.of("macOS", "14.1"))
189+
.parameter("browser", SimpleValue.of("Chrome"), SimpleValue.of("Firefox")) // Inlined
190+
.parameter("os", SimpleValue.of("Windows", "11"), SimpleValue.of("macOS", "14.1")) // Inlined
143191
.generatePairwise();
144192

145-
// Alternatively, to generate a limited set of all combinations (combinatorial):
146-
// CombinationTable combinatorialResults = JPWise.builder()...generateCombinatorial(4);
147-
148193
// Use the results
149194
for (Combination combination : results.combinations()) {
150195
EquivalencePartition browserEP = combination.getValues()[0];
151196
EquivalencePartition osEP = combination.getValues()[1];
152-
System.out.printf("Browser: %s, OS: %s%n",
153-
browserEP.getValue(),
197+
System.out.printf("Browser: %s, OS: %s%n",
198+
browserEP.getValue(),
154199
osEP.getValue());
155200
}
156201
```
@@ -176,7 +221,10 @@ JPWise supports three types of equivalence partitions:
176221

177222
3. **`CyclingPartition`**: For cycling through values
178223
```java
179-
CyclingPartition versions = CyclingPartition.of("Firefox ESR", "115.0.1esr", "115.0.2esr", "115.0.3esr");
224+
CyclingPartition versions = CyclingPartition.of(
225+
"Firefox ESR Cycle",
226+
Arrays.asList("115.0.1esr", "115.0.2esr", "115.0.3esr")
227+
);
180228
```
181229

182230
### Compatibility Rules
@@ -218,7 +266,7 @@ public void testBrowserCompatibility(String description, String browser, String
218266
}
219267
```
220268

221-
For a complete example with parameter definitions, compatibility rules, and detailed test implementation, please refer to the test classes within the [src/test/java/io/github/mikeddavydov/jpwise/algo/](./src/test/java/io/github/mikeddavydov/jpwise/algo/) directory, such as [CombinatorialAlgorithmTest.java](./src/test/java/io/github/mikeddavydov/jpwise/algo/CombinatorialAlgorithmTest.java) or [PairwiseAlgorithmTest.java](./src/test/java/io/github/mikeddavydov/jpwise/algo/PairwiseAlgorithmTest.java) which demonstrate various usages.
269+
For a complete example with parameter definitions, compatibility rules, and detailed test implementation, see `JpWiseDataProviderDemoTest.java` in the test sources.
222270

223271
## Architecture
224272

@@ -263,7 +311,4 @@ JPWise uses specific terminology to describe its concepts:
263311
- Improved documentation and examples
264312
- Added TestNG DataProvider integration
265313
- Added support for dynamic value generation
266-
- Standardized terminology
267-
268-
269-
314+
- Standardized terminology

0 commit comments

Comments
 (0)