Skip to content

Commit 8f2b7c9

Browse files
pflynn-virtrupflynn-virtru
committed
[run.py] Enhance SDK server setup, certificate generation, and Keycloak readiness checks
- Improved SDK server build and start logic with better error handling. - Added Keycloak readiness validation to ensure smooth service provisioning. - Updated encryption/decryption flow in Go SDK server to support base64 input/output. - Simplified Python `run.py` script for managing test workflows and service setup.
1 parent 4a44f77 commit 8f2b7c9

File tree

9 files changed

+665
-117
lines changed

9 files changed

+665
-117
lines changed

‎.gitignore

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,84 @@ test-results/
3939
work/
4040
.env
4141
coverage_reports/
42+
43+
# SDK Server build artifacts
44+
xtest/sdk/go/server/server
45+
xtest/sdk/go/server/go.sum
46+
xtest/sdk/java/server/target/
47+
xtest/sdk/js/package.json
48+
xtest/sdk/js/package-lock.json
49+
xtest/sdk/js/node_modules/
50+
51+
# SDK build directories
52+
xtest/sdk/go/dist/
53+
xtest/sdk/java/dist/
54+
xtest/sdk/js/dist/
55+
56+
# SDK source checkouts (git worktrees)
57+
xtest/sdk/go/src/
58+
xtest/sdk/java/src/
59+
xtest/sdk/js/src/
60+
61+
# Maven build files
62+
*.jar
63+
*.war
64+
*.ear
65+
*.class
66+
target/
67+
68+
# Go build files
69+
*.exe
70+
*.dll
71+
*.so
72+
*.dylib
73+
*.test
74+
*.out
75+
vendor/
76+
77+
# Node/npm files
78+
npm-debug.log*
79+
yarn-debug.log*
80+
yarn-error.log*
81+
package-lock.json
82+
pnpm-lock.yaml
83+
84+
# IDE files
85+
*.swp
86+
*.swo
87+
*~
88+
.project
89+
.classpath
90+
.settings/
91+
92+
# OS files
93+
Thumbs.db
94+
ehthumbs.db
95+
Desktop.ini
96+
97+
# Test output
98+
*.log
99+
test-output/
100+
test-reports/
101+
102+
# Python bytecode
103+
*.pyo
104+
*.pyd
105+
__pycache__/
106+
*.egg-info/
107+
dist/
108+
build/
109+
.eggs/
110+
111+
# Environment files
112+
*.env.local
113+
*.env.development.local
114+
*.env.test.local
115+
*.env.production.local
116+
117+
# Temporary files
118+
*.tmp
119+
*.bak
120+
*.backup
121+
tmp/
122+
temp/

‎AGENTS.md

