119 lines
3.0 KiB
Markdown
119 lines
3.0 KiB
Markdown
# ABE — CLI & CI/CD Integration Specification
|
|
|
|
## CLI Entry Point
|
|
|
|
File: `src/cli.ts`
|
|
Script in package.json: `"abe": "ts-node src/cli.ts"`
|
|
Global after install: `npx abe` or `abe` if installed globally.
|
|
|
|
## CLI Usage
|
|
```bash
|
|
# Basic run
|
|
abe run --url http://localhost:3000
|
|
|
|
# With auth
|
|
abe run --url http://app.com \
|
|
--auth-type login_flow \
|
|
--login-url http://app.com/login \
|
|
--username test@app.com \
|
|
--password secret
|
|
|
|
# With scope limits
|
|
abe run --url http://app.com \
|
|
--max-states 30 \
|
|
--max-depth 4 \
|
|
--allowed-domains app.com
|
|
|
|
# CI mode: exit 1 if any anomaly found
|
|
abe run --url http://localhost:3000 --fail-on-anomaly
|
|
|
|
# CI mode: exit 1 only on high/critical anomalies
|
|
abe run --url http://localhost:3000 --fail-on-severity high
|
|
|
|
# Output formats
|
|
abe run --url http://localhost:3000 --output json # prints JSON summary to stdout
|
|
abe run --url http://localhost:3000 --output junit # generates junit.xml for CI
|
|
|
|
# Connect to a running ABE server instead of running inline
|
|
abe run --url http://localhost:3000 --server http://abe-server:3001 --api-key mykey
|
|
```
|
|
|
|
## Exit Codes
|
|
|
|
- 0 → exploration complete, no anomalies (or no anomalies above threshold)
|
|
- 1 → anomalies found above threshold
|
|
- 2 → exploration failed (target unreachable, auth failed, etc.)
|
|
|
|
## stdout JSON output (--output json)
|
|
```json
|
|
{
|
|
"sessionId": "sess_abc123",
|
|
"url": "http://localhost:3000",
|
|
"duration_ms": 45000,
|
|
"states_visited": 12,
|
|
"anomalies": [
|
|
{
|
|
"id": "anom_xyz",
|
|
"type": "http_error",
|
|
"severity": "high",
|
|
"description": "Form returns 500 on empty email",
|
|
"report_path": "reports/anom_xyz/report.json"
|
|
}
|
|
],
|
|
"exit_code": 1
|
|
}
|
|
```
|
|
|
|
## JUnit XML output (--output junit)
|
|
|
|
Generates `abe-results.xml` compatible with Jenkins, GitHub Actions, GitLab CI:
|
|
- Each anomaly = one failing test case
|
|
- Each explored state = one passing test case
|
|
|
|
## GitHub Actions Example Workflow
|
|
|
|
Create file: `.github/workflows/abe-example.yml` in the repo:
|
|
```yaml
|
|
name: ABE Exploratory Testing
|
|
|
|
on:
|
|
push:
|
|
branches: [main]
|
|
pull_request:
|
|
|
|
jobs:
|
|
explore:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
|
|
- name: Start application
|
|
run: docker-compose up -d app
|
|
# assumes the project has a docker-compose with the target app
|
|
|
|
- name: Wait for app
|
|
run: npx wait-on http://localhost:3000 --timeout 30000
|
|
|
|
- name: Run ABE
|
|
run: |
|
|
npm install -g abe-explorer # or: npx abe
|
|
abe run \
|
|
--url http://localhost:3000 \
|
|
--max-states 30 \
|
|
--fail-on-severity high \
|
|
--output junit
|
|
|
|
- name: Upload results
|
|
if: always()
|
|
uses: actions/upload-artifact@v4
|
|
with:
|
|
name: abe-reports
|
|
path: reports/
|
|
|
|
- name: Publish test results
|
|
if: always()
|
|
uses: EnricoMi/publish-unit-test-result-action@v2
|
|
with:
|
|
files: abe-results.xml
|
|
```
|