# {{NAME}} — API tests

Self-contained **Cucumber + JUnit 5 + REST Assured** project generated by
[L3git](https://L3Dev.com). You own this code — no proprietary runtime, no per-run fees.

## Run it

```bash
mvn test
```

That's the whole thing. Requires **JDK 17+** and **Maven**. The BDD report is written to
`target/cucumber-reports/cucumber.html` (open it in a browser); machine-readable results are in
`target/surefire-reports/` (JUnit XML) and `target/cucumber-reports/cucumber.json`.

Point the tests at an environment without editing code:

```bash
mvn test -Dapi.baseUri=https://api.example.com     # base URL for relative paths
mvn test -Dtest.forkCount=1C                        # run tests in parallel (1 JVM per CPU core)
```

## Secrets (tokens / keys / auth)

Tokens are referenced in the tests as `${NAME}` and resolved at runtime - they are **never** written
into the `.feature` or step files. Provide the real values one of three ways:

- **`secrets.properties`** (gitignored) - a `NAME=value` file in the project root. If you generated
  with secrets set, it's already here with real values. Otherwise copy `secrets.properties.example`
  to `secrets.properties` and fill it in. Point elsewhere with `mvn test -Dl3git.secrets=/path/to/file`.
- **Environment variables** for CI: `L3GIT_SECRET_<NAME>=value` (e.g. `L3GIT_SECRET_CLANSTOP_TOKEN`).
  An env var whose name matches a key in `secrets.properties` overrides that value.

`secrets.properties.example` is safe to commit (placeholders only); `secrets.properties` is gitignored.

## Reporting & integrations (optional)

Every run writes results locally with **no setup**:

- **Cucumber HTML** — `target/cucumber-reports/cucumber.html` (open in a browser)
- **Allure results** — `target/allure-results/`. View a rich report with the Allure CLI:
  ```bash
  allure serve target/allure-results
  ```
  Install the CLI once: `scoop install allure` (Windows), `brew install allure` (macOS),
  or download from https://github.com/allure-framework/allure2/releases.

To push a pass/fail summary or results to **Slack, Microsoft Teams, TestRail, or Xray**, copy
`reporting.properties.example` to `reporting.properties` (gitignored) and fill in **only** the
integrations you use, then after a run:

```bash
mvn test
java -cp target/test-classes com.example.support.TestReporter
```

The reporter reads the JUnit XML and pushes to each configured target; unconfigured ones (and
air-gapped runs) are skipped. Pure JDK — no extra dependency.

| Integration | You need | Notes |
|---|---|---|
| **Slack** | an Incoming Webhook URL | posts a pass/fail summary + up to 10 failures |
| **Teams** | an Incoming Webhook URL | use the classic *Incoming Webhook* connector |
| **TestRail** | instance URL, email, API key, an existing run id | put the case id in the **scenario name** (e.g. `Scenario: C1234 …`) |
| **Xray** | Cloud import URL + Bearer token (or Server/DC URL + auth) | imports the JUnit XML as a Test Execution |

In CI, set the same values as `REPORT_*` secrets instead of a file — the generated
`.github/workflows/ci.yml` and `Jenkinsfile` already run the reporter for you.

## Layout

```
{{ARTIFACT}}/
  pom.xml                                  Maven build (Cucumber + JUnit + REST Assured only)
  Jenkinsfile                              one-click Jenkins pipeline
  .github/workflows/ci.yml                 GitHub Actions (runs on every push)
  {{ARTIFACT}}.aaproj                       re-import this project into L3git (add UI steps, etc.)
  reporting.properties.example             copy to reporting.properties for Slack/Teams/TestRail/Xray
  .gitignore
  src/test/
    java/com/example/support/              shipped helpers: ApiContext, TestReporter, LoadRunner,
                                           MockService, SecurityScan, ...
    java/{{PKGPATH}}/                       {{RUNNERCLASS}} (JUnit runner) + step definitions
    resources/features/                    the .feature files (edit these to change the scenarios)
    resources/allure.properties            points Allure at target/allure-results
```

## Put it in git + CI

```bash
git init && git add . && git commit -m "API tests from L3git"
git branch -M main
git remote add origin <your-repo-url>
git push -u origin main
```

- **GitHub / GitLab:** `.github/workflows/ci.yml` runs `mvn test` on every push automatically.
- **Jenkins:** create a *Pipeline from SCM* job pointing at this repo — it uses the `Jenkinsfile`
  (assumes Maven + JDK 17 on the agent). Install the *HTML Publisher* plugin and uncomment the
  `publishHTML` line in the `Jenkinsfile` to show the Cucumber report in the build sidebar.

## Combine with browser (UI) tests

This project ships an `{{ARTIFACT}}.aaproj` sidecar. In **L3git UI** (the browser recorder), record a
browser flow, click **Import API project**, and browse to that `.aaproj` — its API steps are appended to
your recording, so a single generated project runs your UI and API steps together.

Regenerate anytime from **L3git API**.