Lines changed: 235 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
# AGENTS.md
2+
3+
## Project Overview
4+
5+
OpenTDF Tests Repository - Comprehensive testing suite for the OpenTDF (Trusted Data Format) platform. Primary focus is cross-SDK compatibility testing to ensure encryption/decryption works correctly across Go, Java, JavaScript, and Swift implementations.
6+
7+
### Important Documentation
8+
- **[REQUIREMENTS.md](./REQUIREMENTS.md)** - Phase 1 requirements for Test Framework Modernization
9+
- **[DESIGN.md](./DESIGN.md)** - Technical design specification (keep in sync with implementation)
10+
- **[TODO.md](./TODO.md)** - Comprehensive handover document maintaining context between sessions
11+
12+
## Development Environment Setup
13+
14+
### Initial Setup
15+
```bash
16+
# Complete environment setup
17+
./run.py setup
18+
19+
# This will:
20+
# - Create Python virtual environment with uv
21+
# - Install Python dependencies
22+
# - Clone/update platform services
23+
# - Build all SDKs (Go, Java, JavaScript)
24+
# - Build SDK test servers
25+
# - Generate KAS certificates
26+
```
27+
28+
### Python Environment
29+
- Python 3.13.6 required
30+
- Virtual environment managed by `uv`
31+
- Activate before development: `source .venv/bin/activate`
32+
33+
## Project Structure
34+
35+
```
36+
tests/
37+
├── xtest/ # Main cross-SDK compatibility test suite (pytest)
38+
├── work/ # Temporary files and test artifacts (auto-created)
39+
│ └── platform/ # Cloned platform services
40+
├── vulnerability/ # Playwright security tests
41+
├── performance/ # Performance benchmarking
42+
└── run.py # Main test orchestration script
43+
```
44+
45+
### Key Components
46+
- **xtest/** - Cross-SDK pytest suite validating encryption/decryption
47+
- **work/platform/** - Go-based platform services (KAS, policy, authorization)
48+
- **xtest/sdk/** - SDK servers for testing (Go, Java, JavaScript)
49+
- **xtest/otdfctl/** - Go CLI tool for TDF operations
50+
51+
## Code Style Guidelines
52+
53+
### Python (Primary Test Language)
54+
- Follow PEP 8
55+
- Use type hints where practical
56+
- Fixtures for shared test resources
57+
- Descriptive test names: `test_<feature>_<scenario>_<expected_result>`
58+
59+
### Go SDK Server
60+
- Standard Go formatting (`go fmt`)
61+
- Error handling: return errors, don't panic
62+
- Use structured logging
63+
64+
### Java SDK Server
65+
- Follow Spring Boot conventions
66+
- Use SLF4J for logging
67+
- Prefer `var` for local variables with obvious types
68+
69+
### JavaScript SDK Server
70+
- ES6 modules
71+
- Async/await over callbacks
72+
- Express.js middleware patterns
73+
74+
## Testing Instructions
75+
76+
### Quick Start
77+
```bash
78+
# Run all tests with parallel execution (recommended)
79+
./run.py test
80+
81+
# Run specific test suite
82+
pytest xtest/test_tdfs.py -v
83+
84+
# Test specific SDKs
85+
pytest --sdks go java js
86+
87+
# Test specific formats
88+
pytest --containers nano ztdf
89+
```
90+
91+
### Test Categories
92+
1. **Container Formats**: nano (NanoTDF), ztdf (TDF3), ztdf-ecwrap
93+
2. **SDKs**: Go, Java, JavaScript, Swift
94+
3. **Policies**: ABAC, assertions, metadata
95+
4. **Scenarios**: Encryption/decryption, policy enforcement, multi-KAS
96+
97+
### Key Test Files
98+
- `test_tdfs.py` - Core TDF3 format testing
99+
- `test_nano_roundtrip.py` - NanoTDF cross-SDK compatibility
100+
- `test_abac_roundtrip.py` - Attribute-based access control
101+
- `test_assertions.py` - Assertion and metadata handling
102+
103+
### Debugging Tests
104+
```bash
105+
# Verbose output
106+
pytest -v
107+
108+
# Keep test artifacts for debugging
109+
pytest --keep-artifacts
110+
111+
# Inspect TDF files
112+
xtest/otdfctl inspect file.tdf
113+
114+
# Check platform logs
115+
docker compose -f work/platform/docker-compose.yaml logs -f
116+
```
117+
118+
## Development Workflows
119+
120+
### Building Components
121+
```bash
122+
# Build platform services
123+
cd work/platform && make build
124+
125+
# Build all SDKs
126+
cd xtest/sdk && make all
127+
128+
# Build individual SDK servers
129+
cd xtest/sdk/go/server && go build
130+
cd xtest/sdk/java/server && mvn package
131+
cd xtest/sdk/js && npm install
132+
```
133+
134+
### Running Platform Services
135+
```bash
136+
cd work/platform
137+
go run ./service start
138+
go run ./service provision keycloak # Setup auth
139+
```
140+
141+
## Temporary File Management
142+
143+
The test suite uses pytest's temporary directory management:
144+
145+
- **`tmp_path`** fixture: Function-scoped, isolated per test
146+
- **`work_dir`** fixture: Session-scoped, for cross-test artifacts
147+
- **Base directory**: `work/` at project root (IDE-visible)
148+
- **Cleanup**: Failed test dirs retained for debugging (3 runs max)
149+
- **Parallel safety**: Full isolation with `pytest-xdist`
150+
151+
Example structure:
152+
```
153+
work/
154+
├── test_abac_test_key_mapping0/ # Per-test directory
155+
├── test_tdfs_test_roundtrip1/
156+
└── opentdf_work0/ # Session-scoped shared
157+
```
158+
159+
## Configuration
160+
161+
- **pytest**: Configured in `pyproject.toml` under `[tool.pytest.ini_options]`
162+
- **Platform**: Environment variables in `test.env`
163+
- **OpenTDF**: Configuration in `opentdf.yaml`
164+
165+
## Important Context for AI Agents
166+
167+
### Multi-SDK Testing
168+
Tests verify the same encryption/decryption scenarios work across all SDK implementations. When making changes:
169+
1. Check cross-SDK compatibility
170+
2. Validate both encryption and decryption paths
171+
3. Test multiple container formats
172+
4. Ensure BATS tests pass for end-to-end workflows
173+
174+
### Fixture System
175+
pytest fixtures provide:
176+
- KAS keys and certificates
177+
- Namespaces and attributes
178+
- Policy configurations
179+
- Temporary directories
180+
181+
### Dependencies
182+
- Platform services must be running (via Docker Compose)
183+
- Keycloak provides OIDC authentication
184+
- Each SDK has its own build requirements
185+
186+
### Common Issues
187+
- **Import errors**: Run `./run.py setup` to rebuild SDKs
188+
- **Connection refused**: Ensure platform services are running
189+
- **Test isolation**: Use appropriate fixtures for temp files
190+
- **Parallel test failures**: Check for shared state violations
191+
192+
## Contribution Guidelines
193+
194+
### Before Committing
195+
1. Run tests: `./run.py test`
196+
2. Update DESIGN.md if architecture changes
197+
3. Update TODO.md with session context
198+
4. Ensure all SDK servers build successfully
199+
200+
### Commit Messages
201+
Format: `[component] Brief description`
202+
203+
Examples:
204+
- `[xtest] Add cross-SDK encryption test for large files`
205+
- `[sdk/go] Fix TDF decryption error handling`
206+
- `[framework] Update pytest fixtures for parallel execution`
207+
208+
### Pull Request Process
209+
1. All tests must pass
210+
2. Document breaking changes
211+
3. Update relevant .md files
212+
4. Ensure .gitignore covers new artifacts
213+
214+
## Agent-Specific Instructions
215+
216+
### Do's
217+
- Always run `./run.py setup` after major changes
218+
- Keep DESIGN.md in sync with implementation
219+
- Use existing fixtures for test resources
220+
- Follow established patterns in existing tests
221+
- Test across multiple SDKs when modifying core functionality
222+
223+
### Don'ts
224+
- Don't hardcode paths - use fixtures
225+
- Don't skip the setup phase
226+
- Don't modify generated SDK source in `src/` directories
227+
- Don't commit build artifacts (check .gitignore)
228+
- Don't assume single SDK - test cross-compatibility
229+
230+
### When Stuck
231+
1. Check TODO.md for context
232+
2. Review REQUIREMENTS.md for goals
233+
3. Examine existing tests for patterns
234+
4. Use `pytest --fixtures` to understand available resources
235+
5. Inspect logs in `work/platform/` for service issues

‎CLAUDE.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

‎GEMINI.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

0 commit comments

Comments
 (0)