https://github.com/vitorsalgado/puma4j
Easy and convenient way to load file resources into your tests using only annotations.
https://github.com/vitorsalgado/puma4j
java java-library junit junit5-extension test testing-tools
Last synced: 9 months ago
JSON representation
Easy and convenient way to load file resources into your tests using only annotations.
- Host: GitHub
- URL: https://github.com/vitorsalgado/puma4j
- Owner: vitorsalgado
- License: mit
- Created: 2021-09-09T16:35:03.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-01-27T21:28:22.000Z (over 1 year ago)
- Last Synced: 2025-07-27T08:49:45.132Z (11 months ago)
- Topics: java, java-library, junit, junit5-extension, test, testing-tools
- Language: Java
- Homepage: https://search.maven.org/search?q=puma4j
- Size: 456 KB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
Puma4j
Easy and convenient way to load file resources into your tests using only annotations.
## Overview
Puma4j provides a convenient and easier way to load and parse file resources in your **JUnit 5** tests using just a couple of **annotations** :)
## Installation
Using Gradle:
```gradle
testImplementation "io.github.vitorsalgado.puma4j:puma4j-junit5-extension:4.0.4"
```
or Maven:
```xml
io.github.vitorsalgado.puma4j
puma4j-junit5-extension
4.0.4
test
```
## How It Works
**Puma4j**, when enabled, detects fields or parameters annotated with `@Res` and inject resource values based on annotated element type, resource extension and
any custom unmarshaller added.
You can use `String` and `byte[]` for all types of resources.
Puma4j is also able to convert some resource types to object type representations:
- Json: Object types based on the json structure. It uses **Jackson ObjectMapper** and **Gson**. Defaults to **Jackson ObjectMapper**
- Yaml: Object types based on yaml structure. It uses **Jackson ObjectMapper**.
- Properties: Converts `.properties` files to java `Properties` class.
For custom **object conversions** use a custom **unmarshaller** using the annotation `@Use`, passing the class type of your custom unmarshaller implementation.
## Usage
First, annotate your JUnit 5 test classes with `@UsePuma4j`. Now you can use the annotation `@Res`
to inject resources on class fields and/or method parameters.
Take a look on the complete example below:
```java
@UsePuma4j
class UsageWithJUnit5 {
@Res("data.txt")
private static String staticTextData;
@Res("complex.json")
private List complexModelList;
@Res("complex-yml.yaml")
private List complexModelListFromYaml;
@Res("test.properties")
private Properties testProperties;
@Res("simple.json")
@Use(JsonTreeUnmarshaller.class)
private JsonNode simpleJsonTree;
@Test
void simpleTest(final @Res("simple.json") SimpleModel model) {
assertEquals(50, model.getAge());
assertEquals("no-one", model.getName());
}
public static class JsonTreeUnmarshaller implements Unmarshaller {
private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
@Override
public JsonNode unmarshal(final Args args) throws IOException {
return OBJECT_MAPPER.readTree(args.getInput());
}
}
}
```
## Features
### Forcing Jackson or Gson
For **json** files, the default parser is **Jackson ObjectMapper**. If you want to use **Gson** for a specific type use: `@UseGson`. If applied in the class
level, all json conversions will use Gson. You can use `@UseJackson` to keep using Object Mapper on specific resources.
### Custom Unmarshaller
You can use your custom **unmarshaller** implementation.
First, create a new class implementing the interface `Unmarshaller`.
Then, use the annotation `@Use(YourCustomUnmarshaller.class)` on the class, field or method level to use your new custom unmarshaller.
### Kotlin Delegate
You can load resources using a Kotlin delegate also. Look the example below:
```kotlin
private val simpleModel: SimpleModel by res("simple.json")
```
To use the delegate `res`, add the library below to your project:
```gradle
testImplementation "io.github.vitorsalgado.puma4j:puma4j-kotlin:4.0.4"
```
---
## Contributing
See [CONTRIBUTING](CONTRIBUTING.md) for more details.
## Contributors
Thanks goes to these wonderful people ✨:
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors)
specification. Contributions of any kind welcome!
## License
This project is [MIT Licensed](LICENSE).
