mirror of
https://github.com/qlik-oss/nebula.js.git
synced 2025-12-20 10:19:04 -05:00
273 lines
18 KiB
Markdown
273 lines
18 KiB
Markdown
# Spec Command Test Architecture
|
|
|
|
## Component Diagram
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ CI Workflow (ci.yml) │
|
|
│ │
|
|
│ ┌────────────┐ ┌──────────┐ ┌─────────────────┐ ┌────────────┐ │
|
|
│ │ build │→│ validate │ │ test-integration│ │test-create │ │
|
|
│ └────────────┘ └──────────┘ └─────────────────┘ └──────┬─────┘ │
|
|
│ │ │
|
|
└─────────────────────────────────────────────────────────────┼───────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────┐
|
|
│ nebula_create.sh Script │
|
|
│ │
|
|
│ Parameters: │
|
|
│ • PROJECT_NAME │
|
|
│ • PICASSO_TEMPLATE │
|
|
│ • MASHUP │
|
|
│ • INSTALL │
|
|
│ • BUILD │
|
|
│ • TEST │
|
|
│ • TYPESCRIPT ← New! │
|
|
│ • TEST_SPEC ← New! │
|
|
└──────────────┬──────────────────────────────┘
|
|
│
|
|
┌──────────────────────┴──────────────────────┐
|
|
│ │
|
|
▼ ▼
|
|
┌───────────────────────┐ ┌───────────────────────────┐
|
|
│ Existing Templates │ │ TypeScript Template │
|
|
│ │ │ (NEW!) │
|
|
│ • picasso/none │ │ │
|
|
│ • picasso/barchart │ │ Files: │
|
|
│ • mashup │ │ • PropertyDef.ts │
|
|
└───────────────────────┘ │ • nebula.config.js │
|
|
│ • tsconfig.json │
|
|
│ • package.json │
|
|
└─────────┬─────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────┐
|
|
│ Spec Command Test Flow │
|
|
│ │
|
|
│ 1. Create project │
|
|
│ 2. Link packages │
|
|
│ 3. Run: yarn run spec │
|
|
│ 4. Validate generated files │
|
|
│ 5. Run: yarn run build │
|
|
│ 6. Run: yarn run test:e2e │
|
|
│ 7. Upload artifacts │
|
|
└─────────┬───────────────────────┘
|
|
│
|
|
┌─────────────────────────┼─────────────────────────┐
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌──────────────────┐ ┌──────────────────────┐ ┌──────────────────┐
|
|
│ Schema File │ │ Defaults File │ │ Validation │
|
|
│ Generated │ │ Generated │ │ Results │
|
|
│ │ │ │ │ │
|
|
│ <name>- │ │ generated- │ │ • File exists │
|
|
│ properties. │ │ default- │ │ • Has $id │
|
|
│ schema.json │ │ properties.ts │ │ • Has defs │
|
|
│ │ │ │ │ • Valid TS │
|
|
└────────┬─────────┘ └───────────┬──────────┘ └────────┬─────────┘
|
|
│ │ │
|
|
└──────────────────────────┴───────────────────────┘
|
|
│
|
|
▼
|
|
┌───────────────────────┐
|
|
│ CI Artifacts │
|
|
│ Uploaded │
|
|
│ │
|
|
│ typescript-spec- │
|
|
│ generated/ │
|
|
└───────────────────────┘
|
|
```
|
|
|
|
## Data Flow
|
|
|
|
```
|
|
TypeScript Interface (PropertyDef.ts)
|
|
│
|
|
│ Contains JSDoc @default annotations
|
|
│
|
|
▼
|
|
┌─────────────────────────────────┐
|
|
│ nebula spec command │
|
|
│ │
|
|
│ Uses: │
|
|
│ • ts-json-schema-generator │
|
|
│ • nebula.config.js settings │
|
|
│ • tsconfig.json │
|
|
└────────┬────────────────────────┘
|
|
│
|
|
├──────────────┬────────────────┐
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
Parse TS Extract JSDoc Generate Schema
|
|
Interface @default tags Definitions
|
|
│ │ │
|
|
└──────┬───────┴────────────────┘
|
|
│
|
|
├─────────────────┬─────────────────┐
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
JSON Schema Defaults File Console Output
|
|
(validation) (TypeScript) (logs)
|
|
│ │ │
|
|
└─────────┬───────┴─────────────────┘
|
|
│
|
|
▼
|
|
Test Validation
|
|
│
|
|
├─── File existence checks
|
|
├─── Structure validation
|
|
├─── Content validation
|
|
└─── Build verification
|
|
│
|
|
▼
|
|
✓ Tests Pass
|
|
```
|
|
|
|
## Test Execution Flow
|
|
|
|
```
|
|
GitHub Push/PR
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ build job │ ← Builds all packages
|
|
│ yarn build │
|
|
└────────┬────────┘
|
|
│
|
|
├─── Upload workspace artifact
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ test-create job │ ← Downloads workspace
|
|
└────────┬────────┘
|
|
│
|
|
├─── Test 1: Picasso none template
|
|
│ └─ create, link, build, test
|
|
│
|
|
├─── Test 2: Picasso barchart template
|
|
│ └─ create, link, build, test
|
|
│
|
|
├─── Test 3: TypeScript template (NEW!)
|
|
│ └─ create, link, spec, validate, build, test
|
|
│
|
|
└─── Test 4: Mashup template
|
|
└─ create, link, build
|
|
```
|
|
|
|
## File Structure
|
|
|
|
```
|
|
nebula.js/
|
|
├── .github/
|
|
│ ├── workflows/
|
|
│ │ └── ci.yml ...................... Updated: Added TypeScript test step
|
|
│ └── scripts/
|
|
│ └── nebula_create.sh ............ Updated: Added spec testing logic
|
|
│
|
|
├── commands/
|
|
│ ├── create/
|
|
│ │ ├── command.js .................. Updated: Added --typescript option
|
|
│ │ ├── lib/
|
|
│ │ │ └── create.js ............... Updated: TypeScript template logic
|
|
│ │ └── templates/
|
|
│ │ └── sn/
|
|
│ │ ├── picasso/ ............ Existing templates
|
|
│ │ ├── none/ ............... Existing template
|
|
│ │ └── typescript/ ......... NEW! Complete template
|
|
│ │ ├── src/
|
|
│ │ │ ├── PropertyDef.ts
|
|
│ │ │ ├── index.js
|
|
│ │ │ ├── object-properties.js
|
|
│ │ │ └── meta.json
|
|
│ │ ├── test/
|
|
│ │ │ └── integration/
|
|
│ │ ├── _package.json
|
|
│ │ ├── tsconfig.json
|
|
│ │ ├── nebula.config.js
|
|
│ │ ├── _eslintrc.json
|
|
│ │ ├── _gitignore
|
|
│ │ └── README.md
|
|
│ │
|
|
│ └── spec/ ........................... Existing spec command
|
|
│ ├── command.js
|
|
│ └── lib/
|
|
│ ├── spec.js
|
|
│ └── init-config.js
|
|
│
|
|
├── docs/
|
|
│ └── spec-command-testing.md ......... NEW! Testing documentation
|
|
│
|
|
└── SPEC_TESTING_SUMMARY.md ............. NEW! Implementation summary
|
|
```
|
|
|
|
## Validation Points
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Validation Checklist │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ✓ Template Creation │
|
|
│ └─ All template files copied correctly │
|
|
│ │
|
|
│ ✓ Dependencies Installation │
|
|
│ ├─ yarn install succeeds │
|
|
│ └─ All @nebula.js packages linked │
|
|
│ │
|
|
│ ✓ Spec Command Execution │
|
|
│ ├─ yarn run spec completes without errors │
|
|
│ └─ No TypeScript compilation errors │
|
|
│ │
|
|
│ ✓ Generated Files │
|
|
│ ├─ generated-default-properties.ts exists │
|
|
│ ├─ <name>-properties.schema.json exists │
|
|
│ ├─ Schema has required "$id" field │
|
|
│ ├─ Schema has "definitions" object │
|
|
│ └─ Defaults file has TypeScript const declaration │
|
|
│ │
|
|
│ ✓ Build Process │
|
|
│ ├─ yarn run build succeeds │
|
|
│ └─ Dist files created │
|
|
│ │
|
|
│ ✓ Test Execution │
|
|
│ └─ yarn run test:e2e passes │
|
|
│ │
|
|
│ ✓ Artifacts │
|
|
│ └─ Generated files uploaded to CI │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Integration Points
|
|
|
|
```
|
|
┌──────────────────────────────────────────────────────────────┐
|
|
│ Existing Infrastructure │
|
|
│ │
|
|
│ ┌──────────────────┐ ┌──────────────────┐ │
|
|
│ │ nebula create │◄─────┤ New typescript │ │
|
|
│ │ command │ │ option │ │
|
|
│ └──────────────────┘ └──────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌──────────────────┐ ┌──────────────────┐ │
|
|
│ │ Template system │◄─────┤ TypeScript │ │
|
|
│ │ │ │ template folder │ │
|
|
│ └──────────────────┘ └──────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌──────────────────┐ ┌──────────────────┐ │
|
|
│ │ nebula_create.sh │◄─────┤ Spec test logic │ │
|
|
│ │ test script │ │ & validation │ │
|
|
│ └──────────────────┘ └──────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌──────────────────┐ ┌──────────────────┐ │
|
|
│ │ CI test-create │◄─────┤ New test step │ │
|
|
│ │ job │ │ & artifacts │ │
|
|
│ └──────────────────┘ └──────────────────┘ │
|
|
│ │
|
|
└──────────────────────────────────────────────────────────────┘
|
|
```
|